Module projection

Expand description

The projection protocol (spine §10, R14): renderer-agnostic read-only DTOs — the ONLY contract between any renderer and the store.

Five closed DTO families (spine §10.1): FlowGraphView (from FlowIR), RunTimelineEntry (from RunLog), StepDossierView (= the pointlock locate JSON shape), HumanInboxEntry (from the humanRequested/humanResponded pairing), and RunOverview (run summary + revision + per-step state map). Every top-level DTO carries projectionVersion: 1; evolution is additive-only, breaking changes bump the version, and the version is independent of irVersion (spine §10.3).

Discipline (08 §1 iron law 1, typed here): projections fold ledger facts, they never judge — every verdict/state below is what the runner recorded. No coordinates, no layout, no React Flow concepts (spine §10.1/§10.5): rendering concerns stay in the renderer.

Structs§

AlignmentSummary: Per-class alignment counts of the latest resume (08 §2.4 top bar).
AssertionSummary: One assertion summary row on an assert/action node (08 §3.4).
AttemptView: One attempt, enriched beyond the checkpoint’s discriminant-only AttemptRecord by joining the actionIntent/actionSettled events (07 §2.2: dossier attempts carry the ErrorInfo verbatim + timing).
BoundedValue: A bounded JSON digest (08 §4.4): truncation is always explicit.
FlowGraphView: The graph projection of one FlowIR (spine §10.1).
FrameEnvironment: The enclosing frame environment (07 §2.3 part 4).
GraphEdge: One semantic edge.
GraphNode: One graph node. id is the flow-scoped stepId (unique across the whole flow incl. nested regions — compiler-guaranteed, 08 §3.2).
HandlerTriggerView: One handler trigger against this instance.
HookBadge: A handler badge (08 §3.1 hook row): hook + disposition + budget.
HumanInboxEntry: One pending human request (step or supervision — purpose is the discriminator, spine A.4).
ProjectionVersion: The projection-protocol version marker, pinned to the JSON number 1 (spine §10.3). Additive evolution keeps the value; breaking changes bump it. Independent of irVersion — the projection is a read-side contract and never touches IR or checkpoint semantics.
RunOverview: The run summary (spine §10.1).
RunTimelineEntry: One timeline entry (spine §10.1 RunTimelineEntry).
SourceLocation: YAML source location resolved through the sourceMap (07 §2.3 part 2).
StepDossierView: The adjudicable dossier (spine §10.1; = pointlock locate JSON).
StepStateSummary: The minimal per-step overlay cell (2026-07-17 ruling, additive).
TimelineErrorView: Typed error surface on error-class entries (08 §4.2: ErrorClass + ErrorInfo{code, message, retryable}).
TimelineEvidenceRef: One evidence reference on a timeline entry — reference ONLY, never bytes (08 §4.3); dereference goes through the evidence route.
TimelinePage: One synchronous timeline page (08 §4.4: pagination never moves seen entries; revision tells the client when to re-pull).
VerdictRecordView: One recorded verdict in the append-only lineage (re-judgements append with supersedes; history is never deleted — 08 §2.5).

Enums§

GraphEdgeKind: The closed semantic edge classes (spine §10.1).
GraphNodeBody: Kind-specific node payloads (discriminant = step kind, A.4-aligned).
NodeRegion: Which nested sub-region of the parent a node lives in.
ProjectionSchemaFamily: One schema family of the projection protocol (closed five — spine §10.1; the timeline family’s root is the page envelope, which embeds RunTimelineEntry).
RunTimelineFilter: The five-value filter vocabulary (08 §4.2, verbatim from the DeviceRail TimelineFilter).
TimelineDetail: The typed per-event detail of one entry. A closed enum mirroring the 17-variant RunLog union, carrying only bounded summaries — full payloads stay in the dossier (08 §4.4).

Constants§

PROJECTION_SCHEMA_FAMILIES: The closed family list, in canonical emission order.
TIMELINE_EVIDENCE_MAX: At most 32 evidence references per entry (08 §4.4).
TIMELINE_JSON_MAX_BYTES: JSON digests truncate at 16 KiB serialized (08 §4.4).
TIMELINE_JSON_MAX_DEPTH: JSON digests truncate at depth 12 (08 §4.4).
TIMELINE_MAX_PAGE_SIZE: Hard page-size cap (08 §4.4, = LIVE_TIMELINE_MAX_PAGE_SIZE).
TIMELINE_TEXT_MAX_BYTES: Text fields truncate at 4 KiB (08 §4.4).

Functions§

flow_graph_view: Projects one FlowIR into its graph view. Deterministic and pure (08 §3.1); subflow bodies are NOT inlined — call nodes carry the callee identity for lazy loading (spine §10.1).
human_inbox: The cross-run inbox (08 §2.6): pending entries of every run, ordered by run creation then request seq.
locate_step: Resolves a locate --step argument to one instance path: a canonical path string (spine §9 grammar, matched by rendered equality against recorded instances — parse yields hash prefixes only), a JSON PathFrame[] document (07 §2.3: the structured form is the authority), or a bare step id (unique-match convenience; ambiguity is a typed error).
projection_schema: Generates one family’s schema.
projection_schemas: Generates all five families, in canonical order.
run_inbox: Scans one run’s ledger for pending entries, in request order.
run_overview: Projects one run’s overview from its ledger + metadata.
step_dossier: Builds the dossier of one instance. artifacts may carry the run’s FlowIR and its subflow closure; when the governing IR is absent the dossier still delivers the complete run record (irNode/source absent).
timeline_page: Projects one timeline page. page is 1-based; page_size is clamped to the hard cap (08 §4.4).