# Attested-Run Bundle Schema — Layer 3 Evidence Entity Type # KNO Schema Version: 0.1.0 # Version: 0.1.0 # Status: Experimental # CHANGELOG: # 0.1.0 (M275 P0/S2, #4062): Initial schema. Defines the GCN attested-run # bundle: AC set with forge refs, frame-segmented # recording refs, first-class AC-timeline mapping, # per-step OTel span links, builder/improver/judge # turn records with typed composition findings, # two artifact classes (process record + final # take), and the write-once immutability posture # for S6 (#4066) to implement. # # A GCN attested-run bundle is the auditable record of one journey run under # the GCN acceptance framework (anchor ps#4053): the acceptance criteria that # were checked, the screen recording that shows the run, the OTel spans that # trace it, the review turns that judged it, and the verdicts — one bundle, # auditable, whether the run was green or red. # # EXTENDS: document-schema.kno (which composes identity, history, quality) # CONFORMS TO: asciinema file format v2 (2021; v3 accepted where produced) — # the required substrate for analysis-grade terminal recordings this # schema references (tursi/tursi#1244 comment 71773 fidelity rule) # CONFORMS TO: W3C Trace Context Level 2 (2024) — the `traceparent` shape # carried by per-step span links # MAPS TO: OpenTelemetry span/trace identifiers (see specs/otel-spec.kno) — # span links resolve in the estate's SigNoz/OTel backend # MAPS TO: Playwright trace format (1.x) — browser-surface analysis # recordings reference Playwright trace/video artifacts # RELATED: design-system-review-schema.kno (the judge seat wears the # design-reviewer hat; finding severity vocabulary is shared) # RELATED: capability-registry-schema.kno (GCN lifts into the registry as a # portable capability per ps#4053 — this bundle shape is part of what lifts) # # ADOPTED CONVENTIONS (tursi/tursi#1244 — refinement convention source): # - Frame segmentation is a named evidence plane: recordings are segmented # into frames, and composition is judged whole-frame AND on the # SUCCESSION between frames, not only per-AC facts. # - Fidelity rule: asciinema casts are the ONLY composition-analysis # substrate for terminal surfaces; VHS renders are demo-grade only. # "Casts attest, tapes teach, hash-bound bundles" (tursi ADR-034). # - The frame walk saves as an auditable annotated artifact INSIDE the # bundle — the check itself leaves evidence. # - Red-run rider (comment 71805 / futro B-001): a failing run leaves its # bundle exactly as a passing one does. NO evidence field in this schema # is conditional on a passing verdict. # - Every bundle pins the build SHAs of the software under test, so # frame-walk comparisons are build-pinned pairs. # # KEY DESIGN DECISIONS (M275 P0): # - The .kno instance IS the bundle manifest; heavy artifacts (casts, # traces, videos, annotated frames, assertion logs) are content-addressed # references (uri + sha256), stored write-once by S6. # - The AC-timeline mapping (which AC ↔ which frames ↔ which spans) is a # FIRST-CLASS required section — it is the viewer's (ps#4060) seed data, # not something the viewer derives. # - Two artifact classes as distinct, linked records: the PROCESS RECORD # (all builder/improver/judge iterations, failures included) and the # FINAL TAKE (clean happy path, derived from the process record). A red # run has a process record and honestly NO final take (no-stubbed-work). # - Surface-agnostic seam: `substrate` is discriminated per surface # (playwright-trace | playwright-video | asciinema | vhs) so the shape # lifts to the registry without rewrite when new surfaces (desktop) land. # - Acceptance = ALL ACs pass AND composition passes. A screen whose every # element passes but whose composition fails cannot pass (the gate-7 # wall-of-text class). # # THREE-GATE TEST (kno-foundational-principles.md § 0.6) — why a NEW schema: # Gate 1 (Distinctness): YES — nearest neighbors all fail structurally. # bundle-definition-schema is a Curated Pointer-Projection (surfaces[] + # filters + persona; composition rules for a downloadable zip) with no # run identity, no verdicts, no evidence semantics. design-system-review- # schema records findings of a design review but has no recording plane, # no frame segmentation, no span links, no AC set, no build pins, and no # immutability posture — extending it would overload a review document # with a run-evidence manifest. observation-schema captures single # telemetry observations, not a triangulated multi-plane run record. # Gate 2 (Reusability): YES — every GCN-accepted journey run on every # surface (browser, terminal, TUI, desktop later) across every consumer # of the lifted capability (tursi first, pfi-foundry at S4/S8) produces # an instance; S7's viewer and S6's store consume it. # Gate 3 (Clarity): YES — first-class named planes (acceptance_criteria, # recordings, ac_timeline, records, immutability) beat stuffing evidence # refs into document metadata; the viewer, the store, and the auditors # each read a named section. # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY (Layer 1) # ============================================================================= id: 01K9GCN0RB4X2VW8MJT3QH5FD7 slug: attested-run-bundle-schema type: spec version: 0.1.0 # ============================================================================= # VISIBILITY DECLARATION (REQ-18) — collection default # ============================================================================= # Attested-run bundle entities are OPERATIONAL ACCEPTANCE EVIDENCE — they # contain screen recordings, span links, and build SHAs of internal flows. # Collection default is `organizer`: per REQ-18 that means REST + MCP + A2A # surface parity, NO llms.txt projection. Individual entities MAY override # (last-write-wins at the entity level) — e.g. a bundle promoted to a public # demo asset — but promotion is a deliberate per-entity act, never a default. visibility: organizer # ============================================================================= # STANDARD TIER # ============================================================================= title: "Attested-Run Bundle Schema" purpose: | Define the schema for GCN attested-run bundles — the auditable record of one journey run under the GCN acceptance framework (ps#4053). **What is an attested-run bundle?** When a journey (e.g. j-admin-door, j-arrival) runs under GCN, the run leaves a bundle that triangulates three evidence planes and the judgment made over them: | Plane | What it carries | Source | |-------|-----------------|--------| | Facts | AC set with forge refs + observable-fact text, per-AC verdicts | tracker + judge seat | | Sight | frame-segmented screen recording + composition verdicts + annotated frame walk | recorder + judge seat | | Trace | per-step OTel span links | instrumented software under test | The bundle is judged by the builder/improver/judge triad: two agents converge the work until a third (wearing the design-reviewer hat) rules that all ACs pass AND the composition — whole frames and the succession between frames — passes. Collaborative converge, not adversarial. **Red runs bundle too.** A failing run leaves its assertion log, cast, trace, and manifest exactly as a passing run does. No field here is conditional on a green verdict (tursi/tursi#1244 comment 71805). **Two artifact classes, distinct and linked:** | Class | Contents | Grade | |-------|----------|-------| | process record | every iteration, failures included, assertion log | analysis | | final take | the clean happy-path recording, derived from the process record | analysis + optional demo renders | A red run has a process record and NO final take — honestly absent, never stubbed. Demo renders (VHS tapes, GIFs) may only hang off the final take: casts attest, tapes teach. **The AC timeline is the viewer's seed data.** `ac_timeline` maps each AC to the frames and spans that evidence it; the S7 viewer (ps#4060) renders its AC rail directly from this section. **Write-once.** Every artifact reference is content-addressed (sha256); the manifest itself is write-once and superseded, never edited (S6, ps#4066 implements the store). # ============================================================================= # RICH TIER — Provenance & Taxonomy # ============================================================================= provenance: origin: id: 01K9GCN0RB4X2VW8MJT3QH5FD7 timestamp: "2026-09-02T00:00:00Z" tool: claude-code note: | Drafted for M275 P0/S2 (#4062), anchor ps#4053, viewer ps#4060. Adopts tursi/tursi#1244's frame-segmentation convention verbatim: frames + succession as the composition plane (body, deliverable 1); asciinema-only fidelity rule for terminal analysis with VHS demoted to demo grade (comment 71773, refinement 1; tursi ADR-034 "casts attest, tapes teach, hash-bound bundles"); annotated proof-of-check artifact inside the bundle (body, deliverable 2); builder/improver/judge triad with the design-reviewer hat on the judge seat (deliverables 3-4); red-run completeness and build-SHA pinning (comment 71805, futro B-001); capability-seam cleanliness so the shape lifts into the Possibility Space Registry without rewrite (comment 71773 refinement 2, comment 72735) — hence the surface-discriminated `substrate` enum rather than a hardcoded recorder. Recording tool roster fixed by operator 2026-09-01 (M275 milestone body): Playwright, asciinema, VHS (demo-take generator), tui-test (assertion harness — its output is the assertion log, not a recording substrate). taxonomy: topics: - acceptance - evidence - verification - observability - recordings keywords: - gcn - attested-run - bundle - acceptance-criteria - frame-segmentation - composition - asciinema - playwright - otel - span - verdict - immutability - content-addressing - process-record - final-take # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to KNO format specification v0.0.9" - xri: "kno://specs/document-schema" reason: "Extends the document composition (identity, history, quality)" - xri: "kno://specs/otel-spec" reason: "Per-step span links resolve against the estate OTel/SigNoz backend" related_to: - xri: "kno://specs/design-system-review-schema" reason: "The judge seat wears the design-reviewer hat; severity vocabulary is shared" - xri: "kno://specs/capability-registry-schema" reason: "GCN lifts into the registry (ps#4053); this bundle shape travels with it" - xri: "kno://specs/quality-schema" reason: "Bundle verdicts are run-scoped acceptance, distinct from entity quality review" enables: - xri: "kno://content/attested-runs/*" reason: "Attested-run bundle instances conform to this schema" - xri: "kno://specs/api-spec" reason: "S7 viewer (ps#4060) and S6 store (ps#4066) read/write this shape" # ============================================================================= # RICH TIER — Quality # ============================================================================= quality: completeness: 0.70 last_reviewed: "2026-09-02" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY (P9 Temporal) # ============================================================================= _history: retention: full format: changelog changelog: - version: "0.1.0" date: "2026-09-02" author: "claude" summary: "Initial attested-run bundle schema (M275 P0/S2, #4062)" changes: - "AC set with forge refs, observable-fact text, per-AC judge verdicts" - "Frame-segmented recording refs, substrate-discriminated per surface" - "First-class ac_timeline (AC ↔ frames ↔ spans) as viewer seed data" - "Builder/improver/judge turn records with typed composition findings" - "Two artifact classes: process record + final take, distinct and linked" - "Red-run completeness and build-SHA pinning per tursi#1244 c71805" - "Write-once, content-addressed immutability posture for S6" # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Draft description: | ## Bundle structure An attested-run bundle instance (`type: attested-run-bundle`) is the manifest of one journey run. Heavy artifacts live in the S6 store and are referenced by `{uri, sha256, media_type}` — every reference is content-addressed. The instance carries six required sections (`run`, `acceptance_criteria`, `recordings`, `ac_timeline`, `records`, `immutability`) and three recommended sections (`steps`, `turns`, `composition`). ## Acceptance rule `run.outcome` is `green` only when every `acceptance_criteria[].verdict` is `pass` AND `composition.verdict` is `pass`. Composition is judged whole-frame and on the succession between frames — a run whose every element passes but whose composition fails is `red` (detectability test, tursi#1244). # =========================================================================== # REQUIRED SECTIONS (top-level keys of a conforming instance) # =========================================================================== required_sections: - name: run description: "Run identity: journey, surface, outcome, build pins, seats" - name: acceptance_criteria description: "The AC set with forge refs, observable-fact text, verdicts" - name: recordings description: "Frame-segmented recording references, substrate-discriminated" - name: ac_timeline description: "FIRST-CLASS AC ↔ frames ↔ spans mapping — the viewer's seed data" - name: records description: "The two artifact classes: process_record (+ optional final_take)" - name: immutability description: "Content-addressing and write-once posture of this bundle" recommended_sections: - name: steps description: "Per-step records with OTel span links and frame anchors" - name: turns description: "Builder/improver/judge turn protocol records with typed findings" - name: composition description: "Frame + succession verdicts and the annotated proof-of-check artifact" # =========================================================================== # FIELD SPECIFICATIONS # =========================================================================== required_fields: run: type: object description: "Identity and context of the run" structure: run_id: type: string description: "ULID of the run" journey: type: object description: "The journey under test: {id, ref} — ref is a tracker ref (e.g. tursi/tursi#1028)" surface: type: enum values: ["browser", "terminal", "tui", "desktop"] description: "Surface class of the software under test; discriminates valid substrates" outcome: type: enum values: ["green", "red"] description: >- Overall run outcome. Red runs produce a complete bundle: NO other field in this schema is conditional on a green outcome (tursi#1244 c71805). started_at: type: string description: "ISO-8601 start of the run" ended_at: type: string description: "ISO-8601 end of the run" build_pins: type: array description: >- REQUIRED, min 1. [{repo, ref, sha}] — the exact build SHAs of the software under test, so frame-walk comparisons are build-pinned pairs, never 'whatever was mid-rebase'. seats: type: object description: >- The triad: {builder, improver, judge}, each {agent, model?, hats?[]}. The judge seat wears the design-reviewer hat wherever GCN runs (hats MUST include 'design-reviewer' on the judge seat). acceptance_criteria: type: array description: "The AC set, one entry per criterion" structure: ac_id: type: string description: "Stable id within the bundle (e.g. ac-1)" forge_ref: type: string description: "Tracker ref for the AC's issue (e.g. 'ps#4068', 'pfi-foundry#41 AC2')" text: type: string description: "Observable-fact phrasing of the criterion — what a viewer can see is true" verdict: type: enum values: ["pass", "fail", "blocked", "not-evaluated"] description: "The judge seat's ruling on this AC" verdict_by: type: string description: "Seat that ruled (must be 'judge', or the seat being presented to)" evidence: type: array description: "ac_timeline entry ids and/or artifact refs backing the verdict" recordings: type: array description: "Frame-segmented recording references" structure: recording_id: type: string description: "Stable id within the bundle (e.g. rec-1)" substrate: type: enum values: ["playwright-trace", "playwright-video", "asciinema", "vhs"] description: >- Recording substrate, discriminated per surface (capability-seam cleanliness — new surfaces add enum values, never a rewrite). grade: type: enum values: ["analysis", "demo"] description: >- FIDELITY RULE (tursi#1244 c71773): analysis grade on terminal/tui surfaces MUST be substrate asciinema — casts record what is on screen; VHS does not. substrate vhs MUST be grade demo. Analysis and demo refs are different field classes; never conflate. artifact: type: object description: "{uri, sha256, media_type} — content-addressed reference into the S6 store" frames: type: array description: >- The frame segmentation (a bundle production step: cast → frames via agg, trace → frames via step markers). Each frame: {frame_id, index, start, end, step_ids[], label}. start/end are substrate-native offsets (seconds for casts/video, action indexes for traces). ac_timeline: type: array description: >- FIRST-CLASS mapping of AC ↔ frames ↔ spans — the S7 viewer's (ps#4060) seed data for its AC rail. Every AC with verdict pass or fail MUST have at least one entry. structure: ac_id: type: string description: "The AC this entry evidences" recording_id: type: string description: "The recording the frames belong to" frame_ids: type: array description: "Frames in which this AC's observable fact is (or fails to be) visible" span_ids: type: array description: "OTel span ids (from steps[].span) correlated to this AC" records: type: object description: "The two artifact classes — distinct, linked records" structure: process_record: type: object description: >- REQUIRED. The full acceptance loop: {record_id, recording_ids[], turn_range, includes_failures: true, assertion_log: {uri, sha256}}. Iterations and failures included — this is the class a red run always has. assertion_log is the tui-test / test-runner output. final_take: type: object description: >- OPTIONAL. The clean happy-path take: {record_id, derived_from (MUST reference process_record.record_id), recording_id (analysis-grade), demo_renders[]: [{substrate, artifact}]}. Present ONLY when a clean take exists — a red run has none (honestly absent, never stubbed). Demo renders (vhs, gif) may only appear here: casts attest, tapes teach. immutability: type: object description: "The bundle's write-once posture — S6 (#4066) implements the store" structure: content_addressing: type: enum values: ["sha256"] description: "Digest algorithm for all artifact references" write_once: type: boolean description: "MUST be true — bundles are never edited after sealing" bundle_digest: type: string description: >- sha256 over the canonical serialization of this manifest at sealing time (hash-bound bundle, tursi ADR-034) supersedes: type: string description: >- OPTIONAL — xri of an earlier bundle this one replaces. Amendment = new bundle + supersedes, never mutation. optional_fields: steps: type: array description: >- Per-step run records: {step_id, description, span: {trace_id, span_id, traceparent (W3C Trace Context)}, frame_id?}. The span plane lands fully at S5 (#4065); the field shape is fixed here. turns: type: array description: >- The builder/improver/judge protocol record: {turn, seat (builder|improver|judge), hats[], findings[]}. Findings are TYPED entries in the same turn record: {finding_id, type (ac-fact | composition-frame | composition-succession), subject (ac_id, frame_id, or 'frame_id..frame_id' pair), severity? (BLOCKER | MAJOR | MINOR | COSMETIC, per design-system-review vocabulary), note, resolved_by_turn?}. composition: type: object description: >- The composition plane: frame_verdicts[] ({frame_id, verdict, notes}), succession_verdicts[] ({from_frame, to_frame, verdict, notes}), annotated_artifact ({uri, sha256, kind: annotated-frames | gif+notes}) — the saved frame walk, the proof that the check itself left evidence — and verdict (pass|fail). Overall acceptance requires this verdict AND all AC verdicts to pass. # =========================================================================== # VALIDATION RULES # =========================================================================== # Rollout honesty (specs.md § Schema-Rollout Reality Check): the collection # is new (0 instances), but no dedicated lint exists yet — kno:validate's # domain pass checks section presence only. All rules ship `warn` until an # enforcement lint lands (S3/S6 riders); promote per-rule with baseline # comments at that point. validation: rules: - name: red_run_completeness rollout: warn # no enforcement lint yet; promote when lint lands (0-instance baseline) description: >- run, acceptance_criteria, recordings, ac_timeline, records.process_record, and immutability MUST all be present when run.outcome is red, exactly as when green. - name: terminal_analysis_substrate_is_asciinema rollout: warn description: >- For surface terminal|tui, every recording with grade analysis MUST have substrate asciinema; substrate vhs MUST have grade demo. - name: ac_timeline_coverage rollout: warn description: >- Every acceptance_criteria entry with verdict pass|fail MUST be referenced by at least one ac_timeline entry. - name: build_pins_required rollout: warn description: "run.build_pins MUST contain at least one {repo, ref, sha} entry." - name: final_take_linkage rollout: warn description: >- records.final_take, when present, MUST carry derived_from referencing records.process_record.record_id, and MUST NOT be present when run.outcome is red. - name: content_addressed_artifacts rollout: warn description: "Every artifact reference MUST carry both uri and sha256." - name: acceptance_conjunction rollout: warn description: >- run.outcome green requires all AC verdicts pass AND composition.verdict pass (when composition is present). - name: judge_wears_design_reviewer_hat rollout: warn description: "run.seats.judge.hats MUST include design-reviewer."