Merge branch 'burgen-fels'

.gitignore

@@ -2,3 +2,4 @@
 *.sock
 .amduat-asl/
 artifact.bin
+tier1/

CMakeLists.txt

@@ -15,6 +15,6 @@ target_include_directories(amduatd
 )
 
 target_link_libraries(amduatd
-  PRIVATE amduat_pel amduat_format amduat_asl_store_fs amduat_asl amduat_enc
+  PRIVATE amduat_tgk amduat_pel amduat_format amduat_asl_store_fs amduat_asl
-          amduat_hash_asl1 amduat_util
+          amduat_enc amduat_hash_asl1 amduat_util
 )

README.md

@@ -31,12 +31,38 @@ Run the daemon:
 ./build/amduatd --root .amduat-asl --sock amduatd.sock
 ```
 
+Dev loop (build + restart):
+
+```sh
+./scripts/dev-restart.sh
+```
+
 Query store meta:
 
 ```sh
 curl --unix-socket amduatd.sock http://localhost/v1/meta
 ```
 
+Browser UI (use `socat` to forward the Unix socket):
+
+```sh
+socat TCP-LISTEN:8080,fork,reuseaddr UNIX-CONNECT:amduatd.sock
+```
+
+Then open `http://localhost:8080/v1/ui` (concept editor).
+
+Discover the store-backed API contract ref:
+
+```sh
+curl --unix-socket amduatd.sock 'http://localhost/v1/contract?format=ref'
+```
+
+Fetch the contract bytes (JSON):
+
+```sh
+curl --unix-socket amduatd.sock http://localhost/v1/contract
+```
+
 Upload raw bytes:
 
 ```sh
@@ -66,18 +92,74 @@ curl --unix-socket amduatd.sock -X POST http://localhost/v1/pel/run \
   -d '{"program_ref":"<program_ref>","input_refs":["<input_ref_0>"],"params_ref":"<params_ref>"}'
 ```
 
+Define a PEL/PROGRAM-DAG/1 program (store-backed):
+
+```sh
+curl --unix-socket amduatd.sock -X POST http://localhost/v1/pel/programs \
+  -H 'Content-Type: application/json' \
+  -d '{"nodes":[{"id":1,"op":{"name":"pel.bytes.concat","version":1},"inputs":[{"external":{"input_index":0}},{"external":{"input_index":1}}],"params_hex":""}],"roots":[{"node_id":1,"output_index":0}]}'
+```
+
+Create a named concept and publish a ref (so you can use the name instead of hex refs):
+
+```sh
+curl --unix-socket amduatd.sock -X POST http://localhost/v1/concepts \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"hello","ref":"<program_ref>"}'
+```
+
+Publish a new version:
+
+```sh
+curl --unix-socket amduatd.sock -X POST http://localhost/v1/concepts/hello/publish \
+  -H 'Content-Type: application/json' \
+  -d '{"ref":"<program_ref_v2>"}'
+```
+
+Resolve the latest ref:
+
+```sh
+curl --unix-socket amduatd.sock http://localhost/v1/resolve/hello
+```
+
+Inspect concepts:
+
+```sh
+curl --unix-socket amduatd.sock http://localhost/v1/concepts
+curl --unix-socket amduatd.sock http://localhost/v1/concepts/hello
+```
+
+Artifact info (length + type tag):
+
+```sh
+curl --unix-socket amduatd.sock 'http://localhost/v1/artifacts/<ref>?format=info'
+```
+
 ## Current endpoints
 
-- `GET /v1/meta` → `{store_id, encoding_profile_id, hash_id}`
+- `GET /v1/meta` → `{store_id, encoding_profile_id, hash_id, api_contract_ref}`
+- `GET /v1/contract` → contract bytes (JSON) (+ `X-Amduat-Contract-Ref` header)
+- `GET /v1/contract?format=ref` → `{ref}`
+- `GET /v1/ui` → browser UI for authoring/running programs
 - `POST /v1/artifacts`
   - raw bytes: `Content-Type: application/octet-stream` (+ optional `X-Amduat-Type-Tag: 0x...`)
   - artifact framing: `Content-Type: application/vnd.amduat.asl.artifact+v1`
 - `GET|HEAD /v1/artifacts/{ref}`
   - raw bytes default
   - artifact framing: `?format=artifact`
+- `POST /v1/concepts`
+  - request: `{name, ref?}` (`name` is lowercase; `ref` publishes an initial version)
+  - response: `{name, concept_ref}`
+- `POST /v1/concepts/{name}/publish` → publishes a new version `{ref}`
+- `GET /v1/concepts` → `{concepts:[{name, concept_ref}]}`
+- `GET /v1/concepts/{name}` → `{name, concept_ref, latest_ref, versions[]}`
+- `GET /v1/resolve/{name}` → `{ref}` (latest published)
 - `POST /v1/pel/run`
-  - request: `{program_ref, input_refs[], params_ref?, scheme_ref?}` (refs are hex strings; omit `scheme_ref` to use `dag`)
+  - request: `{program_ref, input_refs[], params_ref?, scheme_ref?}` (`program_ref`/`input_refs`/`params_ref` accept hex refs or concept names; omit `scheme_ref` to use `dag`)
   - response: `{result_ref, trace_ref?, output_refs[], status}`
+- `POST /v1/pel/programs`
+  - request: authoring JSON for `PEL/PROGRAM-DAG/1` (kernel ops only; `params_hex` is raw hex bytes)
+  - response: `{program_ref}`
 
 ## Notes
 

registry/README.md

@@ -0,0 +1,20 @@
+# amduat-api registry (draft)
+
+This directory mirrors the core `vendor/amduat/registry/` model for the
+**amduatd HTTP API contract**.
+
+## Goal
+
+- Keep a stable, machine-readable API contract in-repo.
+- Seed that contract into the daemon's single ASL store root at startup.
+- Advertise the store-backed contract `ref` via `GET /v1/meta`.
+
+The daemon remains thin: the contract bytes are data, and the store-backed `ref`
+acts as the version identifier.
+
+## Files
+
+- `api-contract.schema.md` — JSONL manifest schema for API contracts.
+- `api-contract.jsonl` — manifest of published contracts.
+- `amduatd-api-contract.v1.json` — contract bytes (v1).
+

registry/amduatd-api-contract.v1.json

@@ -0,0 +1 @@
+{"contract":"AMDUATD/API/1","base_path":"/v1","endpoints":[{"method":"GET","path":"/v1/ui"},{"method":"GET","path":"/v1/meta"},{"method":"HEAD","path":"/v1/meta"},{"method":"GET","path":"/v1/contract"},{"method":"POST","path":"/v1/concepts"},{"method":"GET","path":"/v1/concepts"},{"method":"GET","path":"/v1/concepts/{name}"},{"method":"POST","path":"/v1/concepts/{name}/publish"},{"method":"GET","path":"/v1/resolve/{name}"},{"method":"POST","path":"/v1/artifacts"},{"method":"GET","path":"/v1/artifacts/{ref}"},{"method":"HEAD","path":"/v1/artifacts/{ref}"},{"method":"GET","path":"/v1/artifacts/{ref}?format=info"},{"method":"POST","path":"/v1/pel/run"},{"method":"POST","path":"/v1/pel/programs"}],"schemas":{"pel_run_request":{"type":"object","required":["program_ref","input_refs"],"properties":{"program_ref":{"type":"string","description":"hex ref or concept name"},"input_refs":{"type":"array","items":{"type":"string","description":"hex ref or concept name"}},"params_ref":{"type":"string","description":"hex ref or concept name"},"scheme_ref":{"type":"string","description":"hex ref or 'dag'"}}},"pel_run_response":{"type":"object","required":["result_ref","output_refs","status"],"properties":{"result_ref":{"type":"string","description":"hex ref"},"trace_ref":{"type":"string","description":"hex ref"},"output_refs":{"type":"array","items":{"type":"string","description":"hex ref"}},"status":{"type":"string"}}},"pel_program_author_request":{"type":"object","required":["nodes","roots"],"properties":{"nodes":{"type":"array"},"roots":{"type":"array"}}},"concept_create_request":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"ref":{"type":"string","description":"hex ref"}}},"artifact_info_response":{"type":"object","required":["len","has_type_tag","type_tag"],"properties":{"len":{"type":"integer"},"has_type_tag":{"type":"boolean"},"type_tag":{"type":"string"}}}}}

registry/api-contract.jsonl

@@ -0,0 +1 @@
+{"registry":"AMDUATD/API","contract":"AMDUATD/API/1","handle":"amduat.api.amduatd.contract.v1@1","media_type":"application/json","status":"active","bytes_sha256":"0072ad1a308bfa52c7578a1ff4fbfc85b662b41f37a839f4390bdb4c24ecef0c","notes":"Seeded into the ASL store at amduatd startup; ref is advertised via /v1/meta."}

registry/api-contract.schema.md

@@ -0,0 +1,20 @@
+# Schema: registry/api-contract.jsonl
+
+Each line is one JSON object (JSONL). This mirrors the conventions described in
+`vendor/amduat/registry/README.md`.
+
+## Canonical descriptor digest
+
+`bytes_sha256` is the SHA-256 digest (lowercase hex) of the exact contract bytes
+as stored in the corresponding `registry/*.json` file.
+
+## Fields
+
+- `registry` (string, required): registry name, fixed to `AMDUATD/API`.
+- `contract` (string, required): contract series identifier (e.g. `AMDUATD/API/1`).
+- `handle` (string, required): stable handle (e.g. `amduat.api.amduatd.contract.v1@1`).
+- `media_type` (string, required): content type of the bytes (e.g. `application/json`).
+- `status` (string, required): `active` | `deprecated` | `reserved`.
+- `bytes_sha256` (string, required): sha256 of the bytes file.
+- `notes` (string, optional): human notes.
+

scripts/dev-restart.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+set -eu
+
+ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+BUILD_DIR="$ROOT_DIR/build"
+SOCK_PATH=${AMDUATD_SOCK:-"$ROOT_DIR/amduatd.sock"}
+STORE_ROOT=${AMDUATD_ROOT:-"$ROOT_DIR/.amduat-asl"}
+
+if [ ! -d "$BUILD_DIR" ]; then
+  cmake -S "$ROOT_DIR" -B "$BUILD_DIR"
+fi
+
+cmake --build "$BUILD_DIR" -j
+
+if [ -S "$SOCK_PATH" ]; then
+  pid=
+  if command -v lsof >/dev/null 2>&1; then
+    pid=$(lsof -t -- "$SOCK_PATH" 2>/dev/null | head -n 1 || true)
+  elif command -v fuser >/dev/null 2>&1; then
+    pid=$(fuser "$SOCK_PATH" 2>/dev/null | awk '{print $1}' | head -n 1 || true)
+  fi
+
+  if [ -n "${pid:-}" ]; then
+    kill "$pid" 2>/dev/null || true
+    i=0
+    while [ $i -lt 30 ] && kill -0 "$pid" 2>/dev/null; do
+      i=$((i + 1))
+      sleep 0.1
+    done
+  fi
+
+  rm -f "$SOCK_PATH"
+fi
+
+exec "$BUILD_DIR/amduatd" --root "$STORE_ROOT" --sock "$SOCK_PATH"
+

tier1/ms.md

@@ -0,0 +1,505 @@
+# AMDUAT-MS/1 — Mapping Surface Specification
+
+Status: Draft
+Owner: Architecture
+Version: 0.2.2
+SoT: Yes
+Last Updated: 2025-11-30
+Linked Phase Pack: PH07
+Tags: [composition, execution, deterministic]
+
+identity_authority: amduat.programme
+lineage_id: L-PENDING-MS1
+doc_code: AMDUAT-MS/1
+code_status: tentative
+doc_code_aliases: []
+
+location: /amduat/tier1/ms.md
+surface: developer
+internal_revision: 3
+provenance_mode: full
+
+---
+
+## Overview
+
+**AMDUAT-MS/1** standardises the executable mapping surface that turns a
+**Concept** plus a **Context Frame** into deterministic **Data** bytes. The
+surface orchestrates **FPS/1 primitives** through **FCS/1 recipes** and records
+runs through **FER/1**; certification, provenance, and policy decisions remain
+with **FCT/1** and phase evidence packs. MS/1 governs observable mapping
+behaviour and context binding rules without authorising new governance or
+relation taxonomies.
+
+---
+
+## Core Model
+
+MS/1 retains Amduat's two primitive node kinds and treats all other structure as
+concept-typed relations.
+
+* **Concept node (C):** Abstract identifier that can describe, type, or govern
+  any graph element. A concept can own multiple materialisations without losing
+  identity.
+* **Data node (D):** Immutable byte sequence addressed by CID (SHA-256). All
+  executions produce Data nodes.
+* **Relation instances:** Every edge is annotated with a `relation_concept` that
+  identifies its semantics. Implementations MUST NOT embed a fixed relation
+  enumeration; relation concepts are first-class concepts.
+
+Non-normative relation concept examples include `represents` (C→D),
+`materializesAs` (C→D), `requiresKey` (C→C), `withinDomain` (C→C), `computedBy`
+(D→C), and `hasProvenance` (D→D). Ecosystems MAY register additional concepts and
+MUST treat each registered concept as a normal graph node.
+
+---
+
+## Context Frames
+
+A **Context Frame (CF)** is a deterministic multimap of `{ key_concept → value
+}` that constrains execution.
+
+* **Keys** are concept identifiers; strings are optional.
+* **Values** are canonical scalars (integers, enums keyed by concept ID) or CIDs
+  to Data nodes for larger payloads.
+* **Context CID:** `CID_context = sha256(canonical_encode(CF))`. The canonical
+  encoding MUST order keys by concept ID and normalise values so identical frames
+  generate identical CIDs.
+
+### Scoping and Refinement
+
+* Frames form a tree during pipeline execution. Each mapping step receives one
+  frame.
+* Child frames inherit bindings from the parent. A child MAY add new bindings or
+  narrow an existing binding but MUST NOT contradict established bindings.
+* Branch communication is explicit. Publishing a refinement to siblings requires
+  constructing a new **published frame** and referencing it; no sideways state is
+  implicit.
+
+### Gaps and Ambiguity
+
+* Missing required bindings yield a **Gap Artifact** (Data) that records the
+  missing keys and the decision point. No payload bytes are emitted.
+* When multiple admissible bindings remain, the step returns an **Ambiguity
+  Artifact** (Data) enumerating admissible alternatives and the rule needed to
+  disambiguate. Resolution demands a refined frame.
+
+Gap and Ambiguity artifacts are ordinary Data nodes with CIDs and MAY be audited
+like any other output.
+
+---
+
+## Mapping Surface Semantics
+
+The surface defines the total function:
+
+```
+MS_map : (Concept C, ContextFrame CF) -> Result
+Result = Produced(Data bytes) | Gap(Data) | Ambiguity(Data)
+```
+
+### Executable Form
+
+* Every mapping MUST be realised as an **FCS/1 recipe** parameterised by **PCB1**
+  blocks.
+* Recipes MAY only invoke **FPS/1 primitives** (`put`, `get`, `slice`,
+  `concatenate`, `reverse`, `splice`) and compositions thereof.
+
+### Determinism and Replayability
+
+For fixed `(C, CF)` inputs and fixed referenced Data CIDs, implementations MUST
+produce identical bytes.
+
+Each run MUST emit a **FER/1 run record** (Data) that declares:
+
+* the recipe concept ID (FCS/1),
+* the PCB1 parameter block (as Data CID),
+* all input CIDs (including `CID_context`),
+* the output CID, and
+* relevant environment hashes (e.g., FPS/1 library surfaces) that affect
+  determinism.
+
+Replaying the FCS/1 recipe with the same inputs MUST yield the same CID.
+
+### Fidelity Predicates
+
+Each mapping declares (via relation concepts) an **equivalence predicate** that
+states when the produced bytes faithfully represent the target concept. Fidelity
+predicates are themselves concepts and MAY be certified through **FCT/1**.
+
+### Domain Keys
+
+Disambiguation relies on **Domain concepts** expressed as context keys (e.g.,
+`withinDomain`). Recipes MAY require domain bindings such as classical vs.
+quantum state spaces to guarantee deterministic interpretation.
+
+### Function Interface Patterns
+
+Implementations SHOULD expose a narrow callable surface so concept inputs and
+Determinism guarantees remain auditable.
+
+1. **Primary signature:**
+   * `Result ms_map(concept_id, context_frame)` is the canonical entry point.
+   * `concept_id` MUST be a stable concept node reference (e.g., CID or registry
+     handle). Implementations MUST NOT infer the target concept from global
+     mutable state.
+   * `context_frame` MUST be the complete set of bindings used for the run. Any
+     binding derived from other inputs MUST be reflected back into the frame
+     before execution.
+2. **Auxiliary parameters:**
+   * Additional parameters are only permitted when they can be canonicalised to
+     deterministic Data CIDs and recorded in the FER/1 run record.
+   * Preferred pattern: `attachments: Sequence[DataCID] = ()`. Each attachment
+     MUST already exist as a Data node, and the mapping MUST reference the CIDs
+     explicitly in the FER/1 log.
+   * Alternative pattern: `concept_inputs: Sequence[ConceptID] = ()` for
+     secondary concept handles. Each element MUST also appear in the effective
+     context frame (e.g., under a relation-specific key). Passing the concept ID
+     without updating the frame is a violation.
+3. **Rejected pattern:** Opaque keyword arguments or process-level environment
+   variables MUST NOT influence execution. Implementations discovering such usage
+   MUST emit an Ambiguity artifact describing the missing context binding
+   instead.
+
+The following pseudocode illustrates a compliant wrapper:
+
+```
+def ms_map(concept_id: ConceptID,
+           context_frame: ContextFrame,
+           *,
+           attachments: Sequence[DataCID] = (),
+           concept_inputs: Sequence[ConceptID] = ()) -> Result:
+    frame = context_frame.with_bindings({
+        relation_for(ci): ci for ci in concept_inputs
+    })
+    frame = frame.with_bindings({
+        relation_for(cid): cid for cid in attachments
+    })
+    record = run_fcs_recipe(concept_id, frame, attachments)
+    return normalise_result(record)
+```
+
+`relation_for` denotes a deterministic lookup from relation concept to the key
+under which the binding is stored. Implementations MAY inline more efficient
+mechanisms, but the observable effect MUST match first updating the frame and
+then invoking the recipe.
+
+### Media (MIME) Types vs. MS Context
+
+**MIME/media types** label already-produced Data so downstream systems can
+interpret byte strings (e.g., `text/plain; charset=utf-8`, `image/png`). An
+**MS context frame** captures the *pre-execution* bindings that shape which bytes
+will be emitted. They relate but are not interchangeable:
+
+* **Where they live:** Context bindings exist before execution and are hashed
+  into `CID_context`. MIME labels are attached after Data exists (e.g., CIL
+  payload metadata, HTTP headers, or relation edges such as
+  `ms.produces_media_type`).
+* **What they encode:** Context keys describe decision levers (encoding, domain,
+  fidelity policy) that an FCS recipe uses to deterministically produce bytes.
+  MIME types describe how consumers should parse already-materialised bytes. A
+  context MAY carry a desired media-type concept ("emit this as
+  `application/pdf`") but it is still a binding that constrains execution, not a
+  replacement for Content-Type headers.
+* **Interoperability:** When MS outputs feed MIME-governed ecosystems, recipes
+  SHOULD register a concept such as `ms.media_type` and declare it via
+  `ms.requires_key` if the choice affects determinism (e.g., choosing between
+  `text/csv` vs. `application/json`). FER/1 receipts then bind the produced Data
+  both to the governing context frame and to a media-type relation so downstream
+  MIME routers, storage overlays, and catalogues reconcile the two perspectives.
+
+MIME types are one example of **interpretation contracts** that MS contexts can
+align with. The same pattern applies to CAD kernels with STEP schemas, audio
+encoders with bitstream levels, or ML artefacts with `model.format`
+descriptors. MS/1 keeps them deterministic by requiring the selection to be a
+context binding (recorded before execution) while also allowing publication
+surfaces to mirror the choice via their native metadata channels.
+
+---
+
+## Pipelines and Composition
+
+A **Pipeline** is a concept that composes ordered mapping steps.
+
+* Each step executes `MS_map(C_i, CF_i)`.
+* Pipelines return either Produced(Data) or an Artifact (Gap/Ambiguity).
+* Given identical inputs, pipelines MUST be byte-stable.
+* **Branch isolation:** each branch operates on a forked frame. Publishing
+  updates requires emitting a new frame with a fresh `CID_context`, preserving
+  immutability.
+
+---
+
+## Conformance Criteria
+
+Implementations conform to MS/1 when they satisfy all of the following:
+
+1. Accept `(C, CF)` and emit either Produced(Data) or a Gap/Ambiguity artifact.
+2. Produce outputs reproducibly via FCS/1 + FPS/1, and record each run via FER/1.
+3. Encode mutable decisions through concept-typed context keys only; no hidden
+   flags.
+4. Address all bytes by SHA-256 CIDs and guarantee identical inputs replay to
+   identical CIDs.
+5. Treat relation types as concepts without hard-coded enumerations.
+
+## Dependencies (pinned drafts)
+
+MS/1 relies on upstream drafts; consumers MUST treat these versions as pinned
+for this specification and handle later changes as upstream drift:
+
+* FCS/1 v0.2.1 (Draft)
+* FPS/1 v0.4.3 (Draft)
+* FLS/1 v0.1.0 (Draft)
+
+Any adoption in PH10+ MUST re-pin consciously if these upstream specs change.
+
+## Evidence (PH08 runtime)
+
+PH08 reference executions demonstrate MS/1 behaviour; cite these when asserting
+readiness or approval:
+
+* `logs/ph08/evidence/ms/PH08-EV-MS-RUNTIME-001/`
+* `logs/ph08/evidence/ms/PH08-EV-MS-ACCEPT-001/`
+* `logs/ph08/evidence/ms/PH08-EV-MS-BIND-001/`
+* `logs/ph08/evidence/ms/PH08-EV-MS-CORE-001/`
+* `logs/ph08/evidence/ms/PH08-EV-MS-GATES-001/`
+* `logs/ph08/evidence/ms/PH08-EV-MS-LADDER-001/`
+* `logs/ph08/evidence/ms/PH08-EV-MS-PIPE-001/`
+* `logs/ph08/evidence/ms/PH08-EV-MS-ML-EVAL-001/`
+
+---
+
+## Worked Ladder Example (Zero → Byte)
+
+The following non-normative ladder illustrates how MS/1 composes mappings from
+abstract numbers to textual bytes.
+
+1. Concepts: `C_Number65`, `C_CodePoint(U+0041)`, `C_LetterA`, `C_WordA`.
+2. Context frame bindings: `withinDomain → C_Unicode15`,
+   `C_TextEncoding → C_UTF8`.
+3. Steps:
+   * Interpret `C_Number65` as `C_CodePoint(U+0041)` by applying a mapping rule
+     concept.
+   * Map `C_CodePoint(U+0041)` within the Unicode/UTF-8 frame to Data `0x41`.
+   * Map `C_WordA` under the same frame to Data `0x41`.
+
+Each run records its FER/1 linkage so the byte `0x41` can be replayed.
+
+---
+
+## Context Evolution and Replay Discipline
+
+### Context Revisions During Pipelines
+
+When a branch detects missing bindings (e.g., absent `C_TextEncoding`), it MUST
+emit an Ambiguity artifact detailing admissible encodings. Progress resumes by
+creating a refined frame `CF' = CF ∪ { C_TextEncoding → C_UTF8 }` and re-running
+only the affected branch. Publishing the refinement to siblings is explicit and
+produces a new parent frame with a distinct `CID_context`.
+
+### Replay-First Evolution
+
+MS/1 guards against semantic drift when the knowledge base or registry grows:
+
+* **Frame immutability:** Every FER/1 record captures the `CID_context` that was
+  in force at execution time. New bindings (e.g., alternative encodings) produce
+  new frame hashes and therefore new provenance edges. Historical runs replay
+  byte-for-byte because their frames never mutate.
+* **Required bindings:** Recipes MUST register mandatory keys via
+  `ms.requires_key`. When governance tightens (for example, by requiring a
+  `string.encoding` key), existing frames lacking the key yield deterministic
+  Gap/Ambiguity artifacts instead of silently adopting defaults.
+* **Replay-first migration:** If an ecosystem needs the new semantics, it reruns
+  the recorded FCS/1 recipe with a refined frame. The new FER/1 record cites the
+  refined `CID_context`, making comparisons between legacy and refreshed runs
+  explicit and auditable.
+* **Artifact parity:** Gap and Ambiguity outputs are stored as first-class Data
+  nodes. Audits can therefore demonstrate exactly where a richer knowledge base
+  demanded additional context, keeping provenance complete even when execution
+  paused.
+
+Collectively, these rules let operators expand the registry or tighten policies
+without jeopardising determinism or traceability.
+
+---
+
+## Hashing Bits and Abstract Values
+
+MS/1 hashes bytes, not abstract concepts. A bit becomes hashable only once it is
+materialised (e.g., via `C_BitAsOctet`). When domain or packing decisions remain
+unbound, the mapping MUST emit an Ambiguity or Gap artifact rather than guess.
+
+---
+
+## Risk Controls
+
+MS/1 aligns with existing Amduat controls:
+
+* **Semantic drift:** Context keys are concepts with versioned materialisations;
+  frame hashes reveal mismatches.
+* **Provenance loss:** Every Produced(Data) links to a FER/1 record via
+  `hasProvenance`.
+* **Undocumented mutation:** Frames are immutable; refinements create new
+  contexts.
+* **Rights obligations:** Licences and attribution obligations appear as context
+  keys referencing policy Data. Recipes MAY decline to execute when obligations
+  are unmet, provided the decision is deterministic.
+
+---
+
+## Acceptance Checks
+
+An MS/1 implementation SHOULD ship the following self-tests:
+
+1. **Replay test:** identical `(C, CF)` inputs produce the same CID and FER/1 log.
+2. **Gap test:** missing required keys yield deterministic Gap artifacts.
+3. **Ambiguity test:** admissible alternatives are enumerated stably.
+4. **Scope test:** sibling branches remain unchanged unless a published frame is
+   adopted.
+5. **Fidelity test:** the declared equivalence predicate is machine-verifiable.
+
+---
+
+## Registry Alignment
+
+MS/1 is production-registered in the CRS/1 concept registry. Implementations
+MUST treat the following handles and digests as canonical when emitting or
+validating graphs:
+
+| Symbol | Registry Handle | Kind | SHA-256 Digest | Notes |
+| --- | --- | --- | --- | --- |
+| `MS/1` | `crs:concept/amduat.ms.surface@1` | Concept | `d140ac54367a88fa2459e3fedf0b2fde934f9ac73568f8a159e2b0c1c1828c70` | Primary mapping surface concept anchoring `MS_map` executions. |
+| `ms.produces` | `crs:concept/amduat.ms.relation.produces@1` | Relation concept | `447a9f454d78f5b2ee300fe416138a864789e133b2eb9a84e32592aa9dd47965` | Annotates `Concept → Data` edges that capture Produced(Data) bytes. |
+| `ms.requires_key` | `crs:concept/amduat.ms.relation.requires_key@1` | Relation concept | `a90295a8ca3006e062a5a1d5a6220330e53ba00677736b6f4a18efcec1169f6a` | Declares mandatory context key bindings for deterministic execution. |
+| `ms.within_domain` | `crs:concept/amduat.ms.relation.within_domain@1` | Relation concept | `0993dff2531dd32ea32b98925bf8a5cbc88c88ed28cd3c3575e8affc84d7fa2d` | Expresses domain refinements used to disambiguate mappings. |
+| `ms.fidelity_predicate` | `crs:concept/amduat.ms.relation.fidelity_predicate@1` | Relation concept | `7e159182789d89269b743c19da58d34acc3279d86650cfef83efd4f2c210c66a` | Binds outputs to the declared fidelity predicate concept. |
+| `ms.byteValue` | `crs:concept/amduat.ms.relation.byte_value@1` | Relation concept | `4c43dd3a37ae695bac476e4dc62d8d8c2abda6c555668d4d863810d0053056c3` | Records byte concepts and their literal value bindings within the ladder corpus. |
+| `ms.codePoint` | `crs:concept/amduat.ms.relation.code_point@1` | Relation concept | `bb7301d2fa0c5058cbd53019625bfd38ecb59e42010b64a9f0b0ada7dc494117` | Links textual concepts to Unicode code points under registered contexts. |
+| `ms.symbolSequence` | `crs:concept/amduat.ms.relation.symbol_sequence@1` | Relation concept | `115035e5dc2db7e9ab2e4255f50aee56d222b04f7b7434dbbec76620cf36aa6d` | Declares ordered relations between code points/bytes when emitting strings. |
+| `ms.upperCasePolicy` | `crs:concept/amduat.ms.relation.upper_case_policy@1` | Relation concept | `6f5165648c1069178c2e8a615bd24bd02a3a367df6f8e6ac21050f42eeea484c` | Encodes casing policies that constrain textual ladders. |
+| `ms.titleCasePolicy` | `crs:concept/amduat.ms.relation.title_case_policy@1` | Relation concept | `7f10f109b578b69b079fc9f284ed73c69b82434b31db0a999a872d2b47958ae5` | Encodes title-casing policies enforced during deterministic mapping. |
+
+The registry sidecar at `/amduat/registry/predicates.jsonl` mirrors these
+entries, allowing auditors to verify digests independent of this specification.
+Implementations MUST fail closed when encountering unregistered aliases for
+these handles.
+
+---
+
+## Phase 07 Cross-Stream Integration
+
+Phase 07 workstreams bind their certificates, receipts, facts, overlays, and
+domain dossiers to MS/1 contexts through a shared TypeTag grid:
+
+* `/amduat/phases/ph07/notes/PH07-CIL-XMAP-001.md` (`CIL-X1`) and
+  `vectors/ph07/cil/PH07-CIL-XMAP-001.json` declare the authoritative
+  cross-stream mapping entries and TypeTag ranges that all semantic surfaces
+  must cite before reaching Draft Ready gates. The JSON registry is logged
+  under `PH07-EV-CIL-ATTEST-001` so downstream profiles can dereference the
+  same identifiers without ambiguity.
+* `/amduat/phases/ph07/notes/PH07-CROSS-CHECK-001.md` records the harness that
+  enforces these bindings. The checklist stored in
+  `logs/ph07/evidence/cil/PH07-EV-CIL-ATTEST-001/PH07-CROSS-TV-001.md`
+  validates every FER/FCT/OI manifest against the refreshed XMAP IDs before the
+  `*-5` ledger exits (`FER-5`, `FCT-5`, `OI-5`) can advance.
+* `/amduat/phases/ph07/notes/PH07-FER-SCHEMA-001.md` (ledger `FER-1`, evidence
+  `PH07-EV-FER-RUN-001`) pins `xmap_refs[]`, certificate anchors, and replay
+  bundles to the XMAP rows so every receipt explicitly declares which MS/1
+  context governed execution.
+* `/amduat/phases/ph07/notes/PH07-FCT-SCHEMA-001.md` (ledger `FCT-1`, evidence
+  `PH07-EV-FCT-FACTS-001`) introduces the `trust_spine` block that carries the
+  required `xmap_ref`, `receipt_refs[]`, and `anchor_certs[]`, keeping fact
+  acceptance policies tied to the same mapping IDs.
+* `/amduat/phases/ph07/notes/PH07-OI-HARNESS-001.md` (ledger `OI-5`, evidence
+  `PH07-EV-OI-VIEWS-001`) proves overlay descriptors and workspace views publish
+  `mapping_profile.xmap_refs[]` plus TGK edge expectations aligned with
+  `XMAP-CIL-CUSTOM-V1`.
+* `/amduat/phases/ph07/notes/PH07-DOM-HARNESS-001.md` (ledger `DOM-5`, evidence
+  `PH07-EV-DOM-APPS-001`) extends the same guarantees to domain pilot dossiers,
+  confirming their overlays, facts, and receipts cite approved TypeTags and TGK
+  edge sets.
+
+MS/1 implementations participating in PH07 MUST therefore emit the same mapping
+handles and evidence references recorded in these notes so provenance can be
+validated across CIL/FER/FCT/OI boundaries.
+
+---
+
+## Phase 05 Textual Ladder Scope and Evidence
+
+Phase 05 extends MS/1 from abstract examples to a production ladder that binds
+textual concepts to deterministic bytes. The ladder introduces:
+
+* A `byte` concept family with 256 child concepts (`byte/0x00` … `byte/0xFF`)
+  whose CRS/1 relations emit single-octet Data nodes and optionally record the
+  radix context via `ms.byteValue` predicates.
+* UTF-8 code point concepts that sequence byte concepts through
+  `ms.symbolSequence` relations while asserting `ms.within_domain` bindings to
+  Unicode 15 and UTF-8 domain concepts.
+* Casing policy concepts (e.g., `allCaps`, `titleCase`) that require the
+  `string.casingPolicy` context key and advertise fidelity predicates so
+  downstream tooling can reject ambiguous casing decisions via
+  `ms.upperCasePolicy` and `ms.titleCasePolicy` handles.
+* Dictionary word concepts implemented as FCS/1 recipes that concatenate code
+  points into byte strings, emitting FER/1 receipts that cite the governing
+  casing policy and context frame.
+
+Predicate registries gain canonical handles (`ms.byteValue`, `ms.codePoint`,
+`ms.symbolSequence`, `ms.produces`, `ms.requires_key`, `ms.upperCasePolicy`,
+`ms.titleCasePolicy`) so tooling can resolve ladder edges without bespoke
+enumerations. Missing casing bindings MUST yield Ambiguity artifacts
+(`ERR_MS_POLICY_MISSING`/`ERR_MS_AMBIGUITY`); absent code points produce Gap
+artifacts (`ERR_MS_GAP`); undeclared predicates raise
+`ERR_MS_UNDECLARED_PREDICATE`.
+
+Evidence for the ladder is captured under
+`/amduat/vectors/ph05/ms1-text/manifest.json` and the reserved
+`/amduat/logs/ph05/evidence/ms1/` surfaces:
+
+* `PH05-EV-MS-CTX-001/` — CTX/1 context frames with predicate registry vectors
+  (domain separator `AMDUAT:CTX\0`, reject `ERR_CTX_UNKNOWN_KEY`).
+* `PH05-EV-MS-LADDER-001/` — Dual-run FER/1-backed positive ladders for bytes,
+  code points, and dictionary outputs with SA/PA guardrails.
+* `PH05-EV-MS-ERRORS-001/` — Gap/ambiguity/missing policy/undeclared predicate
+  receipts mapped to ADR-006.
+
+---
+
+## Phase Alignment and Readiness
+
+* **PH07 (Semantic Surfaces):** MS/1 is authoritative for every PH07 semantic
+  surface (CIL/FER/FCT/OI) and must be cited wherever mapping semantics are
+  referenced. PH07 workstreams MAY extend context vocabularies or registry rows
+  so long as they remain MS/1-conformant; no runtime commits are expected in
+  this phase beyond harness stubs and governance evidence.
+* **PH08 (Reference Implementation):** The reference `ms_map` runtime, parity
+  harnesses, and subsystem wiring reside in the `KRN-2` campaign slotted for
+  Phase 08. PH08 SHALL use this specification verbatim, emitting FER/1 records
+  and exercising the acceptance checks in §Acceptance Checks.
+* **Downstream pilots (PH09+):** Reproducible ML, CI/CD, data mesh, and notebook
+  pilots inherit the MS/1 contract by invoking the PH08 reference surface. Those
+  phases MAY add domain-specific context keys or ladders, but they MUST register
+  them through CRS/1 and capture evidence via the surfaces reserved in
+  §Phase 05 Textual Ladder Scope and Evidence.
+
+Declaring these boundaries keeps the approval pathway clear: PH07 completes the
+specification, PH08 proves the executable substrate, and later phases consume it
+without reopening MS/1 fundamentals.
+
+---
+
+## Document History
+
+<!-- Managed by tools/codex/document_history.py -->
+
+* **0.1.0 (2025-11-10):** Initial draft capturing deterministic concept-to-data mapping surface.
+* **0.1.1 (2025-11-11):** Add interface patterns for mapping functions and constrain auxiliary parameters.
+* **0.1.2 (2025-11-12):** Formalize registry concept handles and digests for MS/1.
+* **0.1.3 (2025-11-14):** Documented PH05 textual ladder scope, predicate handles, and evidence surfaces.
+* **0.1.4 (2025-11-15):** Aligned MS/1 evidence references with CTX/1, ladder, and error reservations.
+* **0.1.5 (2025-11-18):** Added ms.* predicate handles, CTX/1 domain separator, ADR-006 error mapping, and dual-run evidence guardrails.
+* **0.1.6 (2025-11-18):** Added context-evolution guardrails and PH07→PH08 readiness boundaries.
+* **0.1.7 (2025-11-19):** Clarified MIME/media-type relationship to MS context frames and execution bindings.
+* **0.2.0 (2025-11-19):** Standardized metadata, headings, and evidence alignment per DOCSTD.
+* **0.2.1 (2025-11-19):** Synced registry handles and documented PH07 XMAP/harness integration.
+* **0.2.2 (2025-11-30):** Added DOCID header, pinned upstream draft dependencies, and referenced PH08 MS/1 evidence bundles.