astp-docs-server 0.1.0__py3-none-any.whl

astp_docs_server/corpus/open/CONFORMANCE-LAYER3.md

@@ -0,0 +1,272 @@
+# ASTP — Layer 3 (Workflow & Execution DAG) Conformance Test Vectors
+
+**Version:** 1.1.0
+**Status:** Stable
+**Authors:** Scorched Earth Labs
+**Date:** 2026-09-19
+**Applies To:** SPEC.md §21 (Layer 3 — Workflow & Execution DAG), 5.1.0 (SPEC §21; unchanged by 5.0.0 — see the note in §1)
+
+---
+
+## 1. Overview
+
+> **SPEC 5.0.0 / 5.1.0 note.** Layer 3 is unchanged by 5.0.0: its byte form is governed by SPEC §21 Part III §8 and is deliberately outside the §5.1 single-encoding statement (§5.1 says so). What did change around it: the audit records Layer 3 events write are the version 2 audit record of SPEC §8; and, under the 5.1.0 adapter failure contract, a Layer 3 writer that cannot complete raises rather than returning a default.
+
+This document specifies the conformance test vectors for **Layer 3 — the Workflow & Execution DAG** of ASTP (the AI State Tree Protocol). A conforming implementation MUST pass all vectors marked **REQUIRED**. Vectors marked **RECOMMENDED** test behaviors that conforming implementations SHOULD support.
+
+Layer 3 is the forensic provenance layer: `WorkflowDeclaration`, `ExecutionNode`, and `SkillInvocation` record *how* an Episode's cognition was carried out. Its defining property is **cryptographic isolation from the Merkle Spine** — Layer 3 nodes reference Layers 1/2 by `node_id` only and MUST NOT participate in Spine hashing (Invariant L3-I1). This isolation is a first-class conformance concern; see the `L3-` vectors of §6.
+
+These vectors are **cross-implementation-consistency** vectors: they assert canonical *field inclusion and ordering* and behavioral invariants, not hardcoded golden-hash values. Per SPEC §21 §8, the hash **byte-form is left open at the protocol layer** — each implementation chooses a serialization (SHA3-256 length-prefixed concatenation, SHA-256 canonical JSON, or other) and MUST be internally consistent. Two conforming implementations that adopt the *same* documented serialization MUST produce identical bytes for identical inputs; two implementations that adopt *different* serializations legitimately produce different hashes. What every conforming implementation MUST agree on is **which fields contribute, in what order** (W-L3-2).
+
+Vectors are organized to match the reference deployment's adapter guide, `IMPLEMENTATION-LAYER3.md` (which lives with that adapter):
+
+| Scope | Description | Vector Prefix |
+|-------|-------------|---------------|
+| WorkflowDeclaration | Schema, hash preimage, mutation surface, state machine | `WF-` |
+| ExecutionNode | Schema, hash preimage, terminal-on-write, error consistency | `EX-` |
+| SkillInvocation | Schema, hash preimage, `registry_id` deferral | `SK-` |
+| Sole-writer (CIA) | G-36 sole-writer principle + audit attribution | `CIA-` |
+| Layer invariants | Spine isolation, immutability, retry-by-new-node | `L3-` |
+
+All hex values lowercase. All string fields UTF-8.
+
+---
+
+## 2. WorkflowDeclaration Vectors (§21 §4)
+
+### 2.1 Hash Canonicalization
+
+**WF-001** — `WorkflowDeclaration` content hash — field order
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §4, §21 §8 (W-L3-1, W-L3-2)
+- **Description:** `compute_workflow_declaration_content_hash()` MUST canonicalize, in this exact order: `node_id`, `node_type`, `schema_version`, `episode_id`, `intention_id`, `mandate_id`, `workflow_name`, `workflow_version`, `declared_by`, `declared_at`, `input_context`, `expected_outputs`, `timeout_ms`. It MUST exclude `status`, `status_updated_at`, `error_detail`, and `content_hash` itself.
+- **Verification Protocol:** Cross-implementation consistency check. Two implementations sharing a documented serialization MUST produce identical bytes for the same input tuple; every conforming implementation MUST agree on the field set and order.
+- **Failure Condition:** Any excluded field contributes to the hash; any listed field is missing or reordered; wrong integer/UUID/datetime encoding.
+
+**WF-002** — Nullable provenance fields are hash-included
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §4 (hash preimage note)
+- **Description:** `intention_id` and `mandate_id` MUST contribute to the preimage even when null. A `WorkflowDeclaration` with `mandate_id = null` MUST produce a different `content_hash` than one with a non-null `mandate_id`, all other fields equal. Nullability is part of the immutable record.
+- **Failure Condition:** A null `mandate_id` (or `intention_id`) hashes identically to the field's absence, or to a distinct non-null value.
+
+**WF-003** — Mutation surface is hash-stable
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §4, §21 §9 (L3-I4)
+- **Description:** Mutating any of `status`, `status_updated_at`, `error_detail` and recomputing MUST yield the **same** `content_hash`. The mutation surface is excluded from the preimage precisely so that lawful terminal-state transitions never alter the declaration's content identity.
+- **Verification Protocol:** Stamp a declaration; mutate the trio; re-stamp; assert equal hashes.
+- **Failure Condition:** A permitted mutation changes the content hash.
+
+### 2.2 State Machine
+
+**WF-004** — Status transition legality
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §10
+- **Description:** `enforce_workflow_status_transition()` MUST permit exactly: `DECLARED → {IN_PROGRESS, INTERRUPTED}` and `IN_PROGRESS → {COMPLETED, FAILED, INTERRUPTED}`. `COMPLETED`, `FAILED`, and `INTERRUPTED` are terminal — no outbound transition is permitted. Illegal transitions MUST raise, not silently no-op.
+- **Verification Protocol:** For each (from, to) pair, assert permitted pairs succeed and all others raise `Layer3GovernanceError`.
+- **Failure Condition:** A transition out of a terminal state is admitted, or a non-listed transition succeeds.
+
+**WF-005** — Auto-transition on first execution write
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §10
+- **Description:** The first `ExecutionNode` write for a given `workflow_id` MUST atomically transition that workflow's `status` from `DECLARED` to `IN_PROGRESS`. A workspace whose `WorkflowDeclaration.status == DECLARED` while ExecutionNodes for it exist is non-conforming.
+- **Failure Condition:** A workflow remains `DECLARED` after an ExecutionNode is recorded against it.
+
+**WF-006** — Two distinct `INTERRUPTED` states are distinguishable
+- **Class:** RECOMMENDED
+- **Spec Reference:** §21 §10
+- **Description:** A conforming verifier SHOULD distinguish `status == INTERRUPTED` with **zero** ExecutionNodes ("declared, never started") from `status == INTERRUPTED` with **one or more** ExecutionNodes ("started, terminated mid-execution"). Neither is a schema violation; both are valid forensic states.
+
+---
+
+## 3. ExecutionNode Vectors (§21 §5)
+
+### 3.1 Hash Canonicalization
+
+**EX-001** — `ExecutionNode` content hash — field order
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §5, §21 §8 (W-L3-1, W-L3-2)
+- **Description:** `compute_execution_node_content_hash()` MUST canonicalize, in this exact order: `node_id`, `node_type`, `schema_version`, `workflow_id`, `episode_id`, `sequence_index`, `step_name`, `agent_id`, `executed_at`, `duration_ms`, `input_state`, `output_state`, `status`, `error_detail`, `error_type`. It MUST exclude **only** `content_hash` itself.
+- **Verification Protocol:** Cross-implementation consistency check; field set + order agreement.
+- **Failure Condition:** Any field except `content_hash` is excluded; wrong order.
+
+**EX-002** — `status` is hash-included
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §5 (hash preimage note)
+- **Description:** Unlike `WorkflowDeclaration`, `ExecutionNode.status` MUST contribute to the content hash. Because the node is terminal-on-write, its status is a permanent forensic fact — two ExecutionNodes identical but for `status` MUST hash differently.
+- **Failure Condition:** `status` is excluded from the ExecutionNode preimage, or two nodes differing only in `status` hash identically.
+
+### 3.2 Error Consistency
+
+**EX-003** — Error field / status coupling
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §5
+- **Description:** `enforce_execution_error_consistency()` MUST reject a `COMPLETED` node with non-null `error_type` or non-null `error_detail`, and MUST reject a `FAILED`/`INTERRUPTED` node with null `error_type`. (`error_detail` on a failed node is RECOMMENDED, not enforced.) `error_type ∈ {AGENT_ERROR, TIMEOUT, DEPENDENCY_FAILURE, SKILL_ERROR, UNKNOWN}`.
+- **Failure Condition:** A `COMPLETED` node carries error fields, or a failed/interrupted node omits `error_type`.
+
+---
+
+## 4. SkillInvocation Vectors (§21 §6)
+
+### 4.1 Hash Canonicalization
+
+**SK-001** — `SkillInvocation` content hash — field order
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §6, §21 §8 (W-L3-1, W-L3-2)
+- **Description:** `compute_skill_invocation_content_hash()` MUST canonicalize, in this exact order: `node_id`, `node_type`, `schema_version`, `execution_node_id`, `workflow_id`, `episode_id`, `skill_id`, `skill_source`, `skill_version`, `invoked_by`, `invoked_at`, `duration_ms`, `input_parameters`, `output_result`, `status`, `error_detail`. It MUST exclude `registry_id` and `content_hash` itself.
+- **Verification Protocol:** Cross-implementation consistency check; field set + order agreement.
+- **Failure Condition:** `registry_id` contributes to the hash; any listed field is missing or reordered.
+
+**SK-002** — `registry_id` backfill is hash-stable
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §6, §21 §13.2
+- **Description:** Populating `registry_id` on an existing `SkillInvocation` (a future Skill Registry backfill) MUST NOT change its `content_hash`. `registry_id` is the only Layer 3 field excluded from a content hash for a reason other than mutation — a deliberate forward-compatibility provision.
+- **Verification Protocol:** Stamp with `registry_id = null`; populate `registry_id`; re-stamp; assert equal hashes.
+- **Failure Condition:** Setting `registry_id` alters the content hash.
+
+**SK-003** — `registry_id` left null pending Skill Registry
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §13.2
+- **Description:** A conforming implementation MUST leave `SkillInvocation.registry_id` null until the future Skill Registry amendment defines its semantics.
+- **Failure Condition:** An implementation populates `registry_id` under its own ad-hoc semantics.
+
+### 4.2 Open Behavioral Surface
+
+**SK-004** — Skill taxonomy is recorded, not validated
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §6, §21 §12 (audit-the-decision)
+- **Description:** `skill_id` and `skill_source` are open, implementation-defined strings. The protocol does not constrain their vocabulary; it commits only that whatever value the implementation chose is recorded immutably and contributes to `content_hash`. An implementation MUST document its `skill_source` vocabulary in its `ConformanceDeclaration`.
+- **Failure Condition:** An implementation drops `skill_id`/`skill_source` from the hash, or claims a fixed protocol-level skill vocabulary.
+
+---
+
+## 5. Sole-Writer / CIA Vectors (§21 §3, G-36)
+
+**CIA-001** — Sole-writer enforcement (G-36)
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §3 (L3-I2), G-36, §21 §12
+- **Description:** For each Layer 3 node type in a workspace, exactly one entity — the Cognitive Implementation Authority — MUST be authorized to issue creation writes. Writes from any other principal MUST be rejected at the wire tier (or, under the audit-detection enforcement style, admitted but flagged `WIRE_VIOLATION`, which conforming verifiers reject). The `ConformanceDeclaration` MUST name the CIA per node type and identify the enforcement mechanism.
+- **Verification Protocol:** Attempt a Layer 3 creation write from a non-CIA principal; assert rejection (or `WIRE_VIOLATION` flag). Confirm the `ConformanceDeclaration` names a unique CIA per node type.
+- **Failure Condition:** A non-CIA principal's Layer 3 write is admitted and unflagged; or the `ConformanceDeclaration` omits/duplicates the CIA for a node type.
+
+**CIA-002** — `cia_identifier` mandatory in every audit event
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §11
+- **Description:** Every `WORKFLOW_DECLARED`, `EXECUTION_RECORDED`, `SKILL_INVOKED`, and `WORKFLOW_CLOSED` audit event MUST carry a non-null `cia_identifier` naming the principal that performed the write. This is what makes sole-writer verifiable: a verifier walking the chain confirms every L3 write came from the declared CIA.
+- **Failure Condition:** Any Layer 3 audit event lacks `cia_identifier`.
+
+**CIA-003** — Audit event emission before durability (W-L3-4)
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §11 (W-L3-4)
+- **Description:** Each Layer 3 node creation and each `WorkflowDeclaration.status` mutation MUST emit its corresponding audit event into the append-only, hash-chained log **before** the operation is considered durable. Each record hash-chains via `prev_audit_hash`; the chain-key dimension is a documented implementation choice (the reference implementation in Ignis OS — Scorched Earth Labs' agent runtime, the first consumer of this protocol — uses `episode_id`).
+- **Failure Condition:** A durable Layer 3 write with no preceding audit event, or an audit chain whose recomputed `prev_audit_hash` linkage is broken.
+
+**CIA-004** — Audit event required-field completeness
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §11
+- **Description:** Each of the four audit event types MUST carry its §11 required fields: `WORKFLOW_DECLARED` (`workflow_id`, `episode_id`, `intention_id?`, `mandate_id?`, `declared_by`, `declared_at`, `content_hash`, `cia_identifier`); `EXECUTION_RECORDED` (`execution_node_id`, `workflow_id`, `episode_id`, `sequence_index`, `agent_id`, `status`, `executed_at`, `content_hash`, `cia_identifier`); `SKILL_INVOKED` (`skill_invocation_id`, `execution_node_id`, `workflow_id`, `episode_id`, `skill_id`, `skill_source`, `invoked_by`, `invoked_at`, `status`, `content_hash`, `cia_identifier`); `WORKFLOW_CLOSED` (`workflow_id`, `final_status`, `status_updated_at`, `error_detail?`, `cia_identifier`).
+- **Failure Condition:** Any required field is absent from its event.
+
+---
+
+## 6. Layer-Invariant Vectors (§21 §2, §9)
+
+**L3-001** — Spine isolation (L3-I1) — first-class conformance
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §2 (L3-I1)
+- **Description:** No field of any Layer 3 node or edge may appear in the preimage of any Layer 1 or Layer 2 hash, and no Layer 1/2 node may embed a Layer 3 `node_id` by value in its hash preimage. **Layer 3 is cryptographically isolated from the Spine — Layer 3 data MUST NEVER enter Spine hash computation.** All Layer 3 → Layer 1/2 references are by `node_id` (UUID) only.
+- **Verification Protocol:** Freeze a Spine fingerprint; perform arbitrary Layer 3 writes; recompute the Spine fingerprint and assert it is byte-identical. Independently, inspect every Layer 1/2 hash preimage and confirm no Layer 3 `node_id` appears.
+- **Failure Condition:** Any Layer 3 write alters any Spine hash; any Spine/Layer-2 preimage contains a Layer 3 field or `node_id`. This is a cryptographic-chain-corrupting defect.
+
+**L3-002** — Layer 3 absence/corruption does not invalidate Layers 1/2
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §2 (consequence 2)
+- **Description:** A workspace whose Layer 3 is entirely absent or entirely corrupt MUST remain a valid ASTP workspace at Layers 1 and 2. Layer 3 is a strict augmentation, never a dependency.
+- **Verification Protocol:** Delete/corrupt all Layer 3 records; assert Layer 1 and Layer 2 verification still pass.
+- **Failure Condition:** Layer 1/2 verification depends on Layer 3 state.
+
+**L3-003** — Independent Layer 3 verification chain
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §2 (consequence 3), §21 §11
+- **Description:** Layer 3 integrity MUST be verifiable against its own audit chain (§11), independently of walking the Spine. Layer 3 verification confirms execution-record integrity; Layer 1 verification confirms cognitive integrity; the two are independent.
+- **Failure Condition:** Layer 3 verification requires Spine traversal, or vice versa.
+
+**L3-004** — Terminal-on-write immutability (L3-I3)
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §9 (L3-I3)
+- **Description:** `ExecutionNode` and `SkillInvocation` are fully immutable after creation. Every mutation attempt on any field of either type MUST be rejected. Neither type has a write-after-create path.
+- **Failure Condition:** Any field of a created `ExecutionNode` or `SkillInvocation` is successfully mutated.
+
+**L3-005** — WorkflowDeclaration mutation surface (L3-I4)
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §9 (L3-I4)
+- **Description:** The only mutable fields on `WorkflowDeclaration` are `status`, `status_updated_at`, and `error_detail`. Any attempt to mutate any other field MUST be rejected as a wire-tier violation; the permitted three are further constrained by the §10 state machine.
+- **Failure Condition:** Any field outside the permitted trio is mutated.
+
+**L3-006** — Retry-by-new-node (L3-I5)
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §9 (L3-I5)
+- **Description:** A retried execution step MUST produce a **new** `ExecutionNode` with a new `node_id` and a new `sequence_index`; the prior (failed) node MUST be preserved unchanged. Implementations MUST NOT provide a "retry" surface that mutates a prior node.
+- **Verification Protocol:** Record a `FAILED` step; retry; assert two distinct nodes exist, the original unchanged, sharing `step_name` but differing in `node_id` and `sequence_index`.
+- **Failure Condition:** A retry mutates the prior ExecutionNode, or reuses its `node_id`/`sequence_index`.
+
+**L3-007** — Seven edge names present and correctly directed
+- **Class:** REQUIRED
+- **Spec Reference:** §21 §7
+- **Description:** The implementation MUST expose query paths equivalent to the seven edges: `DECLARED_WITHIN` (Workflow→Episode, REQUIRED), `SERVES_INTENTION` (Workflow→Intention, OPTIONAL), `SPAWNED_BY_MANDATE` (Workflow→Mandate, OPTIONAL), `EXECUTES_WITHIN` (Execution→Workflow, REQUIRED), `PRECEDES` (Execution→Execution, OPTIONAL; absent on first step), `INVOKED_WITHIN` (Skill→Execution, REQUIRED), `SKILL_PRECEDES` (Skill→Skill, OPTIONAL). Edge *names* are normative; storage form is not.
+- **Failure Condition:** A required edge is unqueryable, misdirected, or renamed.
+
+**L3-008** — `PRECEDES` edge-type property
+- **Class:** RECOMMENDED
+- **Spec Reference:** §21 §7
+- **Description:** Where the `PRECEDES` edge is stored, it SHOULD carry the normative property `edge_type ∈ {SEQUENTIAL, CONDITIONAL, PARALLEL}` (the `PrecedesEdgeType` enum), recorded even when the default `SEQUENTIAL` applies, and `sequence_gap: Integer`. Additional implementation-specific edge properties are permitted but MUST NOT alter the semantics of the seven core edges.
+
+---
+
+## 7. Governance Rule Enforcement Matrix
+
+Layer 3 governance centers on the single numbered SPEC rule **G-36 (CIA Declaration)** — renumbered from its authoring numeral G-19 during the v3.2.1 integration (the original G-19 collided with the §19 Branch/Fork/Merge taxonomy). The remaining Layer 3 requirements are stated as **invariants** (L3-I1 … L3-I5) and **wire-tier conformance rules** (W-L3-1 … W-L3-4) rather than G-numbers.
+
+| Rule / Invariant | Scope | Vector(s) |
+|------------------|-------|-----------|
+| **G-36** | CIA sole-writer declaration + enforcement | CIA-001 |
+| L3-I1 | Spine isolation — no Layer 3 data in Spine hash | L3-001, L3-002, L3-003 |
+| L3-I2 | Sole writer (one CIA per node type) | CIA-001 |
+| L3-I3 | Terminal-on-write immutability | L3-004 |
+| L3-I4 | WorkflowDeclaration mutation surface | L3-005, WF-003 |
+| L3-I5 | Retry-by-new-node | L3-006 |
+| W-L3-1 | Hash determinism | WF-001, EX-001, SK-001 |
+| W-L3-2 | Hash field inclusion/exclusion | WF-001/002, EX-001/002, SK-001/002 |
+| W-L3-3 | Documented serialization | (declared in `ConformanceDeclaration`; see §8) |
+| W-L3-4 | Audit emission before durability | CIA-002, CIA-003, CIA-004 |
+| §10 state machine | Status transitions + auto-transition | WF-004, WF-005, WF-006 |
+| §5 error consistency | ExecutionNode error/status coupling | EX-003 |
+| §7 edges | Seven cross-layer edges | L3-007, L3-008 |
+| §13.2 deferral | `registry_id` null + hash-excluded | SK-002, SK-003 |
+
+---
+
+## 8. Conformance Levels
+
+### Level 1: Protocol Conformance (Wire + State tiers)
+
+Implementation passes all **REQUIRED** vectors in sections 2–6 and the governance matrix of section 7. This covers the SPEC §21 §12 **Wire tier** (node schemas §4–§6, edge names §7, hash preimage rules §8, immutability §9, state machine §10, audit events §11, CIA sole-writer §3) and **State tier** (status-transition semantics, retry-by-new-node, the two-`INTERRUPTED` distinction). No claim is made about storage layout, hash byte-form, or performance.
+
+### Level 2: Full Conformance (+ Behavioral tier documentation)
+
+Level 1 plus all **RECOMMENDED** vectors, plus the SPEC §21 §12 **Behavioral tier** audit-the-decision documentation obligations: the implementation MUST document, in its `ConformanceDeclaration`, its chosen **hash byte serialization** (W-L3-3, in enough detail that an independent verifier can reproduce any node's hash from its field values), its **`skill_source` vocabulary**, its **CIA enforcement mechanism**, its **audit chain-key dimension**, and its **edge storage representation**. These choices are unconstrained by the protocol but MUST be recorded.
+
+The Behavioral tier is **NOT REQUIRED** for protocol conformance; the audit-the-decision pattern requires only that each choice be documented, not that any particular choice be made. The Ignis OS reference chooses: SHA3-256 over field-ordered canonical JSON, the four `ignis_*` MCP tools as the sole CIA write path (`cia_identifier = ignis_mcp_server@<workspace_id>`), `episode_id` as the audit chain key, and native graph relationships for the seven edges.
+
+---
+
+## 9. Cross-Reference
+
+- **SPEC.md §21** — normative protocol surface (v3.2.1); §2 Spine isolation, §3 CIA / G-36, §4–§6 schemas, §7 edges, §8 hash preimages, §9 immutability, §10 state machine, §11 audit registry, §12 three-tier conformance, Appendix B conformance checklist.
+- **IMPLEMENTATION-LAYER3.md** — the reference deployment's adapter guide (non-normative; shipped with that adapter, not with the protocol): exact hash-preimage field orders, one storage layout, the reference CIA.
+- **CONFORMANCE-BFM.md** — Branch/Fork/Merge conformance vectors (§19).
+- Ground-truth code: `astp/core/workflow_execution.py` (schemas + `compute_*_content_hash` functions), `astp/core/hash_canonical.py` (reference canonicalizer), `astp/core/branching.py` (`CognitiveDeltaType` Layer 3 audit values).
+
+---
+
+*ASTP Layer 3 Conformance Test Vectors are maintained by Scorched Earth Labs.*
+*Vector set version: 1.0.0 | Applies to SPEC.md: v3.2.1 §21*

astp_docs_server/corpus/open/CONFORMANCE-REPRODUCIBILITY.md

@@ -0,0 +1,219 @@
+# ASTP — Reproducibility Conformance Test Vectors
+
+**Version:** 1.3.0
+**Status:** Working Draft
+**Authors:** Scorched Earth Labs
+**Date:** 2026-09-18
+**Applies To:** SPEC.md 5.0.0 — §5.1 Canonical Field Encoding, §5.2 Leaf Hash, §5.6 Episode Spine Leaf Set, §5.7 Episode Root, §5.8 Algorithm and Ordering Versions, §9.2 Inclusion Proof, §9.3 Reproducibility Obligation, G-1, G-40. RP-001 … RP-008 exercise the retained `spine_algorithm_version` 0 and 1 constructions, which every verifier of a 4.x seal must implement; RP-009 … RP-011 exercise `spine_algorithm_version` 2.
+**Companions:** [CONFORMANCE-CONTEXT.md](CONFORMANCE-CONTEXT.md) (`spine_algorithm_version` 3 — the spine root is byte-identical to version 2, so RP-009 … RP-011 apply to a version 3 seal unchanged; the sixth root field, `context_manifest_hash`, is exercised by CM-001 … CM-010), [CONFORMANCE-TRUST.md](CONFORMANCE-TRUST.md) (§16 trust infrastructure), [CONFORMANCE-BFM.md](CONFORMANCE-BFM.md), [CONFORMANCE-LAYER3.md](CONFORMANCE-LAYER3.md), [CONFORMANCE-CROSS-EPISODE-LINKING.md](CONFORMANCE-CROSS-EPISODE-LINKING.md)
+
+---
+
+## 1. Overview
+
+The Five-Test Gate (§9.1) is only as strong as the verifier's ability to rebuild the
+sealed root. These vectors test that ability directly. They exist because the first
+corpus-scale re-verification of a production deployment (2026-09-13, 62 sealed
+Episodes) found that 17 of them could not be rebuilt from stored nodes under the
+construction their seal claimed:
+
+| Outcome | Episodes |
+|---|---|
+| Root rebuilt from stored nodes | 45 |
+| Rebuilt only under an earlier tree function, which had been replaced in place | 8 |
+| Rebuilt only by searching the orderings of same-timestamp signals | 4 |
+| Not rebuilt under any construction — one has too many tied signals to search and had also accepted content after closure; the other is within reach of a longer search | 2 |
+| In a sealed status with no seal record at all, so no root to rebuild | 3 |
+
+Of the 57 seals that were rebuilt, none showed evidence of content tampering. The
+remaining 5 could not be evaluated: 2 did not rebuild under any construction, and 3
+have no root to rebuild. None of this was visible until a verifier tried to
+reproduce the roots.
+
+A conforming implementation MUST pass all vectors marked **REQUIRED**. Format follows
+[CONFORMANCE-TRUST.md §1](CONFORMANCE-TRUST.md).
+
+Reference implementation: `astp/core/schema.py` (`compute_spine_root_v2`,
+`compute_signal_manifest_hash`, `compute_exclusion_hash`, `compute_episode_root_hash`,
+`enforce_G1_write_guard`), tested in
+`tests/unit/protocol/test_reproducibility_conformance.py`.
+
+---
+
+## 2. Spine Reproducibility (§5.6, §9.3)
+
+**RP-001** — Spine Root From Stored Nodes Only
+- **Class:** REQUIRED
+- **Spec Reference:** §5.6, §9.3
+- **Description:** The spine root is a function of the Episode's non-ephemeral Segment content hashes in `sequence_index` order and, under `spine_algorithm_version` 1, the Episode's identifier (the Episode-identifier leaf, §5.6) — and nothing else. Two verifiers holding the same stored Segments and the same `episode_id` produce the same root; any state not on the nodes (insertion order, a store's default sort, a cache, the signals) plays no part.
+- **Inputs:**
+  ```
+  segment_content_hashes (sequence_index order): 7 hashes, SHA3-256("leaf-0") … SHA3-256("leaf-6")
+  episode_id: "550e8400-e29b-41d4-a716-446655440000"
+  spine_algorithm_version: 1
+  ordering_version: 2
+  ```
+- **Expected Output:**
+  ```
+  SHA3-256("leaf-0")                         aa6c290f56f0f7eb3a8da563ae72efc5d10cc89b88a3112c612d8e3825e20aad
+  Episode-identifier leaf input
+    SHA3-256(episode_id)                     0bdfe537564300a840a9b2279b3c4d0c8ca0e0c3b0c3d9c95c105852f991f222
+  spine_root  (spine_algorithm_version 1)    3cdbc3f20a909338a55a5b9687d72ce4b6f74ad1d3784a377c91b1bba06f2491
+  spine_root  (spine_algorithm_version 0,
+               same seven inputs)            0654211304f104a768b81432567776c7f13f65b97e4937f114f5c65e8dbc5fed
+  ```
+  Hash values enter the tree as 64-character lowercase hex strings, ASCII-encoded (§5.3); an unpaired node is carried up unchanged (§5.4). The root is **not** equal to the `ordering_version` 1 root computed with any signals included; it differs when the segment order is permuted; an empty leaf set is refused.
+- **Failure Condition:** Either root differs from the value above; the root changes when signals are added; the root is order-insensitive; an empty leaf set yields a root.
+
+---
+
+## 3. Signal Manifest (§5.7)
+
+**RP-002** — Signal Manifest Is a Set
+- **Class:** REQUIRED
+- **Spec Reference:** §5.7
+- **Description:** The signal manifest hash depends only on the *set* of SPINE-placed signal content hashes. Arrival order, timestamps, and duplicates do not change it; membership does. The empty manifest is well defined and distinct from the empty exclusion set. The Episode root changes when any component changes.
+- **Inputs:**
+  ```
+  signal_content_hashes: 5 hashes, SHA3-256("leaf-100") … SHA3-256("leaf-104"), presented in five different orders
+  construction: SHA3-256("SIGNAL_MANIFEST:v1:" || sorted hashes joined by "|"); empty → SHA3-256("SIGNAL_MANIFEST:v1:EMPTY")
+  exclusion: SHA3-256("EXCLUSION:v1:" || …); empty → SHA3-256("EXCLUSION:v1:EMPTY")
+  episode_root_hash = SHA3-256("NODE:" || spine_root || signal_manifest_hash || exclusion_hash)
+  ```
+- **Expected Output:**
+  ```
+  signal_manifest_hash (the five hashes, any order, with or without duplicates)
+                                             0a4a4582ad36da24dcd21853b07ed97d13a8c223cf14845588861d9d5786b670
+  signal_manifest_hash (SHA3-256("leaf-104") removed)
+                                             5b73a9aa0cf76aaa0399dce72733b48d5e441b7f236dc063d570eecdde5ff22d
+  signal_manifest_hash (empty)               5188531fe69daafc79126dfa880419494179ca220d60d5dda2fee8279d4ae847
+  exclusion_hash (empty)                     45849be4da47e279538916284a2ac74cd6acd60a67b9a8982992f97afa149be6
+  episode_root_hash  (RP-001 spine_root under spine_algorithm_version 1,
+                      the five-member manifest, empty exclusion set)
+                                             49c1b61c22d00c185dceca5eb39f65bd88c2666281444687c59c48b0b199d7fe
+  ```
+  The Episode root differs when the manifest or the exclusion set differs.
+- **Failure Condition:** Any value differs from the one above; any ordering-dependence; duplicates altering the hash; a root insensitive to a component.
+
+---
+
+## 4. Version Identifiers (§5.8)
+
+**RP-003** — Version Tags Select the Function and Stay Out of the Preimage
+- **Class:** REQUIRED
+- **Spec Reference:** §5.8
+- **Description:** A seal record carries `spine_algorithm_version` and `ordering_version`; a `CognitiveNode` carries `hash_version`. They are recorded and retrievable, default to absent (seal) / `1` (node) so pre-4.3.0 records read as legacy, and are **outside** every hash preimage: two seal records differing only in tags have the same content hash, and two nodes differing only in `hash_version` have the same leaf hash.
+- **Inputs:**
+  ```
+  CrystallizationDelta A: sealed_chain_root R, spine_algorithm_version 1, ordering_version 2
+  CrystallizationDelta B: sealed_chain_root R, no version tags
+  CognitiveNode N1: hash_version 1 (default);  N2: identical fields, hash_version 7
+  ```
+- **Expected Output:** A reports (1, 2); B reports (None, None); `content_hash(A) == content_hash(B)`; `leaf_hash(N1) == leaf_hash(N2)`.
+- **Failure Condition:** Tags not persisted; tags entering a preimage (content or leaf hash differs by tag alone); a tagless record read as current rather than legacy.
+
+---
+
+## 5. Fixed Record (G-1)
+
+**RP-004** — A Closed Episode Refuses Content
+- **Class:** REQUIRED
+- **Spec Reference:** G-1, §4.4.1
+- **Description:** A Segment or Signal commit against an Episode whose record is fixed MUST be refused with a governance error. Fixed means `CLOSING_PENDING_SEAL`, `CLOSED`, `CRYSTALLIZATION_PENDING`, `SEALING`, `SEALED`, `ARCHIVED`. Open means `CREATED`, `ACTIVE`, `PENDING_HITL`, `CLOSING`, `CRYSTALLIZED`. Codicils are exempt and use their own path.
+- **Inputs:** each `EpisodeStatus` value, presented to the write guard.
+- **Expected Output:** governance error for every fixed state — **`CLOSED` included**; no error for every open state.
+- **Failure Condition:** Any fixed state admits a commit. (The reference guard before 4.3.0 admitted `CLOSED`; the production corpus holds one post-closure append as a result.)
+
+---
+
+## 6. Resolved Signal Order (§5.8.1)
+
+These vectors share one fixture. Segments: the seven of RP-001. SPINE-placed Signals: the five of RP-002, `SHA3-256("leaf-100")` … `SHA3-256("leaf-104")`, stored in that (arrival) order, of which the middle three — `leaf-101`, `leaf-102`, `leaf-103` — share a timestamp. At seal time the Signals were folded in the order `leaf-100, leaf-103, leaf-101, leaf-102, leaf-104`. `episode_id` as in RP-001. `ordering_version` 1.
+
+```
+sealed_chain_root, spine_algorithm_version 1     1dda20e990cf757302e67f96173703a2a0f846feb2c6c0f34870a2e173aeed33
+sealed_chain_root, spine_algorithm_version 0     863ded60b9adce9cf3703b8892c5bf5263fa09153a81aa21778517789f9aa2c2
+root under the stored (arrival) order, version 1 2ff4e255c1e7470aa8a30a8b1fbde6cecb690e1d4ffaefb31a0ae26b6fce44ba   (≠ sealed: the seal is a tie-order seal)
+```
+
+**RP-005** — An Admissible Annotation Reproduces the Seal Without a Search
+- **Class:** REQUIRED for implementations that read or write `resolved_signal_order`
+- **Spec Reference:** §5.8.1, §9.3
+- **Description:** Given the fixture and `resolved_signal_order = [leaf-100, leaf-103, leaf-101, leaf-102, leaf-104]` (as content hashes), a verifier recomputes the spine once, under the seal's identifiers, and obtains the sealed root — for `spine_algorithm_version` 1 and, with the corresponding sealed root, for version 0.
+- **Expected Output:** the two `sealed_chain_root` values above; the annotation is reported admissible; no ordering other than the recorded one is tried.
+- **Failure Condition:** Either root differs; the verifier searches despite an admissible annotation.
+
+**RP-006** — An Annotation Is Checked, Never Trusted
+- **Class:** REQUIRED for implementations that read `resolved_signal_order`
+- **Spec Reference:** §5.8.1
+- **Description:** Three inadmissible annotations against the `spine_algorithm_version` 1 fixture. (a) *Wrong order:* `[leaf-100, leaf-101, leaf-103, leaf-102, leaf-104]` — a reordering of the stored Signals that does not reproduce the root. (b) *Foreign hash:* the correct order with its last entry replaced by `SHA3-256("x")`, which is not a Signal of the Episode. (c) *Tampered record:* the correct order, but the first Segment's content hash replaced by `SHA3-256("t")`.
+- **Expected Output:** each annotation is reported inadmissible and is ignored. In (a) and (b) the verifier proceeds as if no annotation were present and may still reproduce the seal by search. In (c) the seal does not reproduce under any order: the correct annotation does not rescue a tampered record.
+- **Failure Condition:** Any of the three is accepted; (c) verifies.
+
+**RP-007** — An `ordering_version` 2 Seal Ignores a Stray Annotation
+- **Class:** REQUIRED for implementations that read `resolved_signal_order`
+- **Spec Reference:** §5.8.1
+- **Description:** A seal tagged `ordering_version` 2 over the RP-001 segments (sealed root as in RP-001, `spine_algorithm_version` 1) whose delta nonetheless carries a `resolved_signal_order`.
+- **Expected Output:** the annotation is ignored; the seal verifies exactly as RP-001, to `3cdbc3f20a909338a55a5b9687d72ce4b6f74ad1d3784a377c91b1bba06f2491`.
+- **Failure Condition:** The annotation alters the recomputation or the outcome.
+
+**RP-008** — Absence of an Annotation Carries No Adverse Inference
+- **Class:** REQUIRED
+- **Spec Reference:** §5.8.1, §9.3
+- **Description:** The `spine_algorithm_version` 1 fixture with **no** annotation. Searching the orderings of the tied group (3! = 6) finds the sealed order. Separately, the same fixture with a sealed root that no ordering reproduces.
+- **Expected Output:** the first seal reproduces to the same `sealed_chain_root` as in RP-005 and is reported as reproduced — no weaker for having been found by search. The second is reported as not reproducible. The two outcomes MUST be distinguishable: "reproduced without an annotation" is not "could not be reproduced".
+- **Failure Condition:** A search-resolved seal is reported as weaker than, or different in root from, an annotated one; the two outcomes are conflated.
+
+---
+
+## 6a. Seal Construction Version 2 (SPEC 5.0.0 §5.1–§5.7, §9.2)
+
+The machine-readable vector file is [`vectors/5.0.0/seal-constructions.json`](./vectors/5.0.0/seal-constructions.json), regenerated by `vectors/5.0.0/generate.py` and never edited by hand. Every value in it is checked twice by the reference tests (`tests/conformance/test_*_v2_vectors.py`): against the package, and against a from-prose reference written from `SPEC.md` with `hashlib` alone. Fixture: `episode_id` `550e8400-e29b-41d4-a716-446655440000`; seven Segments with fixed `node_id`s `00000000-0000-4000-8000-00000000000i` and `content_hash = SHA3-256("leaf-i")`, `sequence_index` i, `schema_version` `"1.2.0"`, parent = the Episode; five SPINE-placed Signals; seven structural members; empty exclusion set. (Fixed `node_id`s are for reproducibility only; real `node_id`s MUST be random, SPEC §5.2.)
+
+**RP-009** — Version 2 Leaf Hash and Spine Root
+- **Requirement:** REQUIRED
+- **Spec Reference:** §5.1.1, §5.2, §5.4, §5.6
+- **Description:** From the fixture's stored fields, a verifier computes each Segment's `hash_version` 2 leaf hash under `LEAF_HASH:v2:` and the spine root under `TREE_LEAF:v2:` / `TREE_NODE:v2:` over raw bytes, with no Episode-identifier leaf.
+- **Expected:**
+```
+leaf_hash (hash_version 2), segment 0        25b617f0d7ac09871f88ce7e2851cc8f50b48305dee51d081b62a5f21ed84935
+spine_root (spine_algorithm_version 2), n=1  5e06ac5629faf452aa18836dcf3f33565db0cd2d8749b482c65365b9273b576e
+spine_root (spine_algorithm_version 2), n=7  4420e38a22409317822ac14e3d5bc8069e6556c0fc08928290f76d23396daa01
+```
+- **Failure Condition:** Any other value; computing a leaf hash from a stored version 1 leaf hash rather than from the fields; accepting hex-text tree inputs under version 2; computing a root for an empty leaf list.
+
+**RP-010** — Version 2 Sets and Episode Root
+- **Requirement:** REQUIRED
+- **Spec Reference:** §5.1.1 (sets), §5.7, §5.7.1
+- **Description:** The signal manifest, the structural manifest over the fixture's seven members, the empty exclusion set, and the Episode root over the Episode's UUID and the four components.
+- **Expected:**
+```
+signal_manifest_hash (v2), five members       70dbc8e8f2e87b63e49187979b14ad56ba11219b42be132015c23dcad36acb43
+exclusion_hash (v2), empty                    ddea405cc1729ebf63d93b16d723873ad02f9f64af3cc159bf86e5f999b02ce1
+structural_manifest_hash, seven members       0a4b777227b87ee0d6c8efd5b2e9a5fc05c02e61d677f2460f868ab06779b537
+episode_root_hash (v2)                        f0511b4d1be172554b9f87ec64d400d24a1409f1742ad72f628bf5ab7b7d33f0
+```
+- **Failure Condition:** Any other value; a set that depends on member order; an empty set hashed with a sentinel; removing a structural member leaving the Episode root unchanged; an Episode root computed over a string identifier.
+
+**RP-011** — Version 2 Inclusion Proof
+- **Requirement:** REQUIRED
+- **Spec Reference:** §9.2
+- **Description:** For the seven-leaf spine, a proof for leaf 3 carries three siblings and a proof for leaf 6 carries two; each verifies against the n=7 root at its own position and at no other; a proof whose sibling count does not fit the shape derived from `leaf_index` and `leaf_count` is refused. The vector file's `inclusion_proofs_v2` fixes the sibling lists.
+- **Failure Condition:** A proof verifying at a position other than its own; a proof accepted with a sibling count the shape does not admit; a verifier that requires stated path directions for a version 2 proof, or derives them for a 4.x proof.
+
+## 7. Governance Rule Enforcement Matrix
+
+| Governance Rule | Description | Test Vectors | Class |
+|----------------|-------------|-------------|-------|
+| **G-1** | Write guard — no appends to a fixed record | RP-004 | REQUIRED |
+| §9.3 | Reproducibility obligation | RP-001, RP-002, RP-003 | REQUIRED |
+| §5.8.1 | `resolved_signal_order` is checked, never trusted; absence carries no inference | RP-005, RP-006, RP-007, RP-008 | REQUIRED (RP-005–007 for implementations that use the annotation) |
+
+## 8. Out of Scope
+
+- How an implementation finds the order of same-timestamp Signals for an `ordering_version` 1 seal (search strategy, caps, scheduling). §6 covers what may be recorded once it is found and how a recorded order must be checked; a seal whose tied groups are too large to search, and which has no admissible annotation, is not reproducible, and no vector requires otherwise.
+- Re-sealing of historical records. Prohibited by §5.8 — a re-seal is a post-closure mutation.
+
+---
+
+*ASTP Reproducibility Conformance Test Vectors are maintained by Scorched Earth Labs.*