amduat-api/tier1/asl-tgk-execution-plan-1.md

# ASL/TGK-EXEC-PLAN/1 -- Unified Execution Plan Semantics

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

**Document ID:** `ASL/TGK-EXEC-PLAN/1`
**Layer:** L2 -- Execution plan semantics (no encoding)

**Depends on (normative):**

* `ASL/1-CORE-INDEX`
* `ASL/LOG/1`
* `ASL/INDEX-ACCEL/1`
* `TGK/1`

**Informative references:**

* `ASL/SYSTEM/1`
* `ENC-ASL-CORE-INDEX`

---

## 0. Conventions

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

ASL/TGK-EXEC-PLAN/1 defines execution plan semantics for querying artifacts and TGK edges. It does not define encoding, transport, or runtime scheduling.

---

## 1. Purpose

This document defines the operator model and determinism rules for executing queries over ASL artifacts and TGK edges using snapshot-bounded visibility.

---

## 2. Execution Plan Model (Normative)

An execution plan is a DAG of operators:

```
Plan = { nodes: [Op], edges: [(Op -> Op)] }
```

Each operator includes:

* `op_id`: unique identifier
* `op_type`: operator type
* `inputs`: upstream operator outputs
* `snapshot`: `(SnapshotID, LogPrefix)`
* `constraints`: canonical filters
* `projections`: output fields
* `traversal`: optional traversal parameters
* `aggregation`: optional aggregation parameters

---

## 2.1 Query Abstraction (Informative)

A query can be represented as:

```
Q = {
  snapshot: S,
  constraints: C,
  projections: P,
  traversal: optional,
  aggregation: optional
}
```

Where:

* `constraints` describe canonical filters (artifact keys, type tags, edge types, roles, node IDs).
* `projections` select output fields.
* `traversal` declares TGK traversal depth and direction.
* `aggregation` defines deterministic reduction operations.

---

## 3. Deterministic Ordering (Normative)

All operator outputs MUST be ordered by:

1. `logseq` ascending
2. canonical key ascending (tie-breaker)

Parallel execution MUST preserve this order.

---

## 4. Visibility Rules (Normative)

Records are visible if and only if:

* `record.logseq <= snapshot.log_prefix`
* The record is not shadowed by a later tombstone

Unknown record types MUST be skipped without breaking determinism.

---

## 5. Operator Types (Normative)

### 5.1 SegmentScan

* Inputs: sealed segments
* Outputs: raw record references
* Rules:
  * Only segments with `segment.logseq_min <= snapshot.log_prefix` are scanned.
  * Advisory filters MAY be applied but MUST NOT introduce false negatives.
  * Shard routing MAY be applied prior to scan if deterministic.

### 5.2 IndexFilter

* Inputs: record stream
* Outputs: filtered record stream
* Rules:
  * Applies canonical constraints (artifact key, type tag, TGK edge type, roles).
  * Filters MUST be exact; advisory filters are not sufficient.

### 5.3 TombstoneShadow

* Inputs: record stream + tombstone stream
* Outputs: visible records only
* Rules:
  * Later tombstones shadow earlier entries with the same canonical key.

### 5.4 Merge

* Inputs: multiple ordered streams
* Outputs: single ordered stream
* Rules:
  * Order is `logseq` then canonical key.
  * Merge MUST be deterministic regardless of shard order.

### 5.5 Projection

* Inputs: record stream
* Outputs: projected fields
* Rules:
  * Projection MUST preserve input order.

### 5.6 TGKTraversal

* Inputs: seed node set
* Outputs: edge and/or node stream
* Rules:
  * Expansion MUST respect snapshot bounds.
  * Traversal depth MUST be explicit.
  * Order MUST follow deterministic ordering rules.

### 5.7 Aggregation (Optional)

* Inputs: record stream
* Outputs: aggregate results
* Rules:
  * Aggregation MUST be deterministic given identical inputs and snapshot.

### 5.8 LimitOffset (Optional)

* Inputs: ordered record stream
* Outputs: ordered slice
* Rules:
  * Applies pagination or top-N selection.
  * MUST preserve deterministic order from upstream operators.

### 5.9 ShardDispatch (Optional)

* Inputs: shard-local streams
* Outputs: ordered global stream
* Rules:
  * Shard execution MAY be parallel.
  * Merge MUST preserve deterministic ordering by `logseq` then canonical key.

### 5.10 SIMDFilter (Optional)

* Inputs: record stream
* Outputs: filtered record stream
* Rules:
  * SIMD filters are advisory accelerators.
  * Canonical checks MUST still be applied before output.

---

## 6. Acceleration Constraints (Normative)

Acceleration mechanisms (filters, routing, SIMD) MUST be observationally invisible:

* False positives are permitted.
* False negatives are forbidden.
* Canonical checks MUST always be applied before returning results.

---

## 7. Plan Serialization (Optional)

Execution plans MAY be serialized for reuse or deterministic replay.

```c
struct exec_plan {
    uint32_t plan_version;
    uint32_t operator_count;
    struct operator_def operators[];
    struct operator_edge edges[];
};
```

Serialization MUST preserve operator parameters, snapshot bounds, and DAG edges.

---

## 8. GC Safety (Informative)

Records and edges MUST NOT be removed if they appear in a snapshot or are
reachable via traversal at that snapshot.

---

## 9. Non-Goals

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

* Runtime scheduling or parallelization strategy
* Encoding of operator plans
* Query languages or APIs
* Operator cost models