161 lines
5.6 KiB
Markdown
161 lines
5.6 KiB
Markdown
# 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.
|