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

4.8 KiB
Raw Blame History

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