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

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

```c
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

```c
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

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

---

## 4. Operator Parameter Union

```c
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

```c
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

```c
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`

```c
// 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?