# 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