amduat/docs/phase0-1-execution-checklist.md

# 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.