amduat/tier1/ms-1.md

MS/1 — Concept Mapping Surface

Status: Draft Owner: Architecture Version: 0.1.0 SoT: No Last Updated: 2026-02-21 Tags: [mapping, concepts, determinism]

Document ID: MS/1 Layer: L2 — Deterministic concept-to-data mapping surface

Depends on (normative):

• ASL/1-CORE — Artifact, Reference, TypeTag identity
• TGK/1 — concept nodes and predicate edges
• ADR-003 — canonical encoding discipline (BCF/1)
• ADR-006 — deterministic error semantics

Informative references:

• amduatd-api-endpoint-spec.target.md §4.12 (MS/1 mapping surface target)

---

0. Conventions

The key words MUST, MUST NOT, REQUIRED, SHOULD, and MAY are to be interpreted as in RFC 2119.

MS/1 defines the deterministic mapping from (Concept, ContextFrame) to outputs. It does not define transport or API endpoints.

---

1. Core Concepts

1.1 Concept

Concepts are graph nodes (TGK) with stable references.

1.2 Context Frame

A Context Frame is a canonical, content-addressed artifact encoding the bindings needed to execute a concept mapping.

Logical model:

ContextFrame = {
  bindings: Map<ConceptRef, Value>
  predicates: Map<PredicateRef, Value>   // optional
}

Value is one of:

• DataRef — an ASL/1-CORE reference to data bytes
• Scalar — a canonical scalar (bool, int, float, string, null)

1.3 Mapping Result

ms_map returns exactly one of:

• produced — a canonical output artifact
• gap — missing required bindings
• ambiguity — multiple admissible bindings

---

2. Context Frame Canonical Encoding (Normative)

Context Frames MUST be encoded deterministically as a canonical BCF/1 map:

{
  "bindings": { <RefBytesHex> : <Value> ... },
  "predicates": { <RefBytesHex> : <Value> ... }   // optional
}

Rules:

1. Keys are ReferenceBytes hex (lowercase, no 0x), sorted byte-lexicographically by raw ReferenceBytes.
2. Value encoding is canonical BCF/1:
   • DataRef is encoded as {"ref": <RefBytesHex>}.
   • Scalar is encoded as the canonical scalar value.
3. No duplicate keys.
4. Missing predicates is equivalent to an empty map.

The resulting bytes are content-addressed; the ContextFrame CID is the identity of the canonical bytes.

Context Frame artifacts MUST use type_tag=amduat.context_frame.

---

3. Mapping Entrypoint (Normative)

ms_map(concept_ref, context_frame, attachments?, concept_inputs?) -> Result

3.1 Effective Frame

The effective Context Frame is the canonical merge of:

1. context_frame bindings
2. attachments (data refs)
3. concept_inputs (concept refs)

Rules:

• attachments are added as bindings under their declared concept keys.
• concept_inputs are added as bindings where the value is a concept ref.
• Conflicts (same key, different value) MUST yield ambiguity.

3.2 Required Keys

A concept MAY declare required bindings via TGK edges:

• ms.requires_key — concept_ref -> key_concept_ref
• ms.requires_predicate — concept_ref -> predicate_concept_ref

Rules:

• Missing required ms.requires_key bindings MUST yield gap.
• Missing required ms.requires_predicate bindings MUST yield gap.

3.3 Result Determination

Given a concept and effective frame:

1. If any required binding is missing ⇒ return gap.
2. If any required binding is present with multiple admissible values ⇒ return ambiguity.
3. Otherwise, execute deterministically and return produced.

All outcomes MUST be deterministic for identical inputs.

---

4. Gap & Ambiguity Artifacts (Normative)

Gap and Ambiguity are first-class artifacts stored for audit.

Canonical payloads (BCF/1 map, deterministic ordering):

4.1 Gap

{
  "concept_ref": <RefBytesHex>,
  "context_ref": <RefBytesHex>,
  "missing_keys": [<RefBytesHex>...],
  "missing_predicates": [<RefBytesHex>...]
}

4.2 Ambiguity

{
  "concept_ref": <RefBytesHex>,
  "context_ref": <RefBytesHex>,
  "ambiguous_keys": [
    { "key": <RefBytesHex>, "candidates": [<RefBytesHex>...] }
  ]
}

• Lists are sorted by key, then candidate bytes.
• Missing arrays are encoded as empty arrays.

Type tags:

• Gap: amduat.ms.gap
• Ambiguity: amduat.ms.ambiguity

---

5. Deterministic Error Codes (ADR-006)

Errors MUST be mapped to deterministic codes:

• ERR_MS_INVALID_FRAME — non-canonical or malformed Context Frame.
• ERR_MS_KEY_MISSING — required key absent (Gap).
• ERR_MS_PREDICATE_MISSING — required predicate absent (Gap).
• ERR_MS_AMBIGUOUS — multiple admissible bindings (Ambiguity).
• ERR_MS_UNSUPPORTED — unsupported scalar or value kind.

These errors MUST NOT depend on runtime ordering or external state.

---

6. Non-Goals

MS/1 does not define:

• Transport or HTTP APIs
• Execution engines or optimizers
• Concept graph schemas beyond required key/predicate edges