amduat/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
Linked Phase Pack: N/A
Tags: [execution, query, tgk, determinism]

<!-- Source: /amduat-api/tier1/asl-tgk-execution-plan-1.md | Canonical: /amduat/tier1/asl-tgk-execution-plan-1.md -->

**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/1`
* `ENC/ASL-TGK-EXEC-PLAN/1`

© 2025 Niklas Rydberg.

## License

Except where otherwise noted, this document (text and diagrams) is licensed under
the Creative Commons Attribution 4.0 International License (CC BY 4.0).

The identifier registries and mapping tables (e.g. TypeTag IDs, HashId
assignments, EdgeTypeId tables) are additionally made available under CC0 1.0
Universal (CC0) to enable unrestricted reuse in implementations and derivative
specifications.

Code examples in this document are provided under the Apache License 2.0 unless
explicitly stated otherwise. Test vectors, where present, are dedicated to the
public domain under CC0 1.0.

---

## 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.

**Implementation note:** This repository treats execution plans as a serialized
plan format and semantic contract only. A plan executor is out of scope for the
core library; higher-level services or tooling may implement execution on top
of the encoded plan.

---

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