niklas/amduat
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat/docs/SUBSTRATE_CONTRACT_V0_1.md
Carl Niklas Rydberg baa4794918 Add projector pattern
2026-02-21 19:50:00 +01:00

8.1 KiB
Raw Blame History

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