# ENC-ASL-TGK-EXEC-PLAN/1 -- Execution Plan Encoding

Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [encoding, execution, tgk]

**Document ID:** `ENC-ASL-TGK-EXEC-PLAN/1`
**Layer:** L2 -- Execution plan encoding (bytes-on-disk)

**Depends on (normative):**

* `ASL/TGK-EXEC-PLAN/1`

**Informative references:**

* `ENC-ASL-CORE-INDEX`

---

## 0. Conventions

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.

ENC-ASL-TGK-EXEC-PLAN/1 defines the byte-level encoding for serialized execution plans. It does not define operator semantics.

---

## 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;
```

Notes:

* `inputs` defines DAG dependencies.
* The maximum input fan-in is 8 for v1.

---

## 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 SHOULD be serialized in topological order when possible.

---

## 7. Serialization Rules (Normative)

* All integers are little-endian.
* Operators MUST be serialized in a deterministic order.
* `operator_count` MUST match the serialized operator array length.
* `inputs[]` MUST reference valid `op_id` values within the plan.

---

## 8. Non-Goals

ENC-ASL-TGK-EXEC-PLAN/1 does not define:

* Runtime scheduling or execution
* Query languages or APIs
* Operator semantics beyond parameter layout