amduat-api/notes/reconcile the models.md

Yes — you’re absolutely right, and thank you for calling this out.
What you’re seeing is not a small conflict, it’s a **layering collision**, and the correct fix is **not** to weaken ENC-TGK-CORE.

Let’s reset cleanly and reconcile the models.

---

## 1. What ENC-TGK-CORE already guarantees (and must not change)

From what you say, ENC-TGK-CORE already defines:

* An **edge** as:

  * a list of *from* nodes
  * a list of *to* nodes
* The encoding is **strict**
* This is the **semantic edge representation**, not an index artifact

That means:

> ENC-TGK-CORE defines *what an edge is*, not *how edges are indexed*.

So my previous draft **incorrectly redefined the edge shape** at the encoding layer. You’re correct to reject that.

---

## 2. Correct mental model (this is the key correction)

There are **three distinct things**:

| Layer                   | What it defines                            |
| ----------------------- | ------------------------------------------ |
| TGK-CORE / ENC-TGK-CORE | Edge *structure* (from[] → to[])           |
| TGK-INDEX               | How edges are *located and filtered*       |
| ENC-TGK-INDEX           | Index records pointing *to* TGK-CORE edges |

👉 **ENC-TGK-INDEX must never encode the edge itself.**
It only encodes **references to edges**.

This is exactly analogous to ASL artifacts vs ASL index entries.

---

## 3. What must change in ENC-TGK-INDEX (conceptual patch)

ENC-TGK-INDEX must be rewritten as:

> *An index over immutable TGK-CORE edges, not a re-encoding of edges.*

That resolves the conflict cleanly.

---

## 4. Revised ENC-TGK-INDEX model (corrected)

### 4.1 What an index record refers to

A TGK index record must reference:

* A **TGK-CORE edge identifier**
* Snapshot / log sequence
* Routing and filtering attributes (edge type key, etc.)
* Optional projection context

But **never** re-encode `from[]` or `to[]`.

---

## 5. Canonical Edge Identity (reconciled)

Canonical Edge Key becomes:

```
CanonicalEdgeKey =
  TGK_CORE_EDGE_ID
```

Where:

* `TGK_CORE_EDGE_ID` is defined *exclusively* by ENC-TGK-CORE
* Identity is stable and already well-defined
* Index never inspects edge structure

This is the cleanest possible boundary.

---

## 6. How filters work with multi-node edges

Because edges are `from[] → to[]`, the index supports **multiple logical projections** *without duplicating semantics*.

Indexing options (all valid):

1. **Edge-centric indexing** (default)

   * One index record per edge
   * Filter by edge type, snapshot, context

2. **Node-projection indexing** (optional acceleration)

   * Additional index records mapping:

     ```
     node_id → edge_id
     ```
   * Pure acceleration
   * Semantically redundant

This fits perfectly with ASL-INDEX-ACCEL.

---

## 7. What ENC-TGK-INDEX should actually contain

### 7.1 Correct index record shape

```c
struct tgk_index_record {
    uint64_t logseq;
    uint64_t tgk_edge_id;      // references ENC-TGK-CORE edge
    uint32_t edge_type_key;    // optional
    uint8_t  has_edge_type;
    uint8_t  role;             // from / to / both (optional)
    uint16_t flags;            // tombstone, etc.
};
```

* `tgk_edge_id` is the only identity reference
* No node lists here
* No semantic duplication

---

### 7.2 Optional projection index (acceleration only)

If needed:

```c
struct tgk_node_edge_ref {
    uint64_t logseq;
    uint64_t node_id;
    uint64_t tgk_edge_id;
    uint8_t  position; // from or to
};
```

This is:

* Optional
* Redundant
* Fully derivable
* Clearly acceleration

---

## 8. Document changes required (precise)

### 🔁 Documents to UPDATE

#### TGK-INDEX

* Canonical Edge Key = TGK-CORE edge ID
* Explicit statement: index never encodes edge structure

#### ENC-TGK-INDEX

* Rewrite as **edge-reference index**
* Remove all `from[]` / `to[]` fields
* Reference ENC-TGK-CORE normatively

---

### 🚫 Documents NOT to touch

* ENC-TGK-CORE (must remain authoritative)
* TGK-CORE semantics
* PEL-TRACE

---

## 9. One sentence that should be normative (important)

Add this verbatim to ENC-TGK-INDEX:

> *ENC-TGK-INDEX encodes only references to TGK-CORE edges and MUST NOT re-encode or reinterpret edge structure.*

This single sentence prevents future drift.

---

## 10. Why this is actually a good sign

You caught this because your model is **internally consistent**.

What happened:

* Index draft accidentally crossed into core semantics
* You noticed because ENC-TGK-CORE is strict
* The fix strengthens layering, not weakens it

That’s exactly what you want at this stage.

---

## 11. Recommended next step

If you want, I can now:

* **Rewrite ENC-TGK-INDEX correctly**, fully aligned with ENC-TGK-CORE
  or
* Produce a **one-page layering contract** between TGK-CORE, TGK-INDEX, and ASL-INDEX-ACCEL

Both will lock this down permanently.