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

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:

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.