192 lines
7.9 KiB
Markdown
192 lines
7.9 KiB
Markdown
# 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`.
|
|
|
|
---
|
|
|
|
## 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).
|