@ai-matrx/content-ir 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -1598,4 +1598,327 @@ declare function collectReferencedKinds(fields: Record<string, FieldSchema>): st
 declare function collectSchemaReferencedKinds(schema: KindSchema): string[];
 declare function kindSchemaToJsonSchema(kind: string, resolve: (kind: string) => KindSchema | undefined, options?: KindJsonSchemaOptions): KindJsonSchemaExport | null;
 
-export { type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type LegResult, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type Punct, ROOT_STORAGE_NAME, type RecordValueType, type RegionEndReason, type RegionFormat, type RegionSourceKind, type SavePlanEntry, type SavePlanValidation, type ScalarFieldType, type SchemaConversionResult, type SchemaLayoutMode, type SchemaResolver, type StoredFieldElement, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isScalarArrayType, kindSchemaToJsonSchema, kindSchemaToStorage, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readObjectKind, reconstructRegionValue, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, xmlDiscriminator };
+/**
+ * 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, type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type KindVerdict, type LegResult, NODE_OUTCOME_KIND, type NodeOutcomeWrapper, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type PartialKindEvent, type PartialKindNode, type PartialKindState, type Punct, ROOT_STORAGE_NAME, RUN_RESULT_KIND, type RecordValueType, type RegionEndReason, type RegionFormat, type RegionSourceKind, type RetractedKindEvent, type RunResultWrapper, type SavePlanEntry, type SavePlanValidation, type ScalarFieldType, type SchemaConversionResult, type SchemaLayoutMode, type SchemaResolver, type StoredFieldElement, type SupersededKindEvent, advancePartialKind, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emitPayloadFence, emitPayloadJson, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isProvisionalKind, isScalarArrayType, isTerminalKindEvent, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, makePartialKindStalenessGate, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };

package/dist/index.d.ts

@@ -1598,4 +1598,327 @@ declare function collectReferencedKinds(fields: Record<string, FieldSchema>): st
 declare function collectSchemaReferencedKinds(schema: KindSchema): string[];
 declare function kindSchemaToJsonSchema(kind: string, resolve: (kind: string) => KindSchema | undefined, options?: KindJsonSchemaOptions): KindJsonSchemaExport | null;
 
-export { type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type LegResult, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type Punct, ROOT_STORAGE_NAME, type RecordValueType, type RegionEndReason, type RegionFormat, type RegionSourceKind, type SavePlanEntry, type SavePlanValidation, type ScalarFieldType, type SchemaConversionResult, type SchemaLayoutMode, type SchemaResolver, type StoredFieldElement, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isScalarArrayType, kindSchemaToJsonSchema, kindSchemaToStorage, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readObjectKind, reconstructRegionValue, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, xmlDiscriminator };
+/**
+ * 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, type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type KindVerdict, type LegResult, NODE_OUTCOME_KIND, type NodeOutcomeWrapper, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type PartialKindEvent, type PartialKindNode, type PartialKindState, type Punct, ROOT_STORAGE_NAME, RUN_RESULT_KIND, type RecordValueType, type RegionEndReason, type RegionFormat, type RegionSourceKind, type RetractedKindEvent, type RunResultWrapper, type SavePlanEntry, type SavePlanValidation, type ScalarFieldType, type SchemaConversionResult, type SchemaLayoutMode, type SchemaResolver, type StoredFieldElement, type SupersededKindEvent, advancePartialKind, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emitPayloadFence, emitPayloadJson, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isProvisionalKind, isScalarArrayType, isTerminalKindEvent, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, makePartialKindStalenessGate, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };