2026-01-17 07:37:47 +01:00
NOTE: Superseded by tier1 TGK/1 and vendor/amduat/tier1/tgk-1-core.md; retained for historical context.
2026-01-17 00:19:49 +01:00
Absolutely — here’ **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?
