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]

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.

---

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.

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