# Substrate Contract v0.1 Status: Draft (repo-grounded) Scope: Defines the substrate surfaces and invariants implemented in this repo for v0.1. This contract is grounded in the current Amduat code and specs. Each requirement below lists file references that define the behavior. If a line is marked **NEW**, it is introduced in this change and implemented in code (referenced below). --- ## 1. Artifact Model (ASL/1-CORE) 1. **Artifact** = bytes + optional type tag; identity is content-addressed and immutable. Sources: `tier1/asl-1-core.md`, `include/amduat/asl/core.h`. 2. **Reference** = `(hash_id, digest)`; equality is hash-id + digest equality. Sources: `tier1/asl-1-core.md`, `include/amduat/asl/core.h`. 3. **Reference derivation** is based on canonical encoding + hash family; the API exposes this via `amduat_asl_ref_derive`. Sources: `tier1/asl-1-core.md`, `include/amduat/asl/ref_derive.h`. 4. **Hash family** in use for the stack is HASH/ASL1 (e.g., SHA-256). Sources: `tier1/hash-asl1.md`, `include/amduat/hash/asl1.h`. --- ## 2. Record Artifacts (ASL records) 1. ASL records are artifacts with type tag `TYPE_TAG_ASL_RECORD_1` and a payload encoding defined by `amduat_asl_record_encode_v1`/`decode_v1`. Sources: `include/amduat/asl/record.h`, `src/core/asl_record.c`. 2. **Record schema is required and ASCII**; payload may be empty but must be well-formed per the encoder rules. Sources: `src/core/asl_record.c`. 3. Records are stored and retrieved via `amduat_asl_record_store_put/get`, which wrap ASL store `put/get` over the encoded record bytes. Sources: `include/amduat/asl/record.h`, `src/core/asl_record.c`, `include/amduat/asl/store.h`. --- ## 3. Authoritative CAS + Index/Log (ASL/1-STORE) 1. The authoritative content-addressed store surface is `amduat_asl_store_t` with `put/get` and indexed variants `put_indexed/get_indexed`. Sources: `include/amduat/asl/store.h`. 2. Index/log state is represented as `amduat_asl_index_state_t` with `snapshot_id` and `log_position`. Sources: `include/amduat/asl/store.h`, `docs/index-log-api-sketch.md`. 3. Index/log record types are encoded as ASL log records, including artifact publish/unpublish, snapshot anchors, and tombstones. Sources: `include/amduat/enc/asl_log.h`, `tier1/asl-log-1.md`. 4. The filesystem index/log adapter implements the indexed store surface and emits log records with monotonically increasing `logseq` values. Sources: `include/amduat/asl/asl_store_index_fs.h`, `src/adapters/asl_store_index_fs/asl_store_index_fs.c`. --- ## 4. Derivation / Provenance Index 1. Derivation records bind an output artifact ref to a program ref, input refs, output index, and optional params/exec-profile. Sources: `include/amduat/asl/asl_derivation_index_fs.h`. 2. Deterministic derivation SIDs are computed from program + inputs (+ optional params/profile) via `amduat_pel_derivation_sid_compute`. Sources: `include/amduat/pel/derivation_sid.h`, `src/core/derivation_sid.c`. 3. The filesystem derivation index stores and lists derivation records by artifact reference. Sources: `include/amduat/asl/asl_derivation_index_fs.h`, `src/adapters/asl_derivation_index_fs/asl_derivation_index_fs.c`. --- ## 5. TGK Projection (Edges as Artifacts) 1. TGK edges are artifacts encoded via `ENC/TGK1-EDGE/1` with type tag `TYPE_TAG_TGK1_EDGE_V1` and edge bodies containing `from`, `to`, and `payload` refs. Sources: `include/amduat/enc/tgk1_edge.h`, `include/amduat/tgk/core.h`. 2. The TGK store surface provides graph queries (edges_from/to/scan/neighbors) over projected edges. Sources: `include/amduat/tgk/store.h`, `tier1/tgk-store-1.md`. 3. `amduat_tgk_store_asl_index_fs` implements a TGK projection over the ASL index/log store. Sources: `include/amduat/tgk/tgk_store_asl_index_fs.h`, `src/adapters/tgk_store_asl_index_fs/tgk_store_asl_index_fs.c`. --- ## 6. Deterministic Transforms (PEL) 1. PEL surface execution results are stored as artifacts with type tag `TYPE_TAG_PEL1_RESULT_1`, encoding `PEL_ENC_EXECUTION_RESULT_V1`. Sources: `include/amduat/enc/pel1_result.h`, `include/amduat/pel/surf.h`. 2. Trace DAGs and Program DAGs are encoded as artifacts with their respective type tags and encoding profiles. Sources: `include/amduat/enc/pel_trace_dag.h`, `include/amduat/enc/pel_program_dag.h`. 3. A minimal job record for deterministic transforms is the tuple: `(program_ref, input_refs, params_ref?, exec_profile?, result_ref, trace_ref?)`. Sources: `include/amduat/pel/surf.h`, `include/amduat/enc/pel1_result.h`, `include/amduat/pel/derivation_sid.h`. --- ## 7. Projection Hooks + Checkpoints (for external projectors) 1. **Projection feed cursor** is the ASL log position (`amduat_asl_log_position_t`) from `amduat_asl_index_state_t` and log records are read via the ASL log API. Sources: `include/amduat/asl/store.h`, `include/amduat/enc/asl_log.h`. 2. **NEW:** `amduat_asl_log_read_since` provides a cursor-based view of log records (records with `logseq` > cursor), enabling deterministic replay from a stable log position. Sources: `include/amduat/asl/log_cursor.h`, `src/near_core/asl/log_cursor.c`. 3. **NEW:** Projection checkpoints are encoded via `amduat_asl_projection_checkpoint_encode_v1/decode_v1` and stored as ASL record artifacts. The v0.1 schema is derived from `docs/projection-checkpoint-schema.md`. Sources: `include/amduat/asl/projection_checkpoint.h`, `src/near_core/asl/projection_checkpoint.c`, `docs/projection-checkpoint-schema.md`, `include/amduat/asl/record.h`. 4. **NEW (v0.1 convention):** Checkpoint record schema string is `projection/checkpoint` and the record payload is the v1 checkpoint encoding. Sources: `src/tools/amduat_scriptlab_adapter.c`, `tests/substrate/test_scriptlab_adapter.c`, `include/amduat/asl/record.h`. See `docs/projector-pattern.md` for the canonical cursor→project→checkpoint loop using `amduat_asl_log_read_since(store, after_logseq, limit)` and `projection/checkpoint` ASL records. --- ## 8. Non-Authoritative Projections 1. External projections (e.g., Elasticsearch, IPFS, JanusGraph) are derived and must remain observationally equivalent to the ASL/TGK substrate. Sources: `docs/amduat-oss-backend-proposal.md`, `docs/indexing-requirements-and-projections.md`. --- ## 9. Definition of Done (v0.1) 1. CAS, index/log store, and derivation index are available via the C surfaces and filesystem adapters. Sources: `include/amduat/asl/store.h`, `include/amduat/asl/asl_store_index_fs.h`, `include/amduat/asl/asl_derivation_index_fs.h`. 2. TGK projection is available over ASL index/log store. Sources: `include/amduat/tgk/tgk_store_asl_index_fs.h`. 3. PEL execution artifacts are produced and encoded as artifacts and can be linked via derivation SIDs. Sources: `include/amduat/pel/surf.h`, `include/amduat/enc/pel1_result.h`, `include/amduat/pel/derivation_sid.h`. 4. **NEW:** Projection feed cursor + checkpoint artifacts are implemented and validated by the scriptlab adapter flow. Sources: `include/amduat/asl/log_cursor.h`, `include/amduat/asl/projection_checkpoint.h`, `tests/substrate/test_scriptlab_adapter.c`. --- ## 10. Layer 1 Dependencies (Allowed vs Disallowed) **Layer 1 (higher API) MAY depend on:** 1. ASL core and store surfaces (`amduat/asl/core.h`, `amduat/asl/store.h`). 2. ASL index/log state + replay (`amduat/asl/index_replay.h`, `amduat/enc/asl_log.h`). 3. Derivation/provenance index (`amduat/asl/asl_derivation_index_fs.h`, `amduat/pel/derivation_sid.h`). 4. PEL deterministic artifacts and surface results (`amduat/pel/surf.h`, `amduat/enc/pel1_result.h`). 5. TGK edge artifacts + TGK store projection (`amduat/enc/tgk1_edge.h`, `amduat/tgk/store.h`, `amduat/tgk/tgk_store_asl_index_fs.h`). 6. Projection replay primitives (cursor + checkpoint helpers) (`amduat/asl/log_cursor.h`, `amduat/asl/projection_checkpoint.h`). **Layer 1 MUST NOT depend on:** 1. CLI tools (`src/tools/*`) as APIs. 2. Any networking, auth, tenancy, or server layers (none are provided). 3. App/domain schemas beyond raw ASL records (records may carry schema bytes, but core does not interpret them).