@ai-matrx/content-ir 0.9.0 → 0.10.1

package/dist/wire.d.cts

@@ -0,0 +1,326 @@
+import { c as IR_VERSION, d as IrDiscriminator, f as IrPath, g as IrResidue } from './ir-types-95bA2cXH.cjs';
+
+/**
+ * Streaming partial kinds — the TS twin of the Python producer's contract.
+ *
+ * Cross-repo system-of-record (read it before changing anything here):
+ * `common-docs/systems/content-ir-system/STREAMING_PARTIAL_KINDS.md`.
+ * Python twin: `aidream/packages/matrx-graph/matrx_graph/content_ir/partial.py`.
+ *
+ * WHAT THIS IS
+ * ------------
+ * While a structured region streams, the server announces what it thinks the
+ * region IS and what has arrived so far, so the UI fills in progressively
+ * instead of showing a spinner until the closing brace. Three events, a CLOSED
+ * union on `state`, all riding `metadata.__ir_partial` on the `render_block`
+ * events this app already receives:
+ *
+ *   partial     — repeatable. A provisional instance whose `root.value` is
+ *                 VALID, CLOSED JSON (the server truncates and closes it, so
+ *                 this side never repairs or guesses). `kindState` is
+ *                 "speculative": it MAY still turn out to be something else.
+ *   superseded  — TERMINAL. The region completed as the announced kind; drop
+ *                 the provisional render, the block's own content/`__ir` is the
+ *                 truth.
+ *   retracted   — TERMINAL escape hatch. Detection was wrong; `becameKind` /
+ *                 `becameBlockType` name what it actually is. Never a silent
+ *                 swap.
+ *
+ * WHY IT IS NOT ON `__ir`
+ * -----------------------
+ * `__ir` means "validated against the registered schema", and a valid `__ir`
+ * is SEEDED into the fingerprint-keyed envelope memo. A provisional value
+ * there would poison every later read of that region. The two channels never
+ * touch: `classifyInboundEnvelopeMetadata` sees `absent` for a partial and
+ * passes the metadata through by reference.
+ *
+ * Pure kernel module: types + validators only. No React, no Redux, no IO.
+ * Lives in @ai-matrx/content-ir `wire/` so EVERY UI (Matrix, Workflow Studio,
+ * the dashboard, the Chrome extension, the desktop app) reads the channel
+ * through the same reader.
+ */
+
+/** The reserved metadata key carrying every event of this contract. */
+declare const IR_PARTIAL_KEY: "__ir_partial";
+type PartialKindState = "partial" | "superseded" | "retracted";
+/** The provisional node. Deliberately `IrStructuredNode`-shaped so existing IR readers work. */
+interface PartialKindNode {
+    role: "structured";
+    /** The server's DETECTION GUESS for this region. */
+    kind: string;
+    /** Always "speculative" on a partial — pre-recognition, not a resolved kind. */
+    kindState: "speculative";
+    discriminator: IrDiscriminator;
+    path: IrPath;
+    status: "streaming";
+    /**
+     * Valid, closed JSON carrying its own `__kind`. MAY be missing required
+     * schema fields — that is what `partial_unvalidated` in `residue.notices`
+     * says. A renderer that throws on an absent field is not partial-ready and
+     * must not be routed a provisional value.
+     */
+    value: Record<string, unknown>;
+    residue: IrResidue | null;
+}
+interface PartialKindEvent {
+    v: typeof IR_VERSION;
+    engine: string;
+    state: "partial";
+    /** Monotonic PER BLOCK — the ordering / staleness key. Keep the highest. */
+    seq: number;
+    fingerprint: string;
+    root: PartialKindNode;
+}
+interface SupersededKindEvent {
+    v: typeof IR_VERSION;
+    engine: string;
+    state: "superseded";
+    seq: number;
+    kind: string;
+}
+interface RetractedKindEvent {
+    v: typeof IR_VERSION;
+    engine: string;
+    state: "retracted";
+    seq: number;
+    /** The kind that was WRONGLY announced. */
+    kind: string;
+    reason: string;
+    /** What it actually is — null when it resolved to no registered kind. */
+    becameKind: string | null;
+    /** The detector's final block type, so a consumer re-routes without guessing. */
+    becameBlockType: string | null;
+}
+type AnyPartialKindEvent = PartialKindEvent | SupersededKindEvent | RetractedKindEvent;
+/**
+ * Read + validate a partial-channel event off a block's metadata.
+ *
+ * Returns null for anything malformed, foreign, or of an unknown `state`. A
+ * malformed partial degrades to "no live rendering" — never to a wrong render,
+ * and never to a thrown error inside a stream handler.
+ */
+declare function readPartialKindEvent(metadata: Record<string, unknown> | null | undefined): AnyPartialKindEvent | null;
+/**
+ * Ingest guard for the partial channel on a `render_block` event — the twin of
+ * `sanitizeInboundEnvelopeMetadata` for `__ir`, and it exists for the same
+ * reason: a malformed server event must be stripped at the wire boundary, not
+ * carried into Redux where every later reader has to re-decide whether to
+ * trust it.
+ *
+ * - no `__ir_partial` key → the SAME metadata reference back (zero-touch).
+ * - valid event → the SAME metadata reference back (idempotence law).
+ * - malformed → a COPY with the key stripped, plus a loud `reportMalformed`.
+ *   Dropping it degrades that block to "no live rendering" and nothing more.
+ *
+ * Pure: the host injects the reporter, exactly like the envelope gate, so
+ * aidream's Workflow Studio can bind its own.
+ */
+declare function sanitizeInboundPartialKindMetadata(metadata: Record<string, unknown> | null | undefined, context: {
+    blockId: string;
+}, hooks?: {
+    reportMalformed?: (info: {
+        blockId: string;
+        raw: unknown;
+    }) => void;
+}): Record<string, unknown> | undefined;
+/** Narrowing helper: is this the repeatable provisional event? */
+declare function isProvisionalKind(event: AnyPartialKindEvent | null): event is PartialKindEvent;
+/**
+ * Narrowing helper: is this a TERMINAL event? Every partial ends in exactly
+ * one of these — that law is what makes a stuck skeleton impossible, so a
+ * consumer clears its provisional render here and nowhere else.
+ */
+declare function isTerminalKindEvent(event: AnyPartialKindEvent | null): event is SupersededKindEvent | RetractedKindEvent;
+/**
+ * Per-block staleness gate. Events can be re-dispatched, replayed on reconnect,
+ * or arrive out of order; only a strictly higher `seq` advances a block.
+ * Returns null when the event should be ignored.
+ *
+ * Pure: the caller owns the `seen` map, so this composes into a reducer
+ * without hiding module state.
+ */
+declare function advancePartialKind(seen: Record<string, number>, blockId: string, event: AnyPartialKindEvent | null): AnyPartialKindEvent | null;
+/**
+ * The per-block staleness GATE, as a stateful closure over `advancePartialKind`
+ * — one per stream.
+ *
+ * `upsertRenderBlock` REPLACES the stored block, so an event landing on a block
+ * would regress what the user is looking at (a filled-in quiz snapping back to
+ * two questions, or a terminal being undone by a late `partial`). The highest
+ * accepted event is CARRIED FORWARD rather than dropped, so it is a no-op on
+ * screen instead of a flicker back to the skeleton.
+ *
+ * 🚨 TWO arrivals must be carried, and the second one is the common case:
+ *
+ *  1. A STALE key — a replay or an out-of-order event (`seq <= last`).
+ *  2. **NO key at all.** The producer clears `__ir_partial` at the top of every
+ *     stamp and re-adds it only when the value genuinely advanced
+ *     (`stream_processor.py::_stamp_partial` → `_partials.advanced(...)`), so
+ *     it is CORRECT for it to omit the key — re-shipping an identical payload
+ *     every token is pure wire cost. But the block still ships whole, and
+ *     replacing the stored block with one that has no partial metadata is what
+ *     made the provisional render vanish between advances: every non-advancing
+ *     token dropped the user back to the pending skeleton.
+ *
+ * Carrying stops at the TERMINAL, and only there. After `superseded` /
+ * `retracted` the region's truth is its own content or `__ir`, so resurrecting
+ * a provisional value would be a lie that outlives its own contract.
+ *
+ * Returns the metadata to store: the same reference when nothing changed, a
+ * copy with the carried-forward event otherwise.
+ */
+declare function makePartialKindStalenessGate(): (blockId: string, metadata: Record<string, unknown> | undefined) => Record<string, unknown> | undefined;
+
+/**
+ * Runtime wrapper kinds — the reader, and THE elision gate.
+ *
+ * Cross-repo contract (system of record):
+ * `common-docs/systems/content-ir-system/RUNTIME_WRAPPER_WIRE.md`.
+ *
+ * A runtime wrapper is the CLOSED set of envelopes that carry instance
+ * context with a data kind NESTED inside: `node_outcome` (one settled node
+ * invocation) and `run_result` (one terminated run, nesting one
+ * `node_outcome` per terminal node). `tool_result` is registered server-side
+ * but nothing emits it yet, so nothing here reads it.
+ *
+ * ## THE ELISION RULE — do it ONCE, here
+ *
+ * The payload is NEVER sent twice. On the wire `output` is `null` and
+ * `output_ref` names the FRAME field that already holds the value:
+ *
+ *  - `"output"`              → the frame's own `output` (`node_completed.output`,
+ *                              the run row's `output`).
+ *  - `"output.<node_id>"`    → that key of the frame's terminal output map.
+ *
+ * PRESENCE OF `output_ref` IS THE MARKER. A bare `output: null` with NO ref is
+ * a legitimately empty payload — never an elision, never something to go
+ * looking for. This is the same rule the `__ir` envelope follows with
+ * `value_ref`, for the same reason: otherwise every payload is serialized
+ * twice per streamed event, twice per durable row and twice per run read.
+ *
+ * Rehydration happens at the single INGEST GATE (each host's one ingest point —
+ * Matrix's workflow-runs reducer, the Studio's inbound-envelope gate),
+ * before anything reads the wrapper. No renderer, selector or component ever
+ * sees an un-rehydrated wrapper, so none of them may re-implement this.
+ *
+ * ## Never load-bearing
+ *
+ * Assembly is a pure read. A malformed wrapper yields `null` and the frame's
+ * own fields carry the surface exactly as they did before the wrapper
+ * existed — additive on the wire, additive here.
+ */
+/** The registered slugs — named once, never spelled by hand elsewhere. */
+declare const NODE_OUTCOME_KIND = "node_outcome";
+declare const RUN_RESULT_KIND = "run_result";
+/** One settled node invocation, with its data kind nested in `output`. */
+interface NodeOutcomeWrapper {
+    __kind: typeof NODE_OUTCOME_KIND;
+    run_id: string;
+    node_id: string;
+    workflow_id: string | null;
+    step: number | null;
+    attempt: number;
+    status: string;
+    started_at: string | null;
+    ended_at: string | null;
+    /** `0` is a REAL duration, not "unknown"; `null` is unknown. */
+    duration_ms: number | null;
+    /** null = the node declared no kind (a loud defect, never a pass). */
+    output_kind: string | null;
+    /** null = never checked / degraded — NEVER renderable as a pass. */
+    output_kind_ok: boolean | null;
+    output_kind_errors: string[] | null;
+    /** Rehydrated by {@link rehydrateNodeOutcome}; null = genuinely empty. */
+    output: unknown;
+}
+/** One terminated run. `outputs` is one wrapper per TERMINAL node. */
+interface RunResultWrapper {
+    __kind: typeof RUN_RESULT_KIND;
+    run_id: string;
+    workflow_id: string | null;
+    status: string;
+    started_at: string | null;
+    ended_at: string | null;
+    duration_ms: number | null;
+    output_kind: string | null;
+    output: unknown;
+    outputs: NodeOutcomeWrapper[];
+}
+/**
+ * Resolve a dotted `output_ref` against the frame that carries the payload.
+ * Returns `undefined` when the path does not resolve — the caller keeps
+ * `output: null` rather than inventing a value.
+ */
+declare function readOutputRef(frame: unknown, ref: string): unknown;
+/**
+ * Read a `node_outcome` off a frame and rehydrate its elided payload.
+ *
+ * `frame` is the object the wrapper travelled ON — the `node_completed` event,
+ * or the run read response for a `run_result`'s children. Returns null for
+ * anything that is not a node_outcome (including a missing wrapper: the
+ * producer fails OPEN, so an absent wrapper is a normal, non-fatal state).
+ */
+declare function rehydrateNodeOutcome(raw: unknown, frame: unknown): NodeOutcomeWrapper | null;
+/**
+ * Read an ALREADY-REHYDRATED node_outcome value into its typed form.
+ *
+ * Deliberately does NOT require `__kind`: the render bridge strips the root
+ * discriminator before the component sees the value, and it does NOT touch
+ * `output_ref` — by the time anything renders, the ingest gate has already
+ * resolved the elision, and a second resolution attempt against a frame that
+ * is no longer there is how a payload goes missing.
+ */
+declare function readNodeOutcomeValue(raw: unknown): NodeOutcomeWrapper | null;
+/**
+ * Read a `run_result` off the run read response and rehydrate every elided
+ * payload — its own, and each terminal node's. Both resolve against the SAME
+ * frame (the run read response), which is what `"output.<node_id>"` addresses.
+ */
+declare function rehydrateRunResult(raw: unknown, frame: unknown): RunResultWrapper | null;
+/**
+ * Read an ALREADY-REHYDRATED run_result value into its typed form. Same
+ * contract as {@link readNodeOutcomeValue}: no `__kind` requirement, no
+ * second elision pass.
+ */
+declare function readRunResultValue(raw: unknown): RunResultWrapper | null;
+/**
+ * The kind verdict, as three states the UI must keep distinct.
+ *
+ * `unchecked` is NEVER a pass: the engine either did not check (no declared
+ * kind) or checked and could not conclude. Collapsing it into "ok" is how a
+ * confidently-rendered document gets shown for a shape nobody verified.
+ */
+type KindVerdict = "passed" | "failed" | "unchecked";
+declare function kindVerdictOf(wrapper: {
+    output_kind: string | null;
+    output_kind_ok: boolean | null;
+}): KindVerdict;
+
+/**
+ * The forward composer: given a kind's stored example, produce the EMIT/RENDER
+ * payload — `{ "__kind": <slug>, ...data }`.
+ *
+ * Pure kernel module (@ai-matrx/content-ir `wire/`): no React, no Redux, no IO.
+ *
+ * Since 2026-08-23 stored examples and instances ALREADY carry their marker
+ * (`__kind` is part of the data — KINDS_EVERYWHERE_PLAN §4.2), so for a
+ * well-formed row this is an IDENTITY with a guarantee attached: the marker is
+ * the FIRST key and it names the right slug. It stays because it is also the
+ * repair for the legacy rows and hand-typed values that do not, and because a
+ * caller wanting a copy-ready render payload should not have to know which it
+ * has.
+ *
+ * Scalars/arrays are returned unchanged — for those kinds the identity travels
+ * out of band (`root.kind`); there is no key to add.
+ */
+declare function withRootKind(kind: string, value: unknown): unknown;
+/** The copy-ready render payload: pretty JSON of `{ __kind, ...data }`. */
+declare function emitPayloadJson(kind: string, value: unknown): string;
+/**
+ * The copy-ready render BLOCK — the render payload inside a ```json fence, the
+ * exact form an agent emits and a user pastes into a prompt or a message to see
+ * it render live.
+ */
+declare function emitPayloadFence(kind: string, value: unknown): string;
+
+export { type AnyPartialKindEvent, IR_PARTIAL_KEY, type KindVerdict, NODE_OUTCOME_KIND, type NodeOutcomeWrapper, type PartialKindEvent, type PartialKindNode, type PartialKindState, RUN_RESULT_KIND, type RetractedKindEvent, type RunResultWrapper, type SupersededKindEvent, advancePartialKind, emitPayloadFence, emitPayloadJson, isProvisionalKind, isTerminalKindEvent, kindVerdictOf, makePartialKindStalenessGate, readNodeOutcomeValue, readOutputRef, readPartialKindEvent, readRunResultValue, rehydrateNodeOutcome, rehydrateRunResult, sanitizeInboundPartialKindMetadata, withRootKind };

package/dist/wire.d.ts

@@ -0,0 +1,326 @@
+import { c as IR_VERSION, d as IrDiscriminator, f as IrPath, g as IrResidue } from './ir-types-95bA2cXH.js';
+
+/**
+ * Streaming partial kinds — the TS twin of the Python producer's contract.
+ *
+ * Cross-repo system-of-record (read it before changing anything here):
+ * `common-docs/systems/content-ir-system/STREAMING_PARTIAL_KINDS.md`.
+ * Python twin: `aidream/packages/matrx-graph/matrx_graph/content_ir/partial.py`.
+ *
+ * WHAT THIS IS
+ * ------------
+ * While a structured region streams, the server announces what it thinks the
+ * region IS and what has arrived so far, so the UI fills in progressively
+ * instead of showing a spinner until the closing brace. Three events, a CLOSED
+ * union on `state`, all riding `metadata.__ir_partial` on the `render_block`
+ * events this app already receives:
+ *
+ *   partial     — repeatable. A provisional instance whose `root.value` is
+ *                 VALID, CLOSED JSON (the server truncates and closes it, so
+ *                 this side never repairs or guesses). `kindState` is
+ *                 "speculative": it MAY still turn out to be something else.
+ *   superseded  — TERMINAL. The region completed as the announced kind; drop
+ *                 the provisional render, the block's own content/`__ir` is the
+ *                 truth.
+ *   retracted   — TERMINAL escape hatch. Detection was wrong; `becameKind` /
+ *                 `becameBlockType` name what it actually is. Never a silent
+ *                 swap.
+ *
+ * WHY IT IS NOT ON `__ir`
+ * -----------------------
+ * `__ir` means "validated against the registered schema", and a valid `__ir`
+ * is SEEDED into the fingerprint-keyed envelope memo. A provisional value
+ * there would poison every later read of that region. The two channels never
+ * touch: `classifyInboundEnvelopeMetadata` sees `absent` for a partial and
+ * passes the metadata through by reference.
+ *
+ * Pure kernel module: types + validators only. No React, no Redux, no IO.
+ * Lives in @ai-matrx/content-ir `wire/` so EVERY UI (Matrix, Workflow Studio,
+ * the dashboard, the Chrome extension, the desktop app) reads the channel
+ * through the same reader.
+ */
+
+/** The reserved metadata key carrying every event of this contract. */
+declare const IR_PARTIAL_KEY: "__ir_partial";
+type PartialKindState = "partial" | "superseded" | "retracted";
+/** The provisional node. Deliberately `IrStructuredNode`-shaped so existing IR readers work. */
+interface PartialKindNode {
+    role: "structured";
+    /** The server's DETECTION GUESS for this region. */
+    kind: string;
+    /** Always "speculative" on a partial — pre-recognition, not a resolved kind. */
+    kindState: "speculative";
+    discriminator: IrDiscriminator;
+    path: IrPath;
+    status: "streaming";
+    /**
+     * Valid, closed JSON carrying its own `__kind`. MAY be missing required
+     * schema fields — that is what `partial_unvalidated` in `residue.notices`
+     * says. A renderer that throws on an absent field is not partial-ready and
+     * must not be routed a provisional value.
+     */
+    value: Record<string, unknown>;
+    residue: IrResidue | null;
+}
+interface PartialKindEvent {
+    v: typeof IR_VERSION;
+    engine: string;
+    state: "partial";
+    /** Monotonic PER BLOCK — the ordering / staleness key. Keep the highest. */
+    seq: number;
+    fingerprint: string;
+    root: PartialKindNode;
+}
+interface SupersededKindEvent {
+    v: typeof IR_VERSION;
+    engine: string;
+    state: "superseded";
+    seq: number;
+    kind: string;
+}
+interface RetractedKindEvent {
+    v: typeof IR_VERSION;
+    engine: string;
+    state: "retracted";
+    seq: number;
+    /** The kind that was WRONGLY announced. */
+    kind: string;
+    reason: string;
+    /** What it actually is — null when it resolved to no registered kind. */
+    becameKind: string | null;
+    /** The detector's final block type, so a consumer re-routes without guessing. */
+    becameBlockType: string | null;
+}
+type AnyPartialKindEvent = PartialKindEvent | SupersededKindEvent | RetractedKindEvent;
+/**
+ * Read + validate a partial-channel event off a block's metadata.
+ *
+ * Returns null for anything malformed, foreign, or of an unknown `state`. A
+ * malformed partial degrades to "no live rendering" — never to a wrong render,
+ * and never to a thrown error inside a stream handler.
+ */
+declare function readPartialKindEvent(metadata: Record<string, unknown> | null | undefined): AnyPartialKindEvent | null;
+/**
+ * Ingest guard for the partial channel on a `render_block` event — the twin of
+ * `sanitizeInboundEnvelopeMetadata` for `__ir`, and it exists for the same
+ * reason: a malformed server event must be stripped at the wire boundary, not
+ * carried into Redux where every later reader has to re-decide whether to
+ * trust it.
+ *
+ * - no `__ir_partial` key → the SAME metadata reference back (zero-touch).
+ * - valid event → the SAME metadata reference back (idempotence law).
+ * - malformed → a COPY with the key stripped, plus a loud `reportMalformed`.
+ *   Dropping it degrades that block to "no live rendering" and nothing more.
+ *
+ * Pure: the host injects the reporter, exactly like the envelope gate, so
+ * aidream's Workflow Studio can bind its own.
+ */
+declare function sanitizeInboundPartialKindMetadata(metadata: Record<string, unknown> | null | undefined, context: {
+    blockId: string;
+}, hooks?: {
+    reportMalformed?: (info: {
+        blockId: string;
+        raw: unknown;
+    }) => void;
+}): Record<string, unknown> | undefined;
+/** Narrowing helper: is this the repeatable provisional event? */
+declare function isProvisionalKind(event: AnyPartialKindEvent | null): event is PartialKindEvent;
+/**
+ * Narrowing helper: is this a TERMINAL event? Every partial ends in exactly
+ * one of these — that law is what makes a stuck skeleton impossible, so a
+ * consumer clears its provisional render here and nowhere else.
+ */
+declare function isTerminalKindEvent(event: AnyPartialKindEvent | null): event is SupersededKindEvent | RetractedKindEvent;
+/**
+ * Per-block staleness gate. Events can be re-dispatched, replayed on reconnect,
+ * or arrive out of order; only a strictly higher `seq` advances a block.
+ * Returns null when the event should be ignored.
+ *
+ * Pure: the caller owns the `seen` map, so this composes into a reducer
+ * without hiding module state.
+ */
+declare function advancePartialKind(seen: Record<string, number>, blockId: string, event: AnyPartialKindEvent | null): AnyPartialKindEvent | null;
+/**
+ * The per-block staleness GATE, as a stateful closure over `advancePartialKind`
+ * — one per stream.
+ *
+ * `upsertRenderBlock` REPLACES the stored block, so an event landing on a block
+ * would regress what the user is looking at (a filled-in quiz snapping back to
+ * two questions, or a terminal being undone by a late `partial`). The highest
+ * accepted event is CARRIED FORWARD rather than dropped, so it is a no-op on
+ * screen instead of a flicker back to the skeleton.
+ *
+ * 🚨 TWO arrivals must be carried, and the second one is the common case:
+ *
+ *  1. A STALE key — a replay or an out-of-order event (`seq <= last`).
+ *  2. **NO key at all.** The producer clears `__ir_partial` at the top of every
+ *     stamp and re-adds it only when the value genuinely advanced
+ *     (`stream_processor.py::_stamp_partial` → `_partials.advanced(...)`), so
+ *     it is CORRECT for it to omit the key — re-shipping an identical payload
+ *     every token is pure wire cost. But the block still ships whole, and
+ *     replacing the stored block with one that has no partial metadata is what
+ *     made the provisional render vanish between advances: every non-advancing
+ *     token dropped the user back to the pending skeleton.
+ *
+ * Carrying stops at the TERMINAL, and only there. After `superseded` /
+ * `retracted` the region's truth is its own content or `__ir`, so resurrecting
+ * a provisional value would be a lie that outlives its own contract.
+ *
+ * Returns the metadata to store: the same reference when nothing changed, a
+ * copy with the carried-forward event otherwise.
+ */
+declare function makePartialKindStalenessGate(): (blockId: string, metadata: Record<string, unknown> | undefined) => Record<string, unknown> | undefined;
+
+/**
+ * Runtime wrapper kinds — the reader, and THE elision gate.
+ *
+ * Cross-repo contract (system of record):
+ * `common-docs/systems/content-ir-system/RUNTIME_WRAPPER_WIRE.md`.
+ *
+ * A runtime wrapper is the CLOSED set of envelopes that carry instance
+ * context with a data kind NESTED inside: `node_outcome` (one settled node
+ * invocation) and `run_result` (one terminated run, nesting one
+ * `node_outcome` per terminal node). `tool_result` is registered server-side
+ * but nothing emits it yet, so nothing here reads it.
+ *
+ * ## THE ELISION RULE — do it ONCE, here
+ *
+ * The payload is NEVER sent twice. On the wire `output` is `null` and
+ * `output_ref` names the FRAME field that already holds the value:
+ *
+ *  - `"output"`              → the frame's own `output` (`node_completed.output`,
+ *                              the run row's `output`).
+ *  - `"output.<node_id>"`    → that key of the frame's terminal output map.
+ *
+ * PRESENCE OF `output_ref` IS THE MARKER. A bare `output: null` with NO ref is
+ * a legitimately empty payload — never an elision, never something to go
+ * looking for. This is the same rule the `__ir` envelope follows with
+ * `value_ref`, for the same reason: otherwise every payload is serialized
+ * twice per streamed event, twice per durable row and twice per run read.
+ *
+ * Rehydration happens at the single INGEST GATE (each host's one ingest point —
+ * Matrix's workflow-runs reducer, the Studio's inbound-envelope gate),
+ * before anything reads the wrapper. No renderer, selector or component ever
+ * sees an un-rehydrated wrapper, so none of them may re-implement this.
+ *
+ * ## Never load-bearing
+ *
+ * Assembly is a pure read. A malformed wrapper yields `null` and the frame's
+ * own fields carry the surface exactly as they did before the wrapper
+ * existed — additive on the wire, additive here.
+ */
+/** The registered slugs — named once, never spelled by hand elsewhere. */
+declare const NODE_OUTCOME_KIND = "node_outcome";
+declare const RUN_RESULT_KIND = "run_result";
+/** One settled node invocation, with its data kind nested in `output`. */
+interface NodeOutcomeWrapper {
+    __kind: typeof NODE_OUTCOME_KIND;
+    run_id: string;
+    node_id: string;
+    workflow_id: string | null;
+    step: number | null;
+    attempt: number;
+    status: string;
+    started_at: string | null;
+    ended_at: string | null;
+    /** `0` is a REAL duration, not "unknown"; `null` is unknown. */
+    duration_ms: number | null;
+    /** null = the node declared no kind (a loud defect, never a pass). */
+    output_kind: string | null;
+    /** null = never checked / degraded — NEVER renderable as a pass. */
+    output_kind_ok: boolean | null;
+    output_kind_errors: string[] | null;
+    /** Rehydrated by {@link rehydrateNodeOutcome}; null = genuinely empty. */
+    output: unknown;
+}
+/** One terminated run. `outputs` is one wrapper per TERMINAL node. */
+interface RunResultWrapper {
+    __kind: typeof RUN_RESULT_KIND;
+    run_id: string;
+    workflow_id: string | null;
+    status: string;
+    started_at: string | null;
+    ended_at: string | null;
+    duration_ms: number | null;
+    output_kind: string | null;
+    output: unknown;
+    outputs: NodeOutcomeWrapper[];
+}
+/**
+ * Resolve a dotted `output_ref` against the frame that carries the payload.
+ * Returns `undefined` when the path does not resolve — the caller keeps
+ * `output: null` rather than inventing a value.
+ */
+declare function readOutputRef(frame: unknown, ref: string): unknown;
+/**
+ * Read a `node_outcome` off a frame and rehydrate its elided payload.
+ *
+ * `frame` is the object the wrapper travelled ON — the `node_completed` event,
+ * or the run read response for a `run_result`'s children. Returns null for
+ * anything that is not a node_outcome (including a missing wrapper: the
+ * producer fails OPEN, so an absent wrapper is a normal, non-fatal state).
+ */
+declare function rehydrateNodeOutcome(raw: unknown, frame: unknown): NodeOutcomeWrapper | null;
+/**
+ * Read an ALREADY-REHYDRATED node_outcome value into its typed form.
+ *
+ * Deliberately does NOT require `__kind`: the render bridge strips the root
+ * discriminator before the component sees the value, and it does NOT touch
+ * `output_ref` — by the time anything renders, the ingest gate has already
+ * resolved the elision, and a second resolution attempt against a frame that
+ * is no longer there is how a payload goes missing.
+ */
+declare function readNodeOutcomeValue(raw: unknown): NodeOutcomeWrapper | null;
+/**
+ * Read a `run_result` off the run read response and rehydrate every elided
+ * payload — its own, and each terminal node's. Both resolve against the SAME
+ * frame (the run read response), which is what `"output.<node_id>"` addresses.
+ */
+declare function rehydrateRunResult(raw: unknown, frame: unknown): RunResultWrapper | null;
+/**
+ * Read an ALREADY-REHYDRATED run_result value into its typed form. Same
+ * contract as {@link readNodeOutcomeValue}: no `__kind` requirement, no
+ * second elision pass.
+ */
+declare function readRunResultValue(raw: unknown): RunResultWrapper | null;
+/**
+ * The kind verdict, as three states the UI must keep distinct.
+ *
+ * `unchecked` is NEVER a pass: the engine either did not check (no declared
+ * kind) or checked and could not conclude. Collapsing it into "ok" is how a
+ * confidently-rendered document gets shown for a shape nobody verified.
+ */
+type KindVerdict = "passed" | "failed" | "unchecked";
+declare function kindVerdictOf(wrapper: {
+    output_kind: string | null;
+    output_kind_ok: boolean | null;
+}): KindVerdict;
+
+/**
+ * The forward composer: given a kind's stored example, produce the EMIT/RENDER
+ * payload — `{ "__kind": <slug>, ...data }`.
+ *
+ * Pure kernel module (@ai-matrx/content-ir `wire/`): no React, no Redux, no IO.
+ *
+ * Since 2026-08-23 stored examples and instances ALREADY carry their marker
+ * (`__kind` is part of the data — KINDS_EVERYWHERE_PLAN §4.2), so for a
+ * well-formed row this is an IDENTITY with a guarantee attached: the marker is
+ * the FIRST key and it names the right slug. It stays because it is also the
+ * repair for the legacy rows and hand-typed values that do not, and because a
+ * caller wanting a copy-ready render payload should not have to know which it
+ * has.
+ *
+ * Scalars/arrays are returned unchanged — for those kinds the identity travels
+ * out of band (`root.kind`); there is no key to add.
+ */
+declare function withRootKind(kind: string, value: unknown): unknown;
+/** The copy-ready render payload: pretty JSON of `{ __kind, ...data }`. */
+declare function emitPayloadJson(kind: string, value: unknown): string;
+/**
+ * The copy-ready render BLOCK — the render payload inside a ```json fence, the
+ * exact form an agent emits and a user pastes into a prompt or a message to see
+ * it render live.
+ */
+declare function emitPayloadFence(kind: string, value: unknown): string;
+
+export { type AnyPartialKindEvent, IR_PARTIAL_KEY, type KindVerdict, NODE_OUTCOME_KIND, type NodeOutcomeWrapper, type PartialKindEvent, type PartialKindNode, type PartialKindState, RUN_RESULT_KIND, type RetractedKindEvent, type RunResultWrapper, type SupersededKindEvent, advancePartialKind, emitPayloadFence, emitPayloadJson, isProvisionalKind, isTerminalKindEvent, kindVerdictOf, makePartialKindStalenessGate, readNodeOutcomeValue, readOutputRef, readPartialKindEvent, readRunResultValue, rehydrateNodeOutcome, rehydrateRunResult, sanitizeInboundPartialKindMetadata, withRootKind };