amduat-api/notes/# C Structures for Execution Plan (ASL + TGK).md

NOTE: Superseded by tier1 TGK/1 and vendor/amduat/tier1/tgk-1-core.md; retained for historical context.

Absolutely — here’s a formal draft of C structures for the unified execution plan, mapping operators, parameters, and the DAG serialization format. This aligns with the ENC-ASL-TGK-INDEX model and preserves deterministic snapshot semantics.

---

C Structures for Execution Plan (ASL + TGK)

---

1. Operator Type Enumeration

typedef enum {
    OP_SEGMENT_SCAN,
    OP_INDEX_FILTER,
    OP_MERGE,
    OP_PROJECTION,
    OP_TGK_TRAVERSAL,
    OP_AGGREGATION,
    OP_LIMIT_OFFSET,
    OP_SHARD_DISPATCH,
    OP_SIMD_FILTER,
    OP_TOMBSTONE_SHADOW
} operator_type_t;

---

2. Operator Flags

typedef enum {
    OP_FLAG_NONE       = 0x00,
    OP_FLAG_PARALLEL   = 0x01, // shard or SIMD capable
    OP_FLAG_OPTIONAL   = 0x02  // optional operator (acceleration)
} operator_flags_t;

---

3. Snapshot Range Structure

typedef struct {
    uint64_t logseq_min;  // inclusive
    uint64_t logseq_max;  // inclusive
} snapshot_range_t;

---

4. Operator Parameter Union

typedef struct {
    // SegmentScan parameters
    struct {
        uint8_t is_asl_segment;      // 1 = ASL, 0 = TGK
        uint64_t segment_start_id;
        uint64_t segment_end_id;
    } segment_scan;

    // IndexFilter parameters
    struct {
        uint32_t artifact_type_tag;
        uint8_t  has_type_tag;
        uint32_t edge_type_key;
        uint8_t  has_edge_type;
        uint8_t  role;               // 0=none, 1=from, 2=to, 3=both
    } index_filter;

    // Merge parameters
    struct {
        uint8_t deterministic;       // 1 = logseq ascending + canonical key
    } merge;

    // Projection parameters
    struct {
        uint8_t project_artifact_id;
        uint8_t project_tgk_edge_id;
        uint8_t project_node_id;
        uint8_t project_type_tag;
    } projection;

    // TGKTraversal parameters
    struct {
        uint64_t start_node_id;
        uint32_t traversal_depth;
        uint8_t direction;           // 1=from, 2=to, 3=both
    } tgk_traversal;

    // Aggregation parameters
    struct {
        uint8_t agg_count;
        uint8_t agg_union;
        uint8_t agg_sum;
    } aggregation;

    // LimitOffset parameters
    struct {
        uint64_t limit;
        uint64_t offset;
    } limit_offset;

    // ShardDispatch & SIMDFilter are handled via flags
} operator_params_t;

---

5. Operator Definition Structure

typedef struct operator_def {
    uint32_t op_id;                     // unique operator ID
    operator_type_t op_type;            // operator type
    operator_flags_t flags;             // parallel/optional flags
    snapshot_range_t snapshot;          // snapshot bounds for deterministic execution
    operator_params_t params;           // operator-specific parameters

    uint32_t input_count;               // number of upstream operators
    uint32_t inputs[8];                 // list of op_ids for input edges (DAG)
} operator_def_t;

• inputs define DAG dependencies
• Max 8 inputs per operator (can be extended)
• Snapshot bounds used to enforce visibility

---

6. Execution Plan Structure

typedef struct exec_plan {
    uint32_t plan_version;              // version of plan encoding
    uint32_t operator_count;            // number of operators
    operator_def_t *operators;          // array of operator definitions
} exec_plan_t;

• Operators are topologically sorted if possible
• Serialization preserves DAG structure via inputs[]

---

7. Example: Serialized Execution Plan

• SegmentScan (ASL) → IndexFilter → Merge → Projection → Aggregation
• SegmentScan (TGK) → IndexFilter → TGKTraversal → TombstoneShadow → Merge → Projection → Aggregation

// Topologically ordered array
operator_def_t operators[8] = {
    { .op_id=1, .op_type=OP_SEGMENT_SCAN, .flags=OP_FLAG_PARALLEL, .snapshot={1000,1000}, .params.segment_scan={1,1,10}, .input_count=0 },
    { .op_id=2, .op_type=OP_INDEX_FILTER, .input_count=1, .inputs={1}, .params.index_filter={42,1,0,0,0} },
    { .op_id=3, .op_type=OP_MERGE, .input_count=2, .inputs={2,6}, .params.merge={1} },
    { .op_id=4, .op_type=OP_PROJECTION, .input_count=1, .inputs={3}, .params.projection={1,1,1,1} },
    { .op_id=5, .op_type=OP_AGGREGATION, .input_count=1, .inputs={4}, .params.aggregation={1,0,0} },
    { .op_id=6, .op_type=OP_SEGMENT_SCAN, .flags=OP_FLAG_PARALLEL, .snapshot={1000,1000}, .params.segment_scan={0,1,5}, .input_count=0 },
    { .op_id=7, .op_type=OP_INDEX_FILTER, .input_count=1, .inputs={6}, .params.index_filter={0,0,7,1,1} },
    { .op_id=8, .op_type=OP_TGK_TRAVERSAL, .input_count=1, .inputs={7}, .params.tgk_traversal={100,2,1} }
};

• This plan matches the previous example query
• DAG is explicit via inputs[]
• Determinism enforced via snapshot + logseq ordering in operators

---

8. Serialization Considerations

• exec_plan_t can be serialized to disk or network

• Each operator_def_t includes:

  • Type, parameters
  • Input edges
  • Snapshot range

• Serialization format can be binary or CBOR/Protobuf for federation

• Supports deterministic replay and distributed execution

---

9. Summary

These C-structs:

• Represent operators, parameters, DAG edges
• Support snapshot-safe, deterministic execution
• Enable serialized execution plans for reuse and federation
• Directly map to ENC-ASL-TGK-INDEX references

---

Next step could be defining runtime execution semantics and memory layout for SIMD/shard acceleration for these operators, fully ready for implementation.

Do you want me to draft that?