niklas/amduat
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat/docs/phase0-1-execution-checklist.md

5.6 KiB
Raw Blame History

Phase 0/1 Execution Checklist

OSS Backend Enablement (MinIO-first)

0. Purpose

This checklist gates work so we do not start infrastructure integration until we can prove:

  • spec conformance holds across multiple backends,
  • deterministic ordering/replay invariants are testable,
  • error-model mappings are pinned down.

Phase 0 — Conformance Harness + Determinism Gates

0.1 Deliverables

  1. Multi-backend conformance runner (same test vectors, multiple backends)
  2. Golden dataset generator for ASL + TGK fixtures
  3. Deterministic equivalence suite:
  • ordering checks
  • replay equivalence
  • cross-backend observational equivalence (surface behavior)

0.2 Required decisions (turn into docs/decision-checklist.md)

  • Conformance test scope: which spec assertions are MUST-pass for Tier 0 vs Tier 1
  • Equivalence definition: what counts as “same result” for TGK/STORE operations (including ordering)
  • Error model mapping policy: canonical internal error types vs adapter-specific errors

0.3 Conformance harness: what to build

A) ASL/1-STORE conformance suite

  • Put/get round-trip for a set of canonical Artifacts
  • Idempotent put(Artifact) returns same Reference
  • get(Reference) exact artifact fidelity
  • NotFound behavior and error codes
  • Corruption detection behavior (if defined/expected by your layers)
  • Optional: latency-independent invariants (no timing assumptions)

B) TGK/STORE/1 conformance suite

  • Required operations per spec and error model
  • Deterministic ordering assertions (as spec defines)
  • “Same ASL state → same TGK answers” invariants
  • Cross-backend equivalence: mem vs fs vs asl_index_fs must match for the same fixture set

C) Replay determinism

  • Build a fixture log/index state
  • Replay into a fresh store
  • Assert equivalent outcomes (references returned, query results, ordering)

0.4 Acceptance criteria (Phase 0 gate)

  • ✅ Same fixture set passes on at least two existing backends:

  • asl_store_fs and asl_store_index_fs

  • tgk_store_mem and tgk_store_fs (or tgk_store_asl_index_fs)

  • ✅ Deterministic ordering checks are explicit and enforced

  • ✅ A “backend contract test” can be run by CI with a single command

0.5 Where this touches the repo (suggested structure)

  • tests/conformance/asl_store/*.c
  • tests/conformance/tgk_store/*.c
  • tests/fixtures/*.bin|*.json|*.asl (whatever your canonical fixture format is)
  • tools/amduat_conformance_run (small runner, like your other tools)

Phase 1 — ASL MinIO Adapter (Strict ASL/1-STORE)

1.1 Deliverables

  1. src/adapters/asl_store_s3_minio/asl_store_s3_minio.c (name as you prefer)
  2. Config + credentials plumbing for MinIO endpoint
  3. Full Phase 0 conformance suite passing against MinIO
  4. CI job (optional initially) that spins MinIO and runs conformance tests

1.2 Required decisions (Phase 1-specific)

  • Object key layout: how Reference maps to bucket/key (e.g., prefix sharding)
  • Metadata policy: do we store encoding/profile version as object metadata, tags, or in-band?
  • Multipart handling: threshold + exact fidelity guarantees
  • Read-after-write expectation: what you assume from MinIO deployment mode; what you test for

1.3 Adapter contract requirements (what must not change)

  • put(Artifact) -> Reference computed by core rules; adapter must not accept a caller-provided reference
  • get(Reference) -> Artifact | NotFound must return exact bytes for canonical decode
  • Error mapping must be stable (auth errors, NotFound, transient IO)

1.4 Failure modes to explicitly test (Phase 1 gate)

  • Bucket missing / permission denied
  • NotFound for unknown reference
  • Partial upload interruption (must not produce a “phantom success”)
  • Corrupt object payload (if detectable at decode step, ensure it surfaces as decode error)

1.5 Acceptance criteria (Phase 1 gate)

  • ✅ ASL/1-STORE conformance suite passes on MinIO
  • ✅ Cross-backend equivalence: MinIO results identical to index/fs for the same fixture set
  • ✅ Determinism: repeated put gives same reference, independent of environment

Missing interfaces and tests to write (concrete list)

A) Missing test harness capability (Phase 0)

  • A single abstraction that can run the same tests against:

  • asl_store_fs

  • asl_store_index_fs

  • future asl_store_minio

  • Same for TGK store adapters

  • A “golden fixture set” format (even if it’s just embedded byte arrays initially)

B) Deterministic ordering assertions (Phase 0)

The repo has lots of tests, but not:

  • a named suite that asserts ordering exactly as TGK/STORE defines
  • cross-backend “same query, same ordering” checks

C) Cross-backend equivalence harness (Phase 0)

You need an explicit mechanism that:

  • seeds the same ASL artifact set into multiple ASL backends
  • builds the same TGK projection inputs
  • runs the same TGK queries and diffs results

D) Adapter error normalization (Phase 0/1)

Define a small internal error taxonomy used by conformance tests so adapters can map:

  • NotFound
  • InvalidArtifact / decode error
  • PermissionDenied
  • TransientNetwork
  • Internal/Unknown

Without this, MinIO will “pass” but be impossible to reason about operationally.

What I would do next (lowest-risk sequence)

  1. Add docs/decision-checklist.md and fill only Phase 0/1 decisions (don’t boil the ocean).
  2. Implement conformance runner that can already test FS vs index/log backends (prove the harness works).
  3. Add deterministic ordering + replay equivalence tests.
  4. Only then implement asl_store_minio, using the harness as your guardrail.