102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
# Decision Checklist (Gating Artifact)
|
|
|
|
This file records decisions that must be resolved before moving forward with
|
|
backend integration. It is the gating artifact for Phase 0/1.
|
|
|
|
---
|
|
|
|
## Phase 0 — Conformance Harness + Determinism
|
|
|
|
### Conformance Scope
|
|
|
|
* Tier 0 MUST-pass specs (backend/store focus):
|
|
* `ASL/1-CORE`
|
|
* `ASL/1-STORE`
|
|
* `ENC/ASL1-CORE`
|
|
* `HASH/ASL1`
|
|
* `TGK/1-CORE`
|
|
* `ENC/TGK1-EDGE/1`
|
|
* `TGK/STORE/1`
|
|
* Tier 1 MUST-pass specs (index/log + optional provenance):
|
|
* `ASL/LOG/1`
|
|
* `ENC/ASL-LOG/1`
|
|
* `ASL/1-CORE-INDEX`
|
|
* `ENC/ASL-CORE-INDEX/1`
|
|
* `ASL/STORE-INDEX/1`
|
|
* `ASL/INDEX-ACCEL/1`
|
|
* `ASL/FEDERATION/1` and `ASL/FEDERATION-REPLAY/1` (if federation is in scope)
|
|
* `TGK/PROV/1` (if provenance operators are surfaced)
|
|
|
|
Notes:
|
|
* The legacy filesystem store (`asl_store_fs`) is not a Tier 1 conformance target once index/log is used.
|
|
* PEL specs are implemented and tested in this repo, but they are not required for the Phase 0/1 backend gate unless the surface is shipped as part of the backend.
|
|
|
|
### TGK/STORE Equivalence Definition
|
|
|
|
* Exact definition of “same result” across backends:
|
|
* For a fixed `GraphStoreConfig` and snapshot where `(Artifacts, config.tgk_profiles)` are equal, all `TGK/STORE/1` operations must return identical results per `TGK/STORE-DET/1`.
|
|
* `resolve_edge(ref)` returns the same `EdgeBody` or the same error code.
|
|
* `edges_from`, `edges_to`, `edges_incident` return identical `GraphEdgeView` lists (same elements in the same order).
|
|
* If implemented, `neighbors` returns identical `Node` lists (same elements in the same order).
|
|
* If implemented, `scan_edges` enumerates the same edges with identical per-page ordering; `PageToken` bytes may differ but must represent the same position in the canonical ordering.
|
|
* Ordering requirements (explicitly enumerated):
|
|
* Edge ordering is canonical and global: ascending lexicographic order of `order_key(edge_ref) = hash_id_bytes || digest_bytes`, with `hash_id` as big-endian `u16` (`TGK/STORE-EDGE-ORDER/1`).
|
|
* Neighbor ordering is canonical: ascending lexicographic order of `(hash_id, digest)` with the same `u16` big-endian encoding (`TGK/STORE-NEIGHBORS/1`).
|
|
* Pagination/scan stability rules:
|
|
* `scan_edges` must enumerate each matching edge exactly once and preserve the canonical per-page ordering.
|
|
* Snapshot stability across pages is optional; if not stable, the implementation must still preserve per-call ordering and enumeration semantics for the snapshot used by that call.
|
|
|
|
### Error Model Mapping Policy
|
|
|
|
* Canonical internal error taxonomy:
|
|
* ASL store errors: `AMDUAT_ASL_STORE_ERR_INTEGRITY`, `AMDUAT_ASL_STORE_ERR_UNSUPPORTED`, `AMDUAT_ASL_STORE_ERR_NOT_FOUND`, `AMDUAT_ASL_STORE_ERR_IO`.
|
|
* TGK store errors: `GS_ERR_NOT_EDGE`, `GS_ERR_ARTIFACT_ERROR`, `GS_ERR_UNSUPPORTED`, `GS_ERR_INTEGRITY`.
|
|
* Adapter-specific error mapping rules:
|
|
* `ASL/1-STORE` specifies `ERR_NOT_FOUND`, `ERR_INTEGRITY`, `ERR_UNSUPPORTED`. I/O/auth failures are out of scope for the spec; in this repo they map to `AMDUAT_ASL_STORE_ERR_IO`.
|
|
* `TGK/STORE/1` requires artifact-layer conflicts during `resolve_edge` to surface as `GS_ERR_ARTIFACT_ERROR` (not `GS_ERR_INTEGRITY`).
|
|
* `GS_ERR_NOT_EDGE` is returned when a reference resolves to an Artifact that is not a TGK edge under the active profile set.
|
|
* Required error tests:
|
|
* ASL: `get` on missing ref → `ERR_NOT_FOUND`.
|
|
* ASL: `put` collision (same ref, different artifact) → `ERR_INTEGRITY`.
|
|
* ASL: unsupported config or hash/profile mismatch → `ERR_UNSUPPORTED`.
|
|
* ASL: adapter I/O faults → `ERR_IO` (non-normative but required for harness).
|
|
* TGK: `resolve_edge` non-edge artifact → `GS_ERR_NOT_EDGE`.
|
|
* TGK: `resolve_edge` artifact-layer integrity failure → `GS_ERR_ARTIFACT_ERROR`.
|
|
* TGK: unsupported profile/encoding → `GS_ERR_UNSUPPORTED`.
|
|
|
|
---
|
|
|
|
## Phase 1 — ASL MinIO Adapter
|
|
|
|
### Object Key Layout
|
|
|
|
* Reference → bucket/key mapping: TBD (not specified by current specs/tests).
|
|
* Prefix sharding / directory fanout: TBD (not specified by current specs/tests).
|
|
|
|
### Metadata Policy
|
|
|
|
* Encoding/profile version tracking: TBD (not specified by current specs/tests).
|
|
* Metadata location (object metadata/tags/in-band): TBD (not specified by current specs/tests).
|
|
|
|
### Multipart Policy
|
|
|
|
* Multipart threshold: TBD (not specified by current specs/tests).
|
|
* Fidelity guarantees and validation: TBD (not specified by current specs/tests).
|
|
|
|
### Consistency Assumptions
|
|
|
|
* Read-after-write expectations: TBD (not specified by current specs/tests).
|
|
* Deployment modes covered by tests: TBD (not specified by current specs/tests).
|
|
|
|
### Security / Credentials
|
|
|
|
* Credential source and rotation policy: TBD (not specified by current specs/tests).
|
|
* Permission boundaries: TBD (not specified by current specs/tests).
|
|
|
|
---
|
|
|
|
## Status
|
|
|
|
* Phase 0 decisions: DRAFTED (spec-derived; requires owner confirmation)
|
|
* Phase 1 decisions: NOT STARTED
|