@ai-matrx/content-ir 0.9.0 → 0.10.1

package/dist/index.d.cts

@@ -1,2030 +1,9 @@
-import { ComponentType } from 'react';
-
-/**
- * The canonical IR contract for structured content.
- *
- * Every source (live agent stream, DB reload, Python-preprocessed results,
- * notes, any future surface) is normalized into these shapes exactly once.
- * Anything already carrying this IR passes through downstream layers by
- * reference — see `core/normalize.ts` for the idempotence law.
- *
- * This file is pure types + path helpers. No React, no Redux, no IO.
- */
-/** Path of a value inside a parsed region (object keys + array indices). */
-type IrPath = Array<string | number>;
-/**
- * How a node's kind was (or wasn't) established.
- *
- * 🚨 `unverified` IS NOT `raw`, AND THE DIFFERENCE IS LOAD-BEARING (Arman's
- * ruling, 2026-08-29). "We checked it and it is wrong" and "we had nothing to
- * check it with" are opposite facts about a payload, and collapsing them cost
- * ~221 live kinds their component overnight: a kind whose schema never loaded
- * degraded to `raw`, the render route read `raw` as "broken instance", and
- * perfectly valid payloads were dumped as key/value lists instead of reaching
- * the component the user built. A consumer that treats `unverified` as a
- * failure is reintroducing that outage — the data is intact and MAY be
- * entirely valid; all that is missing is the schema that would prove it.
- */
-type IrKindState = "resolved" | "speculative" | "pending_kind" | "pending_schema" | "unverified" | "raw";
-/**
- * System-level zero-data-loss channel. Unknown keys are NEVER merged into a
- * node's `value` (they'd be indistinguishable from schema fields); they are
- * carried here verbatim — Protobuf unknown-fields discipline. Distinct from
- * any domain-level `additionalDetails` field, which is an ordinary schema
- * field inside `value`.
- */
-interface IrResidue {
-    /** Keys present in the source object but absent from the kind schema. */
-    extra: Record<string, unknown> | null;
-    /** Optional schema fields the source never provided. */
-    optionalMissing: string[] | null;
-    /** Structured warnings attached during parsing (speculation backtracks, truncation, …). */
-    notices: Array<{
-        code: string;
-        message: string;
-        at?: number;
-    }> | null;
-}
-/** Which wire syntax carried the kind discriminator for a node. */
-type IrDiscriminator = {
-    format: "json";
-    key: "__kind";
-} | {
-    format: "xml";
-    tag: string;
-} | {
-    format: "fence";
-    language: string;
-};
-/** A schema-shaped structured node. Children live inside `value` (and carry their own metadata via `nodeIndex`). */
-interface IrStructuredNode {
-    role: "structured";
-    /** Canonical kind slug. Empty string while pending. */
-    kind: string;
-    kindState: IrKindState;
-    discriminator: IrDiscriminator;
-    /** Region-relative path ([] = region root). */
-    path: IrPath;
-    status: "streaming" | "complete" | "error";
-    /** Compliant snapshot: schema fields + __kind ONLY. Unknown keys → residue. */
-    value: Record<string, unknown>;
-    residue: IrResidue | null;
-}
-/** Envelope version. Bump = migration point for persisted envelopes. */
-declare const IR_VERSION: 1;
-/** Reserved key carrying the envelope inside RenderBlockPayload.data. */
-declare const IR_ENVELOPE_KEY: "__ir";
-/**
- * One parsed region's canonical form. Serializable (plain JSON), carried on
- * render blocks (`data.__ir`), persisted on artifacts and message metadata,
- * and — with `engine: "py-block-detector"` — accepted pre-built from Python.
- */
-interface CanonicalBlockIR {
-    v: typeof IR_VERSION;
-    /** Provenance: which implementation produced this envelope. */
-    engine: "fe-kind-parser" | "py-block-detector";
-    /** Stable hash of the region source text — the idempotence / cache key. */
-    fingerprint: string;
-    root: IrStructuredNode;
-    /**
-     * pathKey → node metadata for per-path readers (child kinds under root).
-     * Carries each child node's residue — child snapshot values inside
-     * `root.value` hold schema fields only, so WITHOUT this the envelope would
-     * silently drop nested unknown keys (zero-data-loss violation).
-     */
-    nodeIndex?: Record<string, Pick<IrStructuredNode, "kind" | "kindState" | "status"> & {
-        residue?: IrResidue | null;
-    }>;
-}
-/** Normalizer output segment: prose stays raw text; structured regions carry IR. */
-type CanonicalSegment = {
-    role: "text";
-    content: string;
-} | {
-    role: "block";
-    blockType: string;
-    content: string;
-    ir: CanonicalBlockIR | null;
-};
-interface CanonicalContent {
-    v: typeof IR_VERSION;
-    segments: CanonicalSegment[];
-}
-declare function irPathKey(path: IrPath): string;
-declare function irPathsEqual(left: IrPath, right: IrPath): boolean;
-declare function irPathIsUnderOrEqual(path: IrPath, prefix: IrPath): boolean;
-/** Human label for a path ("root", "cards[2].front"). */
-declare function irPathLabel(path: IrPath): string;
-/** True when every residue channel is empty — normalize to null instead. */
-declare function isEmptyResidue(residue: IrResidue): boolean;
-
-/**
- * KindSchema — the data-defined field model for a registered kind.
- *
- * `__kind` (KIND_KEY) is the carried discriminator: it is NOT part of a
- * kind's field map; the parser enforces it via `KindSchema.kind` and stamps
- * it onto every compliant snapshot.
- *
- * Moved from app/(dev)/demos/json-block-detector/kind-schemas.ts.
- *
- * 2026-07-15 expressivity extension (A2) — four constructs the Python-owned
- * pydantic schemas need that the v1 vocabulary could not express:
- *   - `{type:"json"}` / `{type:"json[]"}` — any JSON value / array of any
- *     JSON values (pydantic bare `Any` fields, `items: {}` arrays, `{}`
- *     schemas). A `json` value is implicitly nullable — `null` IS a JSON
- *     value — so `nullable` is meaningless (and ignored) on it.
- *   - `record` values widened to `"json"` (pydantic `dict[str, Any]` /
- *     `additionalProperties: true`).
- *   - `union` may now carry `kinds` (object unions — anyOf over kind refs,
- *     optionally mixed with scalars). Refs externalize to `kind_edge` rows
- *     exactly like `array.itemKinds`.
- *   - `KindSchema.root` — a NON-OBJECT root form: the kind's VALUE is the
- *     root field itself (scalar / array / json / open object), not a `__kind`
- *     object with fields. Root-form kinds are data-only: the streaming
- *     `__kind` parser cannot type them (a scalar cannot carry a
- *     discriminator) and refuses them loudly; validation goes through the
- *     emitted JSON Schema (ajv / Pydantic). `root` and a non-empty `fields`
- *     are mutually exclusive.
- *   - `inline_object.open` — `additionalProperties: true`; fixes the
- *     open-empty-object defect where an open `inline_object{fields:{}}`
- *     materialized as CLOSED (schema_proposal / item_presentation class).
- *
- * 2026-07-15 input-semantics extension (W3-A, agent-input bridge) — the
- * constructs the Wave-1 sufficiency survey of all 1,529 live agent variables
- * showed FieldSchema could not carry, added so `AgentVariable` ⇄ kind
- * conversion is faithful:
- *   - `FieldBase.description` — human guidance; round-trips JSON Schema
- *     `description` and VariableDefinition `helpText`.
- *   - `FieldBase.default` — the field's default VALUE (JSON Schema `default`,
- *     VariableDefinition `defaultValue`). Annotation-level: validators never
- *     apply it; emitters carry it verbatim.
- *   - `enum.open` — "one of these options OR any string" (the FE's
- *     `allowOther`). Emits as `anyOf: [{type:"string", enum}, {type:"string"}]`
- *     so the option set survives instead of widening to bare `string`.
- *   - `number` bounds `min`/`max`/`step` — JSON Schema
- *     `minimum`/`maximum`/`multipleOf` (number/slider components).
- *   - `string[].values` (+ `open`) — an items-enum: array of strings drawn
- *     from an option set (checkbox components), `open` meaning the set is
- *     advisory (`allowOther` on a multi-select).
- * Picklist bindings, scope bindings, and media component identity are
- * PROVENANCE, not structure — they never enter FieldSchema; the bridge
- * carries them out-of-band (see convert/kind-variable-bridge.ts sidecar).
- */
-/** System discriminator — hardcoded, not part of per-kind field schemas. */
-declare const KIND_KEY = "__kind";
-type ScalarFieldType = "string" | "number" | "boolean";
-type ArrayItemScalarType = "string" | "number" | "boolean";
-/** Value domain of a `record` field — typed scalars, or any JSON value. */
-type RecordValueType = ArrayItemScalarType | "json";
-type FieldBase = {
-    required?: boolean;
-    nullable?: boolean;
-    /** Human guidance — JSON Schema `description` / variable `helpText`. */
-    description?: string;
-    /**
-     * Default VALUE (JSON Schema `default` / variable `defaultValue`).
-     * Annotation-level: validators never apply it; emitters carry it verbatim.
-     */
-    default?: unknown;
-};
-type FieldSchema = (FieldBase & {
-    type: "string" | "boolean";
-}) | (FieldBase & {
-    type: "number";
-    /** Inclusive lower bound — JSON Schema `minimum`. */
-    min?: number;
-    /** Inclusive upper bound — JSON Schema `maximum`. */
-    max?: number;
-    /** Increment — JSON Schema `multipleOf`. Annotation-level in the parser. */
-    step?: number;
-}) | (FieldBase & {
-    type: "string[]";
-    /** Items-enum: each item must be one of these values (checkbox option sets). */
-    values?: string[];
-    /** With `values`: the set is advisory — any string item is also legal (`allowOther`). */
-    open?: boolean;
-}) | (FieldBase & {
-    type: "number[]" | "boolean[]";
-}) | (FieldBase & {
-    type: "json";
-}) | (FieldBase & {
-    type: "json[]";
-}) | (FieldBase & {
-    type: "array";
-    itemKinds: string[];
-}) | (FieldBase & {
-    type: "object";
-    kind: string;
-}) | (FieldBase & {
-    type: "inline_object";
-    fields: Record<string, FieldSchema>;
-    /** additionalProperties: true — unknown keys are legal, not residue-only. */
-    open?: boolean;
-}) | (FieldBase & {
-    type: "record";
-    values: RecordValueType;
-}) | (FieldBase & {
-    type: "enum";
-    values: string[];
-    /** "One of these OR any string" — the option set is advisory (`allowOther`). */
-    open?: boolean;
-}) | (FieldBase & {
-    type: "union";
-    scalars: Array<"string" | "number" | "boolean">;
-    /** Object union members — kind refs (anyOf of $refs), may mix with scalars. */
-    kinds?: string[];
-});
-/**
- * Domain fields only — __kind is enforced by the parser via KindSchema.kind
- * (block slug). A kind with `root` set has NO field map (fields stays `{}`):
- * its value is the root field's type at the top level. See the module header.
- */
-type KindSchema = {
-    kind: string;
-    fields: Record<string, FieldSchema>;
-    /** Non-object root form — mutually exclusive with a non-empty `fields`. */
-    root?: FieldSchema;
-};
-declare function readObjectKind(value: Record<string, unknown>): string | null;
-declare function isScalarArrayType(type: FieldSchema["type"]): type is "string[]" | "number[]" | "boolean[]";
-declare function scalarArrayItemType(type: "string[]" | "number[]" | "boolean[]"): ArrayItemScalarType;
-/**
- * Does this field's value domain accept ANY JSON shape (object/array/scalar/
- * null alike)? True for `json` and `json[]` ITEMS — the parser treats the
- * subtree under such a field as opaque (no kind identification, no raw_object
- * degradation: unknown structure is the declared contract, not a failure).
- */
-declare function isJsonAnyField(field: FieldSchema): boolean;
-
-/**
- * KindStreamParser — the streaming, schema-validating, __kind-discriminated
- * JSON parser at the heart of content-ir.
- *
- * Frame-stack pushdown parser over JsonStreamTokenizer tokens. Every value is
- * path-addressed; every object resolves a kind against the schema registry;
- * schema-shaped `block_snapshot` events fire on field arrival so renderers
- * get live partials; unknown/invalid structures degrade to `raw_object`
- * instead of failing the stream.
- *
- * The pushdown discipline (commit → descend → never re-ask → backtrack):
- * - SPECULATIVE DESCENT: when a parent field schema predicts a child's kind
- *   ({type:"object", kind} or {type:"array", itemKinds:[K]} with one member),
- *   the child commits to that kind THE INSTANT `{` opens and renders a
- *   placeholder snapshot. `__kind` arrival confirms (no-op), re-tags (allowed
- *   sibling kind), or backtracks to raw (contradiction). An object under a
- *   predicting parent doesn't even need `__kind` — prediction alone types it.
- * - PENDING SCHEMA: an identified kind whose schema isn't loaded holds the
- *   node open (`pending_schema` event, fields keep accumulating), fires the
- *   resolver's cold fetch, and upgrades in place via `notifySchemaArrived` —
- *   even after the node (or the whole region) has closed.
- * - POP-UP-ONE-LEVEL: node-scoped problems (duplicate key, schema violation,
- *   disallowed itemKind) mark THAT node raw and keep parsing the parent.
- *   Only grammar/tokenizer errors are region-fatal — and the host degrades
- *   the region to a plain code block, never the stream.
- */
-
-/** Kept as the historical name for the parser's event paths. */
-type JsonPath = IrPath;
-/**
- * Schema source abstraction. A plain Record works for static sets; the
- * registry supplies a resolver whose `request` fires a cold fetch and later
- * calls `parser.notifySchemaArrived`.
- */
-interface SchemaResolver {
-    get(kind: string): KindSchema | undefined;
-    /** Fire-and-forget cold fetch. Absent = static source, unknown kinds go raw. */
-    request?(kind: string): void;
-    /**
-     * Optional per-resolver override for legacy root-key recognition. Most hosts
-     * leave this unset and register the lookup once via
-     * `setJsonRootKeyLookup` — see that function for why.
-     */
-    kindForJsonRootKey?(key: string): string | null;
-}
-declare function setJsonRootKeyLookup(lookup: ((key: string) => string | null) | null): void;
-/**
- * Why a node degraded off the `resolved` path.
- *
- * `"unverified"` is reserved for ONE situation: no schema was registered for
- * an identified kind, so no check ever ran. Every other degrade — a schema
- * violation, an array-item kind mismatch, a duplicate key, a bad field
- * placement, a contradicted speculation — is `"invalid"`: something checked
- * the node and it failed.
- */
-type RawObjectCause = "unverified" | "invalid";
-type KindStreamEvent = {
-    type: "kind_identified";
-    kind: string;
-    path: JsonPath;
-    /** True when committed from the parent schema before __kind arrived. */
-    speculative?: boolean;
-    at: number;
-} | {
-    type: "pending_kind";
-    path: JsonPath;
-    at: number;
-} | {
-    type: "kind_wait_end";
-    path: JsonPath;
-    outcome: "identified" | "raw_fallback";
-    kind?: string;
-    reason?: string;
-    at: number;
-} | {
-    type: "pending_schema";
-    kind: string;
-    path: JsonPath;
-    at: number;
-} | {
-    type: "field";
-    kind: string;
-    path: JsonPath;
-    key: string;
-    value: unknown;
-    at: number;
-} | {
-    type: "object_start";
-    path: JsonPath;
-    at: number;
-} | {
-    type: "object_complete";
-    kind: string;
-    path: JsonPath;
-    value: Record<string, unknown>;
-    at: number;
-} | {
-    type: "raw_object";
-    path: JsonPath;
-    value: unknown;
-    reason: string;
-    /**
-     * The kind that WAS identified for this node before it degraded — set
-     * for schema-availability degrades AND (since 2026-08-29) structural
-     * ones, so a payload that said what it is stays acknowledged as an
-     * instance of that kind. Absent only when nothing ever identified it
-     * (an object with no `__kind` at all).
-     */
-    kind?: string;
-    /**
-     * WHY this node is not `resolved` — the discriminator the render route
-     * reads. See `IrKindState` for why collapsing these two is an outage.
-     *
-     * - `"unverified"`: no schema was available, so nothing was checked.
-     *   The value is intact and may be perfectly valid.
-     * - `"invalid"` (default): a check RAN and the node failed it, or the
-     *   node is structurally broken (duplicate key, bad placement).
-     */
-    cause?: RawObjectCause;
-    at: number;
-} | {
-    type: "optional_field_missing";
-    kind: string;
-    path: JsonPath;
-    field: string;
-    at: number;
-} | {
-    type: "extra_field";
-    kind: string;
-    path: JsonPath;
-    field: string;
-    at: number;
-} | {
-    type: "block_snapshot";
-    kind: string;
-    path: JsonPath;
-    value: Record<string, unknown>;
-    residue: IrResidue | null;
-    complete: boolean;
-    at: number;
-} | {
-    type: "array_start";
-    path: JsonPath;
-    field: string;
-    at: number;
-} | {
-    type: "complete";
-    kind: string;
-    value: unknown;
-    at: number;
-} | {
-    type: "error";
-    reason: string;
-    at: number;
-};
-type KindStreamParserOptions = {
-    onEvent: (event: KindStreamEvent) => void;
-    schemas: Record<string, KindSchema> | SchemaResolver;
-    /**
-     * Known-context root prediction (e.g. "this agent's output schema is
-     * flashcard_set"). The root commits speculatively at `{` open — the Option-1
-     * provenance path for agents whose schemas don't carry __kind yet.
-     */
-    expectedRootKind?: string;
-};
-declare class KindStreamParser {
-    private readonly resolver;
-    private readonly stack;
-    private readonly objectKinds;
-    private readonly inlineSchemas;
-    private readonly recordSchemas;
-    private readonly rawObjectPaths;
-    /**
-     * Subtrees whose value domain is "any JSON" by schema (`json` / `json[]`
-     * fields, `record` with `values:"json"` members). OPAQUE by contract: no
-     * kind identification, no pending_kind, no raw_object degradation — unknown
-     * structure here is the declared shape, not a failure. Propagates to every
-     * descendant compound.
-     */
-    private readonly opaquePaths;
-    private readonly deferredFields;
-    private readonly awaitingKindPaths;
-    /** Paths whose kind came from parent-schema prediction, unconfirmed so far. */
-    private readonly speculativeKinds;
-    /**
-     * Kind named by the root object's FIRST key through the `json_root_key`
-     * surface registry — a candidate, adopted only at root finalize.
-     */
-    private rootSurfaceKind;
-    /** kind → paths (by key) waiting for the resolver's cold fetch. */
-    private readonly pendingSchemaPaths;
-    /** Pending-schema paths whose object already closed. */
-    private readonly closedPendingPaths;
-    /** Schemas delivered via notifySchemaArrived (overlay over the resolver). */
-    private readonly arrivedSchemas;
-    private tokenizer;
-    private root;
-    private rootKind;
-    private rootDone;
-    private failed;
-    private readonly options;
-    constructor(options: KindStreamParserOptions);
-    push(chunk: string): void;
-    end(): void;
-    private resolvePendingSchemasAsRaw;
-    /** True once the root value has closed — the region is fully consumed. */
-    get isComplete(): boolean;
-    get hasFailed(): boolean;
-    /**
-     * Upgrade-in-place: the registry's cold fetch answered. Pending nodes for
-     * this kind validate and complete (closed nodes retroactively); a null
-     * schema (fetch miss) drops them to raw. Safe to call after end().
-     */
-    notifySchemaArrived(kind: string, schema: KindSchema | null): void;
-    private handleToken;
-    private handleString;
-    private handlePunctuation;
-    private beginCompound;
-    /**
-     * THE JSON-ROOT-KEY SURFACE — `content_ir.kind_surface` rows of type
-     * `json_root_key`, live at last (they were inert phantom rows until
-     * 2026-08-20).
-     *
-     * A legacy payload such as `{"quiz_title": ...}` carries no `__kind`, but
-     * the ONE surface registry knows exactly which kind that root key names —
-     * the same lookup the SERVER performs before adapting the payload
-     * (`aidream .../processing/blocks/envelope.py`). Consulting it HERE, in the
-     * shared parser core, is what makes one place decide it: both hosts — the
-     * one-shot `normalizeJsonRegion` (DB reload / reconcile) and the live
-     * `openParseSession` (streaming) — build their parser through
-     * `createKindStreamParser`, so neither passes an option and neither can
-     * drift from the other.
-     *
-     * Recorded at the first root key; ADOPTED only when the root object closes
-     * (`completeTypedObject`). That is the surface registry's complete-only
-     * convergence law, and every json_root_key row is `streaming:false` — these
-     * legacy shapes are recognized by their whole payload, so speculating
-     * mid-stream would flash a kind component over an object that may never
-     * satisfy the schema. An explicit `expectedRootKind` (an agent's declared
-     * output schema) is stronger context and always wins; an actual `__kind`
-     * still wins over both.
-     */
-    private noteRootSurfaceKind;
-    /**
-     * Prediction from the parent schema: object field → declared kind; array
-     * item → sole itemKind; root → expectedRootKind. Only when the schema is
-     * actually resolvable (a prediction we can't validate against is not a
-     * commitment worth making).
-     */
-    private resolveSpeculativeKind;
-    /**
-     * A schema usable for OBJECT speculation/snapshots — root-form kinds
-     * (non-object data-only shapes) are never a valid object commitment.
-     */
-    private lookupObjectSchema;
-    private beginScalar;
-    private placeValue;
-    private acceptObjectKey;
-    private acceptColon;
-    private acceptComma;
-    private closeCompound;
-    /**
-     * True when a value placed at `path` sits directly under a json-any
-     * placement: a `json`/`json[]` FIELD, or a member of a `record` whose
-     * values are `"json"`. (Deeper descendants inherit via `opaquePaths`.)
-     */
-    private isJsonAnyPlacement;
-    private onValueFinalized;
-    /** __kind arrived for an object — confirm speculation, identify, or backtrack. */
-    private onKindDiscriminatorArrived;
-    /** A contradicted speculation may re-tag only where the new kind is legal. */
-    private speculativeRetagAllowed;
-    private addPendingSchemaPath;
-    private completeTypedObject;
-    /** Validate + complete an object whose value carries __kind. */
-    private finalizeTypedObject;
-    /** Validate + complete an object typed purely by parent prediction. */
-    private finalizeSpeculatedObject;
-    private validateArrayItemKind;
-    private completeRoot;
-    /** Mark a node raw (node-scoped failure) without killing the stream. */
-    private markNodeRaw;
-    /**
-     * Degrade ONE node off the resolved path.
-     *
-     * `cause` defaults to `"invalid"` deliberately: every call site that omits
-     * it is a real failure (validation, duplicate key, placement, contradicted
-     * speculation). ONLY the "no schema registered" sites pass `"unverified"`,
-     * and they are the reason the parameter exists — see `IrKindState`.
-     */
-    private emitRawObject;
-    private clearKindWait;
-    private emitFieldIfReady;
-    private flushDeferredFields;
-    private getLiveObjectValue;
-    private emitBlockSnapshotForObject;
-    /**
-     * On `complete` snapshots (and post-close schema upgrades) the frame has
-     * already been popped — the finalized value lives in the root tree.
-     */
-    private getFinalizedObjectValue;
-    private validateFieldPlacement;
-    private emitSchemaNotices;
-    private validateObjectAgainstSchema;
-    private validateFinalFieldValue;
-    private validateValueAgainstField;
-    private validateScalarField;
-    private validateRecordScalar;
-    private validateRecordObject;
-    private validateObjectAgainstFields;
-    private registerObjectContext;
-    private resolveParentFieldSchema;
-    private getObjectKindForPath;
-    private getDirectObjectKind;
-    private isAllowedSchemaField;
-    private parentFieldName;
-    private fieldKeyFromPath;
-    private isKindFieldPath;
-    private pathKey;
-    private lookupSchema;
-    private fail;
-    private emit;
-    private currentFrame;
-}
-declare function createKindStreamParser(options: KindStreamParserOptions): KindStreamParser;
-
-/**
- * IrTree — the immutable, structurally-shared view of a parsed region.
- *
- * Consumes KindStreamEvents and maintains one node per kind-resolved path.
- * Node values are STABILIZED: compound children that are themselves kind
- * nodes are substituted by their current tree value, so an update to
- * cards[7] produces new identities for root → cards → cards[7] ONLY;
- * cards[0..6] keep referential identity and memoized components bail out.
- *
- * Parser frame values are NEVER exposed — everything handed out is rebuilt
- * copy-on-write, so it is safe to freeze (Redux dev-mode immutability) and
- * safe to hold across renders.
- *
- * Both the live ParseSession and the one-shot normalizer build their
- * CanonicalBlockIR from this tree — one assembly path, structurally
- * identical output for stream and static input.
- */
-
-interface IrTreeNode {
-    kind: string;
-    kindState: IrKindState;
-    path: IrPath;
-    pathKey: string;
-    /** Stabilized immutable snapshot value (schema fields + __kind only). */
-    value: Record<string, unknown>;
-    residue: IrResidue | null;
-    complete: boolean;
-    /** Bumps on every update to this node (incl. child propagation). */
-    version: number;
-}
-declare class IrTree {
-    private readonly nodes;
-    private readonly rawPaths;
-    private readonly dirty;
-    /**
-     * KIND PRESERVATION (streaming db/cloud kinds): pathKey → identified kind
-     * for nodes whose kind is KNOWN (kind_identified / pending_schema) but that
-     * have no snapshot node yet because the schema is still cold-fetching.
-     * Without this, the envelope reports `kind: ""` for the whole pending
-     * window and the render seam can only show raw JSON.
-     */
-    private readonly identifiedKinds;
-    /** pathKeys currently waiting on a schema cold fetch. */
-    private readonly pendingSchemaPaths;
-    /**
-     * Early top-level scalar fields (title, loading_message, …) captured for
-     * identified-but-schema-pending nodes — the loading-component fuel. Scalars
-     * only (no live parser references can escape through here). Superseded the
-     * moment a real snapshot node exists.
-     */
-    private readonly earlyFields;
-    /**
-     * pathKey → identified kind preserved through a raw fallback (parser stamped
-     * `kind` on the raw_object event) — schema-availability degrades and, since
-     * 2026-08-29, structural ones too. Only a node nothing ever identified (no
-     * `__kind` at all) is absent here.
-     */
-    private readonly rawKinds;
-    /**
-     * pathKey → WHY the node degraded. `"unverified"` means no schema was
-     * available and nothing was ever checked; `"invalid"` means a check ran and
-     * failed. THE RENDER ROUTE BRANCHES ON THIS — see `IrKindState`. Absent =
-     * `"invalid"`, so a parser that predates the `cause` field (or any consumer
-     * hand-building events) keeps the strict, safe reading.
-     */
-    private readonly rawCauses;
-    private regionStatus;
-    private errorReason;
-    private rootRawValue;
-    /** Notices for degrades that tried to erase already-published data. */
-    private readonly rescueNotices;
-    private completedKind;
-    get status(): "streaming" | "complete" | "error";
-    applyEvent(event: KindStreamEvent): void;
-    getNode(pathKey: string): IrTreeNode | null;
-    listNodes(): IrTreeNode[];
-    isRawPath(pathKey: string): boolean;
-    /** Dirty pathKeys since the last drain — the flush/notify unit. */
-    drainDirty(): string[];
-    hasDirty(): boolean;
-    private upsertNode;
-    /**
-     * Substitute kind-node children with their current tree values so sibling
-     * identities are stable; deep-copy everything else so no live parser
-     * reference ever escapes.
-     */
-    private stabilizeValue;
-    /**
-     * COW spine rebuild: replace the child's slot in each ancestor kind-node's
-     * value, shallow-copying only the containers along the way. Siblings keep
-     * identity; every ancestor gets a new value identity + version bump.
-     */
-    private propagateToAncestors;
-    private findNearestAncestorNode;
-    private cloneAlong;
-    private markRaw;
-    /**
-     * A rescue means a degrade tried to erase data a user could already see —
-     * an upstream defect. It rides the envelope as a notice so it surfaces in the
-     * Error Inspector instead of being silently absorbed (`core/` is a pure
-     * kernel: no console, no capture — the notice IS the alarm).
-     */
-    private recordRescue;
-    /**
-     * Assemble the canonical envelope. ONE code path for stream + one-shot.
-     * Callers supply the fingerprint (one-shot hashes the source; live sessions
-     * keep an incremental hasher so no per-flush re-hash happens).
-     */
-    buildEnvelope(fingerprint: string): CanonicalBlockIR;
-}
-
-/**
- * Character-level incremental JSON tokenizer. Survives chunk boundaries
- * mid-token (strings, escapes, unicode sequences, primitives). Pure — no
- * React, no Redux, no IO.
- *
- * Moved from app/(dev)/demos/json-block-detector/reusable-logic.ts (the demo
- * is now a consumer of this library).
- */
-type Punct = "{" | "}" | "[" | "]" | ":" | ",";
-type JsonToken = {
-    type: "punct";
-    value: Punct;
-    at: number;
-} | {
-    type: "string";
-    value: string;
-    at: number;
-} | {
-    type: "number";
-    value: number;
-    at: number;
-} | {
-    type: "boolean";
-    value: boolean;
-    at: number;
-} | {
-    type: "null";
-    value: null;
-    at: number;
-};
-declare class JsonStreamTokenizer {
-    private mode;
-    private pos;
-    private stringBuffer;
-    private primitiveBuffer;
-    private unicodeBuffer;
-    private tokenStart;
-    private readonly onToken;
-    constructor(onToken: (token: JsonToken) => void);
-    get position(): number;
-    push(chunk: string): void;
-    end(): void;
-    private handleNormalChar;
-    private emitPrimitive;
-    private isDelimiter;
-}
-
-/**
- * Compliant snapshot builder — the guarantee that a renderer always receives
- * a well-formed, schema-shaped object even mid-stream.
- *
- * ZERO DATA LOSS: unknown keys are NOT merged into the snapshot value (they
- * would be indistinguishable from schema fields). They are returned on the
- * residue channel and re-merged only at wire-serialization time via
- * `mergeResidueIntoValue`.
- */
-
-/** Placeholder for a required field not yet received during streaming. */
-declare function emptyValueForFieldSchema(field: FieldSchema): unknown;
-interface CompliantKindSnapshot {
-    /** Schema fields + __kind only. Required-but-missing fields hold typed placeholders. */
-    value: Record<string, unknown>;
-    /** Unknown keys + missing optionals. Null when both channels are empty. */
-    residue: IrResidue | null;
-}
-declare function buildCompliantKindSnapshot(schema: KindSchema, partial: Record<string, unknown>): CompliantKindSnapshot;
-/**
- * Wire/round-trip form: schema fields + unknown keys back together, exactly
- * as the source carried them. `residue.extra` wins nothing — snapshot value
- * and extras are disjoint by construction.
- */
-declare function mergeResidueIntoValue(value: Record<string, unknown>, residue: IrResidue | null): Record<string, unknown>;
-
-/**
- * Idempotent normalizer — the "recognizes its own work" property.
- *
- * THE LAW: anything already carrying a current CanonicalBlockIR envelope is
- * returned BY REFERENCE — zero reprocessing, reference equality holds, React
- * bails out. Only raw text (a detected region's source) is ever parsed, and
- * it is parsed exactly once per fingerprint.
- *
- * `normalizeJsonRegion` is the one-shot mode: the same KindStreamParser that
- * powers live streams, run over a complete region string (DB reloads,
- * reconcile passes), assembled through the same IrTree the live session uses
- * — stream and static output are structurally identical by construction.
- */
-
-declare function isCanonicalBlockIR(value: unknown): value is CanonicalBlockIR;
-/**
- * The idempotence fast path: return the existing envelope by reference when
- * it still describes this source text; null means "parse needed".
- */
-declare function reuseEnvelopeIfCurrent(source: string, candidate: unknown): CanonicalBlockIR | null;
-interface NormalizeJsonRegionOptions {
-    schemas: Record<string, KindSchema> | SchemaResolver;
-    /** Known-context root prediction (agent output schema, fence hint). */
-    expectedRootKind?: string;
-    /**
-     * Pass a previously persisted envelope (message metadata, artifact row);
-     * when its fingerprint matches, it is returned as-is and nothing parses.
-     */
-    existing?: unknown;
-}
-interface CompleteValueEnvelopeOptions {
-    /**
-     * Wire discriminator recorded on the root node — which syntax established
-     * the kind. Defaults to the JSON `__kind` key; XML surfaces converging at
-     * region finalize pass `xmlDiscriminator(tag)` so round-trip serializers
-     * know the original arrival format.
-     */
-    discriminator?: IrDiscriminator;
-}
-/**
- * Build a resolved, complete envelope directly from an already-structured
- * value (a persisted artifact's `content.data` object, or a completed XML
- * region's strategy output). This is the zero-reprocessing rehydration path:
- * the value IS the reconstructed region value (schema fields + residue extras
- * merged at persist time), so no tokenizer/parser run is needed — the
- * envelope wraps it verbatim. The fingerprint hashes the canonical value
- * serialization, so any two paths producing the same value produce the SAME
- * envelope (stream ≡ static by construction).
- */
-declare function envelopeFromCompleteValue(value: Record<string, unknown>, kind: string, options?: CompleteValueEnvelopeOptions): CanonicalBlockIR;
-/** One-shot: complete region text in → canonical envelope out. */
-declare function normalizeJsonRegion(source: string, options: NormalizeJsonRegionOptions): CanonicalBlockIR;
-
-/**
- * Stable, fast content fingerprint for IR envelopes.
- *
- * Used as the idempotence / cache key: a persisted CanonicalBlockIR is only
- * reused when its fingerprint matches the region source text it claims to
- * represent. Not cryptographic — collision resistance at the "same message,
- * same block" scale is all that's required, and it must be synchronous and
- * dependency-free (runs per region on the hot streaming path).
- *
- * FNV-1a 32-bit, applied twice with different seeds and concatenated, so a
- * single 32-bit collision doesn't alias two regions.
- *
- * `createFingerprinter` is the incremental form for live streams: feeding
- * chunks one at a time yields EXACTLY the same fingerprint as
- * `fingerprintText` over the concatenation — sessions never re-hash the
- * whole source per flush.
- */
-interface Fingerprinter {
-    push(chunk: string): void;
-    /** Fingerprint of everything pushed so far. */
-    current(): string;
-}
-declare function createFingerprinter(): Fingerprinter;
-declare function fingerprintText(source: string): string;
-
-/**
- * Discriminator abstraction — how a node's kind is established from the wire.
- *
- * The parser never hardcodes "kind comes from a JSON key". JSON resolves via
- * the `__kind` field (implemented today); XML resolves via tag → registry
- * alias (Phase 6 — contract only). `IrStructuredNode.discriminator` records
- * which resolver produced each node so renderers and round-trip serializers
- * can reconstruct the original wire format per node.
- */
-
-declare const JSON_DISCRIMINATOR: IrDiscriminator;
-declare function xmlDiscriminator(tag: string): IrDiscriminator;
-declare function fenceDiscriminator(language: string): IrDiscriminator;
-/** What a resolver can say about an opening compound value. */
-type KindResolution = {
-    outcome: "kind";
-    kind: string;
-} | {
-    outcome: "pending";
-} | {
-    outcome: "raw";
-    reason: string;
-};
-
-/**
- * IrEnvelopeCache — the persisted envelope cache carried on MESSAGE PARTS.
- *
- * Phase 5 (reload without re-parse): at stream end, `assembleMessageParts`
- * stamps every completed JSON region's CanonicalBlockIR onto the committed
- * `CxTextContent.metadata.__ir` as this cache — keyed by fingerprint, because
- * one text part can embed several regions. On reload the splitter's envelope
- * memo consults the seeded cache (`registry/region-envelope-memo.ts`) and
- * reuses the persisted envelope BY REFERENCE via `reuseEnvelopeIfCurrent`
- * (exact fingerprint match of the detected region source) — zero re-parse.
- *
- * Shape discipline: the SAME `__ir` metadata key carries two shapes at two
- * levels, disambiguated by validators that reject each other —
- *   - render block metadata → a single CanonicalBlockIR (`isCanonicalBlockIR`)
- *   - message part metadata → this cache (`isIrEnvelopeCache`)
- *
- * Pure kernel module: types + validators only. No React/Redux/Supabase.
- */
-
-/** Cache version. Bump = migration point for persisted part caches. */
-declare const IR_ENVELOPE_CACHE_VERSION: 1;
-/**
- * The envelope cache persisted on a message part's `metadata.__ir`.
- * `blocks` maps each region-source fingerprint to its complete envelope.
- */
-interface IrEnvelopeCache {
-    v: typeof IR_ENVELOPE_CACHE_VERSION;
-    blocks: Record<string, CanonicalBlockIR>;
-}
-/**
- * Strict whole-cache validation: every entry must be a complete
- * CanonicalBlockIR keyed by its OWN fingerprint. A cache failing this guard
- * came from a buggy or foreign writer — callers surface that loudly and seed
- * nothing (a half-trusted cache is how poisoned envelopes reach renderers).
- */
-declare function isIrEnvelopeCache(value: unknown): value is IrEnvelopeCache;
-/**
- * Build the persistable cache from a run's collected envelopes. Only
- * complete envelopes are cacheable (a streaming/error envelope can never be
- * reused — its fingerprint doesn't describe a finished region). Duplicate
- * regions (same fingerprint) collapse to one entry. Engine-agnostic by
- * design: an aidream-built `engine: "py-block-detector"` envelope is cached
- * identically to an FE-parsed one. Returns null when nothing qualifies so
- * callers skip the metadata stamp entirely.
- */
-declare function envelopeCacheFromEnvelopes(envelopes: readonly CanonicalBlockIR[]): IrEnvelopeCache | null;
-
-/**
- * PURE envelope ingestion — reading `metadata.__ir` off a block's metadata
- * and gating SERVER-BUILT envelopes at the wire boundary. Twin-safe: no
- * React / Redux / Supabase / host diagnostics — side effects (seeding the
- * region-envelope memo, screaming to the Error Inspector) are injected by
- * the host through `InboundEnvelopeHooks`.
- *
- * The frontend host shell is `redux/render-block-envelope.ts` (binds the
- * hooks to `seedEnvelope` + `captureError`); aidream's Workflow Studio binds
- * its own. Contract: /Users/armanisadeghi/code/common-docs/systems/content-ir-system/PYTHON_ENVELOPE_CONTRACT.md.
- */
-
-/** Read a CanonicalBlockIR envelope off a block's metadata (or anything). */
-declare function readEnvelope(metadata: Record<string, unknown> | null | undefined): CanonicalBlockIR | null;
-/** Pure classification of inbound metadata carrying (or not) an envelope. */
-type InboundEnvelopeVerdict = {
-    /** No `__ir` key — zero-touch pass, same reference back. */
-    outcome: "absent";
-    metadata: Record<string, unknown> | undefined;
-} | {
-    /** Valid CanonicalBlockIR — same reference back (idempotence law). */
-    outcome: "valid";
-    metadata: Record<string, unknown>;
-    envelope: CanonicalBlockIR;
-} | {
-    /** Malformed/foreign `__ir` — a COPY with `__ir` stripped. */
-    outcome: "malformed";
-    metadata: Record<string, unknown>;
-    engine: string;
-    raw: unknown;
-};
-declare function classifyInboundEnvelopeMetadata(metadata: Record<string, unknown> | null | undefined): InboundEnvelopeVerdict;
-/** Host-injected side effects for the inbound gate. */
-interface InboundEnvelopeHooks {
-    /** Called with every VALID envelope so later re-splits reuse it by reference. */
-    seedEnvelope?: (envelope: CanonicalBlockIR) => void;
-    /** Called LOUDLY for every malformed envelope — a bad envelope is a defect. */
-    reportMalformed?: (info: {
-        blockId: string;
-        engine: string;
-        raw: unknown;
-    }) => void;
-}
-/**
- * Ingest guard for SERVER-BUILT envelopes riding `metadata.__ir` on a
- * `render_block` event.
- *
- * - No `__ir` key → the SAME metadata reference back (zero-touch pass).
- * - Valid CanonicalBlockIR → the SAME metadata reference back (reuse-by-
- *   reference — the idempotence law) AND `hooks.seedEnvelope` fires so any
- *   later re-split of the same region source reuses it instead of parsing.
- * - Malformed/foreign `__ir` → a COPY with `__ir` stripped, plus a loud
- *   `hooks.reportMalformed`. A bad envelope must never poison kind routing
- *   or the persistence cache; dropping it degrades that block to the
- *   ordinary content-driven path, nothing more.
- */
-declare function sanitizeInboundEnvelopeMetadata(metadata: Record<string, unknown> | null | undefined, context: {
-    blockId: string;
-}, hooks?: InboundEnvelopeHooks): Record<string, unknown> | undefined;
-
-/**
- * Pure envelope→value functions (the zero-data-loss wire round-trip).
- *
- * These live in core/ (the pure kernel) because every layer needs them —
- * including kinds/legacy-bridge-utils, whose bridges are built at MODULE
- * SCOPE inside kinds/<slug>.ts files that system-kinds.ts imports. When these
- * functions lived in redux/render-block-envelope.ts, that file's memo/capture
- * imports closed a module cycle (kinds → bridge-utils → render-block-envelope
- * → region-envelope-memo → kind-registry → system-kinds → kinds), which made
- * SYSTEM_KIND_DEFINITIONS entry-point-fragile (undefined defs when a kinds
- * module was the import entry). Keeping them here makes every kinds module
- * cycle-free BY CONSTRUCTION. redux/render-block-envelope re-exports them for
- * its existing consumers.
- */
-
-/**
- * Rebuild the region's full data: walk the root value and merge each node's
- * residue extras back in (root residue + nodeIndex residues). This is the
- * zero-data-loss read: nothing the model emitted is missing, whether or not
- * a schema knew about it.
- */
-declare function reconstructRegionValue(envelope: CanonicalBlockIR): Record<string, unknown>;
-/**
- * Deep-remove the `__kind` discriminator.
- *
- * 🚨 NOT A TRANSFORM FOR PLATFORM DATA. `__kind` is part of the data
- * (KINDS_EVERYWHERE_PLAN §4.2) and stripping it from anything stored, passed or
- * rendered was annihilated on 2026-08-23. This helper survives for exactly two
- * shapes of caller, both of which are guarded:
- *   - a SYMMETRIC COMPARISON that reduces both sides and returns a boolean;
- *   - legacy validation TOLERANCE against a pre-2026-08-23 schema version.
- * Guards: aidream `scripts/check_kind_marker_law.py`,
- * matrx-frontend `pnpm check:kind-marker-law`.
- */
-declare function stripKindDeep(value: unknown): unknown;
-
-/**
- * ContentRegion — the handshake between a host detector and this library.
- *
- * Boundary rule (the answer to the single-root problem): the HOST detector
- * (StreamBlockAccumulator on streams, content-splitter-v2 on DB loads) finds
- * where a structured region begins and ends inside prose; the kind parser
- * owns everything INSIDE the region. A fresh parser is created per region, so
- * "one root object" is true within a region by construction, and multiple
- * blocks per message are just multiple regions.
- *
- * Through Phase 6 the host's fence-close / brace-count logic remains the
- * region-end oracle (bit-level parity with today). In Phase 7 the parser's
- * own frame stack becomes the oracle and the mirrored counters are deleted.
- */
-type RegionFormat = "json";
-type RegionSourceKind = "fence" | "bare";
-interface ContentRegionInit {
-    regionId: string;
-    format: RegionFormat;
-    sourceKind: RegionSourceKind;
-}
-/** How a region ended. Truncation is a normal outcome, never stream-fatal. */
-type RegionEndReason = "closed" | "truncated" | "aborted";
-
-/**
- * Schema-shape helpers — structural depth and layout hints derived from a
- * KindSchema. Drives the generic renderer's flat / grid / nested layout and
- * human labels for slugs.
- *
- * Moved from app/(dev)/demos/json-block-detector/schema-structure.ts.
- */
-
-/** Human label from a slug or field key (snake_case → Title Case + acronym fixes). */
-declare function formatBlockLabel(key: string): string;
-/**
- * Structural nesting depth of a kind schema — drives generic renderer layout.
- * 0 = flat card (scalars only)
- * 1 = grid (one array/object nesting level)
- * 2+ = expandable grid (parent → child → grandchild)
- */
-declare function schemaStructureDepth(schema: KindSchema, allSchemas: Record<string, KindSchema>, visiting?: Set<string>): number;
-type SchemaLayoutMode = "flat" | "grid" | "nested";
-declare function schemaLayoutMode(schema: KindSchema, allSchemas: Record<string, KindSchema>): SchemaLayoutMode;
-
-/**
- * ParseSession — one live region parse per stream identity.
- *
- * Owns the parser + IrTree OUTSIDE React and Redux. Writers push chunks;
- * N readers subscribe per path (useIrNode / selectors) and are notified on
- * the host's flush cadence — never per token.
- *
- * Notification contract: `write()`/`end()` never notify. The host (demo rAF
- * loop, process-stream's dispatchBatch tick) calls `flushNotify()` to publish
- * dirty paths. Late schema arrivals (registry cold fetch) notify themselves —
- * they happen outside any streaming tick.
- */
-
-interface ParseSessionOptions {
-    identity: string;
-    schemas: Record<string, KindSchema> | SchemaResolver;
-    expectedRootKind?: string;
-    /**
-     * Registry hook: subscribe to cold-fetch answers, return an unsubscribe.
-     * The session forwards arrivals into the parser (upgrade-in-place) and
-     * notifies affected readers immediately.
-     */
-    onSchemaArrived?: (deliver: (kind: string, schema: KindSchema | null) => void) => () => void;
-    /** Observe every parser event (demo inspector, telemetry). */
-    onEvent?: (event: KindStreamEvent) => void;
-}
-type Listener = () => void;
-declare class ParseSession {
-    readonly identity: string;
-    private readonly parser;
-    private readonly tree;
-    private readonly listeners;
-    private readonly anyListeners;
-    private readonly unsubscribeSchemaArrivals;
-    private readonly fingerprinter;
-    private ended;
-    constructor(options: ParseSessionOptions);
-    /** The single writer's input. Does NOT notify — host flushes on its cadence. */
-    write(chunk: string): void;
-    end(): void;
-    get isEnded(): boolean;
-    get status(): "streaming" | "complete" | "error";
-    getNode(pathKey: string): IrTreeNode | null;
-    listNodes(): IrTreeNode[];
-    isRawPath(pathKey: string): boolean;
-    subscribe(pathKey: string, listener: Listener): () => void;
-    /** Structural subscription: fires when ANY node changes (mount lists). */
-    subscribeAny(listener: Listener): () => void;
-    /** Publish dirty paths to their readers. Host-cadence, coalesced. */
-    flushNotify(): void;
-    buildEnvelope(): CanonicalBlockIR;
-    dispose(): void;
-}
-
-/**
- * Session manager — one writer per stream identity, N readers, mechanically
- * enforced: a second `openParseSession` for a live identity THROWS. Readers
- * resolve sessions by identity and never gain write access.
- *
- * Identities: `"{requestId}:{blockId}"` for agent-stream regions; any unique
- * string for other hosts (demo runs, notes, one-shot upgrades).
- *
- * Ended sessions stay resolvable for late readers (reload happens via the
- * persisted envelope, but in-session remounts read here) until disposed.
- */
-
-declare function openParseSession(options: ParseSessionOptions): ParseSession;
-declare function getParseSession(identity: string): ParseSession | null;
-declare function disposeParseSession(identity: string): void;
-
-/**
- * KindDefinition — one kind, many facets. THE canonical registry entry.
- *
- * This does NOT merge BlockComponentRegistry or artifact-type-registry; the
- * `legacyBlockType` and `artifact` facets are FACADES pointing into them, so
- * migration is incremental and each registry keeps its own job.
- */
-
-/**
- * The uniform props contract for kind-driven block components. This is what
- * de-special-cases flashcards: no component receives bespoke glue — every
- * kind component gets exactly this shape.
- */
-interface KindBlockProps {
-    kind: string;
-    schema: KindSchema;
-    /** Compliant snapshot value (schema fields + __kind). */
-    data: Record<string, unknown>;
-    status: "streaming" | "complete" | "error";
-    residue: IrResidue | null;
-    path: IrPath;
-    /** ParseSession identity for live child subscriptions; null after reload. */
-    identity: string | null;
-    /** Child-kind schema lookup (replaces passing allSchemas around). */
-    resolve: (kind: string) => KindSchema | undefined;
-}
-type KindTier = "eager" | "warm" | "cold";
-interface KindDefinition {
-    /** Canonical slug — THE key. */
-    kind: string;
-    /** null until the warm/cold fetch delivers it. */
-    schema: KindSchema | null;
-    schemaSource: "system" | "flexible_data" | "content_ir";
-    tier: KindTier;
-    /** Component facet — lazy-loaded renderer for this kind. */
-    component?: {
-        load: () => Promise<{
-            default: ComponentType<KindBlockProps>;
-        }>;
-    };
-    /** Facade → BlockComponentRegistry type string (e.g. "flashcards"). */
-    legacyBlockType?: string;
-    /**
-     * Legacy-bridge facet: derive the existing component's `serverData` from a
-     * canonical envelope. This is what lets a kind light up the REAL component
-     * (FlashcardsBlock, …) with zero component changes during migration.
-     */
-    toLegacyServerData?: (envelope: CanonicalBlockIR) => Record<string, unknown> | undefined;
-    /** Facade → artifact-type-registry canvasType. */
-    artifact?: {
-        canvasType: string;
-    };
-    /**
-     * Markdown export facet — the FORWARD leg of artifact ⇄ markdown. Receives
-     * the ZERO-LOSS reconstructed value object (the CALLER reconstructs — for
-     * persisted structured artifacts `content.data` already IS that object;
-     * this facet only renders it; `__kind` discriminators may still be
-     * present and must be ignored). MUST produce human-readable markdown
-     * (headings / lists / bold), never a JSON dump — a fenced json body under
-     * a heading is acceptable only for inherently-code payloads (e.g. a
-     * schema_proposal's JSON Schema). Unknown extra keys the renderer doesn't
-     * understand MUST be appended under a small "Additional details"
-     * (key: value) section so nothing silently vanishes. Kinds without this
-     * facet fall back to `genericKindMarkdown` (kinds/kind-markdown-utils.ts).
-     */
-    toMarkdown?: (value: Record<string, unknown>) => string;
-    persistence?: {
-        persistStructured: boolean;
-    };
-    /** Future XML tags / kind aliases resolving to this kind. */
-    discriminatorAliases?: string[];
-    /**
-     * PARTIAL-READY opt-in — the streaming partial-kinds posture.
-     *
-     * While a structured region streams, the server may announce a PROVISIONAL
-     * instance of this kind on `metadata.__ir_partial` (valid, closed JSON that
-     * may be missing required fields). The default posture is WITHHOLD: a
-     * provisional value is never routed to a component, and the block keeps its
-     * loading skeleton until the region completes — because a component that
-     * throws on an absent field must not be handed one.
-     *
-     * Setting this to `true` declares "this kind's component renders a partial
-     * value without throwing", and the provisional value is routed to the SAME
-     * component that renders the final one, filling in as tokens arrive. A kind
-     * with a `toLegacyServerData` bridge must ALSO pass `{ provisional: true }`
-     * to `makeCompleteEnvelopeBridge` (pinned by a test). A component that
-     * throws anyway is caught, screams, and permanently drops this kind back to
-     * withhold for the session.
-     *
-     * Contract: common-docs/systems/content-ir-system/STREAMING_PARTIAL_KINDS.md
-     */
-    partialReady?: boolean;
-    /**
-     * Loading-library slug (`kind_definition.metadata.loading_component`) —
-     * which of the ~20 hardcoded loading components renders while this kind's
-     * instance streams in / its schema+component fetch is in flight. Null or
-     * unknown slugs fall back to the generic structured skeleton.
-     */
-    loadingComponent?: string | null;
-}
-
-/**
- * Kind ↔ content_ir storage shape — the pure, DB-free reshaping between the
- * consumed `KindSchema` and the `content_ir.kind_definition.data` array +
- * `content_ir.kind_edge` rows.
- *
- * Two exact inverses:
- *   - `kindSchemaToStorage`  — the MIGRATION / write direction: a parsed
- *     `KindSchema` (fields Record, targets inline) → an ORDERED `data` array
- *     (targets stripped) + externalized `kind_edge` specs (targets, keyed by
- *     field PATH). This is what pours `flexible_data` (and future authored
- *     kinds) into the canonical tables.
- *   - `storageToKindSchema`  — the ADAPTER / read direction: `data` array +
- *     edges → the same `KindSchema` the parser/emitter consume, re-attaching
- *     `object.kind` / `array.itemKinds` from the edges by path.
- *
- * Design invariants (from the 2026-07-05 kind-registry storage design, since deleted):
- *   - The `data` element is `FieldSchema` + `name`, MINUS ref targets. Order is
- *     intrinsic to the array (fixes the jsonb key-reorder bug).
- *   - `kind_edge` is the SINGLE source of truth for kind→kind refs: `object`
- *     → one edge (position null); `array` → N edges (union) ordered by
- *     `position`. `field_name` is a dot-PATH so a ref nested inside an
- *     `inline_object` still gets a distinct, collision-free edge.
- *   - `inline_object` is structural: its `fields` is an ordered array, it never
- *     becomes a registry row and never carries `__kind`. Its nested refs DO get
- *     edges (path-prefixed) so cascade/pinning see every dependency. Its
- *     `open` flag persists on the element (losing it is the open-empty-object
- *     defect).
- *   - `union.kinds` refs externalize to edges exactly like `array.itemKinds`;
- *     the stored element keeps `hasKinds: true` so lost edges scream on read.
- *   - A NON-OBJECT ROOT (`KindSchema.root`) stores as ONE reserved element
- *     named `ROOT_STORAGE_NAME` ("__root") — the only element allowed in that
- *     kind's `data`. Real fields may never use the reserved name.
- *
- * NO imports of supabase / the DB — this is pure and unit-tested by round-trip
- * (`__tests__/kind-storage-transform.test.ts`).
- */
-
-/**
- * Reserved `data[]` element name for a NON-OBJECT ROOT form (`KindSchema.root`).
- * A root-form kind stores exactly one element under this name; the read
- * direction reconstructs `{ root }` instead of a field map. The write
- * direction rejects any REAL field with this name — the name is the marker.
- */
-declare const ROOT_STORAGE_NAME = "__root";
-type StoredFieldBase = {
-    name: string;
-    required?: boolean;
-    nullable?: boolean;
-    /** Human guidance — mirrors FieldBase.description. */
-    description?: string;
-    /** Default VALUE (annotation-level) — mirrors FieldBase.default. */
-    default?: unknown;
-};
-/** One element of `kind_definition.data` — FieldSchema + name, ref targets removed. */
-type StoredFieldElement = (StoredFieldBase & {
-    type: "string" | "boolean";
-}) | (StoredFieldBase & {
-    type: "number";
-    min?: number;
-    max?: number;
-    step?: number;
-}) | (StoredFieldBase & {
-    type: "string[]";
-    values?: string[];
-    open?: boolean;
-}) | (StoredFieldBase & {
-    type: "number[]" | "boolean[]";
-}) | (StoredFieldBase & {
-    type: "json";
-}) | (StoredFieldBase & {
-    type: "json[]";
-}) | (StoredFieldBase & {
-    type: "array";
-}) | (StoredFieldBase & {
-    type: "object";
-}) | (StoredFieldBase & {
-    type: "inline_object";
-    fields: StoredFieldElement[];
-    open?: boolean;
-}) | (StoredFieldBase & {
-    type: "record";
-    values: RecordValueType;
-}) | (StoredFieldBase & {
-    type: "enum";
-    values: string[];
-    open?: boolean;
-}) | (StoredFieldBase & {
-    type: "union";
-    scalars: Array<"string" | "number" | "boolean">;
-    /** Marker that this union's kind refs live in edges (positions ordered). */
-    hasKinds?: boolean;
-});
-/** One `content_ir.kind_edge` row (child resolved to an id at insert time). */
-type KindEdgeSpec = {
-    /** Field PATH in the parent's `data` (dot-notation into inline_objects). */
-    fieldPath: string;
-    /** Child kind slug — insert resolves this to `child_definition_id`. */
-    childKind: string;
-    /** Union (anyOf) ordering for array refs; null for a single object ref. */
-    position: number | null;
-};
-/** The full write payload for one kind: the ordered data array + its edges. */
-type KindStorageShape = {
-    data: StoredFieldElement[];
-    edges: KindEdgeSpec[];
-};
-declare class KindStorageError extends Error {
-    constructor(message: string);
-}
-/**
- * MIGRATION / write direction. Order of `data` follows `Object.entries(fields)`
- * — the caller supplies the KindSchema whose field order is authoritative
- * (prefer the compiled `system-kinds.ts` order for system kinds during the
- * one-time flexible_data migration; jsonb order is the fallback for user kinds).
- */
-declare function kindSchemaToStorage(schema: KindSchema): KindStorageShape;
-/** ADAPTER / read direction — the exact inverse of `kindSchemaToStorage`. */
-declare function storageToKindSchema(kind: string, shape: KindStorageShape): KindSchema;
-
-/**
- * The dual gate — Arman's law as executable code: a kind is only `is_active`
- * when its canonical `sample_data` passes BOTH systems.
- *
- *   1. Structural (Pydantic): the sample validates against the kind's
- *      `emitted_json_schema`. Python's Pydantic is the AUTHORITATIVE owner of
- *      this leg, but it reads the SAME materialized `emitted_json_schema` — so
- *      this TS ajv check and the Python check validate the same sample against
- *      the same schema and agree by construction. A disagreement IS the
- *      screamer (a schema Pydantic can't express, or an ajv/Pydantic gap).
- *   2. Render (UI): the sample lights up the kind's real component. TS is the
- *      AUTHORITATIVE owner of this leg. It is a PROXY for a DOM render, not a
- *      DOM render. Exactly what it checks, and nothing more:
- *        · the kind has something to render with (`legacyBlockType` or
- *          `component`);
- *        · for BRIDGED kinds, `toLegacyServerData(sample)` returns a plain
- *          object that is SEMANTICALLY non-empty — see
- *          `describeUnrenderableBridgeOutput` for the exact predicate;
- *        · BRIDGELESS kinds pass with a recorded caveat — nothing is verified.
- *
- *      This catches the 2026-07-04 "No flashcards available yet" class: a
- *      bridge that returns `undefined`, `{}`, `{language:"json"}` (the raw
- *      code-region annotation), or an object whose every value is empty.
- *
- *      What it does NOT do — stated plainly, because a gate that overclaims is
- *      worse than no gate: it does not mount the component, and it cannot know
- *      WHICH key carries the payload. `{title:"Cell Biology", cards:[]}` passes
- *      this leg on `title` alone. Proving the payload key is populated needs
- *      per-kind knowledge the gate deliberately does not have; a DOM-level
- *      render check is the deeper leg, deferred to an RTL harness.
- *
- * Both legs necessary, neither sufficient. Fail either → `isActive: false` and
- * the caller reports it loudly (Error Inspector, `content-ir`) and holds the
- * row out of production. This module is PURE (deps injected) so it runs in the
- * harness, in CI, and in a browser author-save alike.
- *
- * Ownership split (the 2026-07-05 kind-registry storage design, since deleted; the live contract is the code below): the caller writes the outcome
- * to the LIVE `content_ir.kind_definition` row's `is_active`; the canonical
- * `_version_capture` trigger snapshots that state into `history.row_versions`
- * (never a post-hoc history mutation).
- */
-
-/** The facets the render leg needs — a structural subset of KindDefinition. */
-interface DualGateDefinition {
-    legacyBlockType?: string;
-    toLegacyServerData?: (envelope: CanonicalBlockIR) => Record<string, unknown> | undefined;
-    component?: {
-        load: () => Promise<unknown>;
-    };
-}
-/**
- * The render leg's second satisfier: an ACTIVE `role='output'` component
- * resolved from `content_ir.kind_component`. Feed this from
- * `resolveComponent(kind, "web", "output")`.
- *
- * Why this exists: the render leg originally consulted only the compiled TS
- * registry, so an agent-authored kind whose renderer is a `source='db'` row was
- * structurally unable to pass — `definition` came back null and the gate said
- * "no component" about a kind that had a live, working one. Six authored kinds
- * (wine_tasting, employee_card, employee_roster, employee_of_the_week,
- * flashcard_deck, arman_video_prompt) sat permanently inactive because of it.
- *
- * NOT a mirror of `content_ir.evaluate_kind_activation`. The SQL render leg is
- * presence-only — it checks that an active `role='output'` row exists, because
- * SQL cannot execute a TypeScript bridge. THIS leg is strictly stronger: for a
- * compiled kind it also runs `toLegacyServerData` and rejects semantically
- * empty output (the "No <kind> available" class).
- *
- * The asymmetry is deliberate and bounded: SQL is the FLOOR (necessary, and
- * sufficient for DB-authored components, which own no bridge), while this leg
- * is the CEILING for compiled kinds. Consequence to know: activating a COMPILED
- * kind whose bridge is broken would pass the RPC and fail here. Compiled kinds
- * are activated by developers through `scripts/shape/activate-kinds.ts`, which
- * runs this leg — the studio control only ever reaches owner-authored kinds.
- * If that ever stops being true, the browser control must run this gate before
- * enabling its button.
- */
-interface DualGateResolvedComponent {
-    componentKey: string;
-    /** The row's own render-trust verdict (R6). Inactive rows do not satisfy. */
-    isActive: boolean;
-    /** "bundled" | "db" — reported in the leg detail, never gates the verdict. */
-    source: string;
-}
-interface DualGateInput {
-    kind: string;
-    /** The canonical instance (kind_definition.sample_data). */
-    sample: Record<string, unknown>;
-    /** The materialized kind_definition.emitted_json_schema (plain, no __kind). */
-    emittedJsonSchema: unknown;
-    /** The registry definition for the kind (or null when unregistered). */
-    definition: DualGateDefinition | null;
-    /**
-     * The resolver's `(kind, web, output)` answer, when the caller has one.
-     * Omit (or pass null) to check the compiled registry alone.
-     */
-    resolvedComponent?: DualGateResolvedComponent | null;
-    /**
-     * True when the kind is a generated data-only contract
-     * (`metadata.family` ∈ workflow_io | tool_io | action_io | agent_io).
-     * Those are passed between nodes and never rendered, so the render leg is
-     * structurally inapplicable — the same `n/a` doctrine the shape doctor uses.
-     * Failing them would be noise, and noise erodes the gate.
-     */
-    dataOnly?: boolean;
-}
-interface LegResult {
-    ok: boolean;
-    detail?: string;
-}
-interface DualGateResult {
-    /** True only when BOTH legs pass — the value the caller writes to is_active. */
-    isActive: boolean;
-    structural: LegResult;
-    render: LegResult;
-}
-/**
- * The structural leg, exported on its own so the shape doctor
- * (`shape-doctor.ts`) RECOMPUTES gate validation with the exact same ajv
- * config + marker semantics as activation (verbatim first, marker-free retry
- * second) — never a parallel validator. `sample` is `unknown` (not `Record`) because kind examples may
- * legitimately be scalars/arrays (workflow I/O kinds like `text`/`number`).
- */
-declare function validateStructuralLeg(sample: unknown, emittedJsonSchema: unknown): LegResult;
-declare function runKindDualGate(input: DualGateInput): DualGateResult;
-/**
- * One-line, Error-Inspector-ready reason for a failed gate (empty string when
- * it passed). The caller feeds this to `captureError({ source: "content-ir" })`
- * and sets `is_active=false`.
- */
-declare function describeDualGateFailure(kind: string, result: DualGateResult): string;
-
-/**
- * OpenAI/provider JSON Schema → KindSchema converter + __kind injection.
- *
- * The strategic keystone: `buildAgentSchemaWithRenderBlockSupport` turns "a
- * user/agent defined an output schema" into "the platform has a render
- * contract for it" by injecting the `__kind` discriminator into the agent's
- * output schema (root + array items), so the model emits self-identifying
- * objects from then on.
- *
- * Moved from app/(dev)/demos/json-block-detector/schema-converter.ts.
- */
-
-type JsonSchemaNode = Record<string, unknown>;
-type ConversionProblem = {
-    severity: "error" | "warning" | "info";
-    path: string;
-    message: string;
-};
-type DroppedMetadata = {
-    path: string;
-    dropped: Record<string, unknown>;
-};
-type FieldComparison = {
-    field: string;
-    aiPresent: boolean;
-    blockPresent: boolean;
-    aiSummary: string | null;
-    blockSummary: string | null;
-    status: "match" | "ai_only" | "block_only" | "type_mismatch" | "ai_richer" | "block_richer";
-    detail?: string;
-};
-/** One standalone flexible_data block schema row. */
-type BlockSchemaDraft = {
-    slug: string;
-    label: string;
-    fields: Record<string, FieldSchema>;
-    /**
-     * NON-OBJECT ROOT form (KindSchema.root): the kind's value is this field's
-     * shape at the top level (scalar / array / json / OPEN object). When set,
-     * `fields` is empty — mirror of `KindSchema.root`.
-     */
-    root?: FieldSchema;
-};
-type ArrayItemKindBinding = {
-    arrayField: string;
-    itemKindSlug: string;
-};
-type SchemaConversionResult = {
-    schemaName: string | null;
-    strict: boolean | null;
-    /** Every block schema row required for the converted shape (1..n). */
-    blockSchemas: BlockSchemaDraft[];
-    /** OPTION 2 — same input shape with __kind injected for agent output. */
-    agentSchemaWithKinds: unknown | null;
-    problems: ConversionProblem[];
-    droppedMetadata: DroppedMetadata[];
-    comparisons: FieldComparison[];
-};
-type SavePlanEntry = {
-    draft: BlockSchemaDraft;
-    existsInDb: boolean;
-    willSave: boolean;
-};
-type ItemKindRefCheck = {
-    parentSlug: string;
-    field: string;
-    itemKind: string;
-    satisfied: boolean;
-    source: "batch" | "database" | "missing";
-};
-type SavePlanValidation = {
-    entries: SavePlanEntry[];
-    itemKindRefs: ItemKindRefCheck[];
-    newCount: number;
-    canSave: boolean;
-    errors: string[];
-};
-/**
- * Inject the `__kind` discriminator into one object schema (const when
- * strict, enum otherwise; `__kind` prepended to required; strict also pins
- * additionalProperties:false). Shared with the REVERSE converter
- * (kind-to-json-schema.ts) so both directions stamp identical discriminators.
- */
-declare function injectKindIntoObjectSchema(objectSchema: JsonSchemaNode, kindSlug: string, strict: boolean): JsonSchemaNode;
-declare function buildAgentSchemaWithRenderBlockSupport(input: unknown, rootKindSlug: string, arrayBindings: ArrayItemKindBinding[], strict: boolean): unknown | null;
-declare function normalizeAiSchemaInput(input: unknown): {
-    name: string | null;
-    strict: boolean | null;
-    rootSchema: JsonSchemaNode | null;
-    parseErrors: string[];
-};
-type ConversionCore = {
-    schemaName: string | null;
-    strict: boolean | null;
-    blockSchemas: BlockSchemaDraft[];
-    problems: ConversionProblem[];
-    droppedMetadata: DroppedMetadata[];
-};
-declare function convertAiSchemaToBlockFields(schemaName: string, rootSchema: JsonSchemaNode, strict: boolean): ConversionCore;
-declare function compareWithExistingKindSchema(convertedFields: Record<string, FieldSchema>, existing: KindSchema | null): FieldComparison[];
-declare function runSchemaConversion(input: unknown, existingSchemas: Record<string, KindSchema>): SchemaConversionResult & {
-    parseErrors: string[];
-};
-declare function validateBlockSchemaSavePlan(blockSchemas: BlockSchemaDraft[], existingSlugs: string[], hasConversionErrors: boolean): SavePlanValidation;
-declare function fieldsToDbPayload(fields: Record<string, FieldSchema>): Record<string, unknown>;
-declare function isDuplicateBlockSlug(slug: string, entries: Array<{
-    slug: string;
-}>): boolean;
-
-/**
- * KindSchema → provider-ready JSON Schema — the REVERSE of the OpenAI
- * converter in openai-schema-converter.ts.
- *
- * The requested root kind renders INLINE as the top-level object; every
- * OTHER kind it transitively references (via `{type:"object", kind}` and
- * `{type:"array", itemKinds}` fields, including inside inline_objects)
- * becomes a `$defs` entry referenced with `$ref: "#/$defs/<slug>"`.
- * References back to the ROOT kind use `"#"` — the standard JSON Schema
- * recursive-root reference (OpenAI structured outputs support both forms).
- * Collection is cycle-safe: each kind enters the closure exactly once.
- *
- * Round-trip contract — output fed through `runSchemaConversion`
- * (openai-schema-converter.ts) reproduces the source KindSchemas for the
- * root and every array-item child (enforced by
- * __tests__/kind-to-json-schema.test.ts). The 2026-07-15 expressivity
- * extension closed the three historical asymmetries: `record` now has a
- * forward target (properties-less objects → record scalar/json), multi-
- * itemKind arrays read back through items-anyOf when each variant declares
- * its `__kind`, and nullable anyOf preserves the member list + nullable flag
- * instead of flattening to `string`. Remaining accepted narrowings:
- * - multi-kind array items emitted as $refs (not inline __kind objects)
- *   still cannot be read back — the forward converter rejects $ref.
- * - a nullable object-REF (`anyOf: [$ref, {type:"null"}]`) degrades for the
- *   same $ref reason.
- * - JSON Schema `integer` narrows to `number` (the map_result precedent).
- */
-
-type KindJsonSchemaOptions = {
-    /**
-     * Provider strict mode: additionalProperties:false on every kind object
-     * and inline object, and `const` (vs `enum`) __kind discriminators —
-     * mirrors makeKindJsonSchemaProperty / injectKindIntoObjectSchema.
-     */
-    strict?: boolean;
-    /**
-     * Inject the `__kind` discriminator (+ required) into the root and every
-     * $defs kind object. Default true — this is what makes the emitted
-     * objects self-identifying for the render pipeline.
-     */
-    injectKind?: boolean;
-};
-type KindJsonSchemaExport = {
-    /** The root kind slug — doubles as the provider schema name. */
-    name: string;
-    schema: JsonSchemaNode;
-    strict: boolean;
-    /**
-     * Referenced kinds the resolver could not supply. Each still gets a
-     * permissive `$defs` object stub (never additionalProperties:false, even
-     * in strict mode — a __kind-only strict object would reject every real
-     * payload) so the export stays structurally valid. Surface these loudly.
-     */
-    unresolved: string[];
-};
-/**
- * Every kind referenced by a field map — `{type:"object", kind}` refs and
- * `{type:"array", itemKinds}` members, recursing through inline_objects.
- * First-sighting order, deduplicated. Shared read helper (the registry
- * catalog builds its uses / used-by graph from this).
- */
-declare function collectReferencedKinds(fields: Record<string, FieldSchema>): string[];
-/**
- * Schema-level referenced kinds — field-map refs PLUS the refs a non-object
- * root form carries. Use this (not `collectReferencedKinds(schema.fields)`)
- * whenever the schema in hand may be root-form.
- */
-declare function collectSchemaReferencedKinds(schema: KindSchema): string[];
-declare function kindSchemaToJsonSchema(kind: string, resolve: (kind: string) => KindSchema | undefined, options?: KindJsonSchemaOptions): KindJsonSchemaExport | null;
-
-/**
- * JSON Schema → KindSchema — THE registry-facing direction.
- *
- * 🚨 WHY THIS FILE IS THE POINT OF THE WHOLE CONVERT LAYER (Arman's ruling,
- * 2026-08-29): a kind's fields must be DERIVED from its schema, never stored a
- * second time. `content_ir.kind_definition` used to carry both — a JSON Schema
- * AND a flattened field list written beside it — and the two had already
- * diverged on 13 of the 62 live kinds that carried both: stored lists holding
- * `__kind` as if it were a data field, enums flattened to bare strings,
- * min/max bounds and required flags the schema states and the copy never
- * learned. A cache that can disagree with its source is not a cache.
- *
- * The heavy lifting lives in `openai-schema-converter.ts` (it also serves the
- * agent-authoring flow, which needs the problems/dropped-metadata detail).
- * This module is the narrow, honest door the registry calls: one schema in,
- * one `KindSchema` out, plus whatever child kinds the schema declared inline
- * or through `$defs`.
- *
- * Accepts both storage shapes seen in the wild: a bare JSON Schema, and the
- * provider `{name, schema, strict}` response-format envelope that 5 live rows
- * carry.
- */
-
-type KindSchemaFromJsonResult = {
-    /**
-     * The requested kind's schema, or null when the input could not be read as
-     * an object contract at all. NEVER a partial guess: a field the vocabulary
-     * cannot express degrades to `json` (widening, always safe), and only a
-     * structurally unusable root yields null.
-     */
-    schema: KindSchema | null;
-    /**
-     * Child kinds the schema declared inline or via `$defs`, keyed by slug.
-     * A registry that ingests these gets the whole tree from ONE row's schema —
-     * which is how a nested kind renders before its children's rows load.
-     */
-    children: Record<string, KindSchema>;
-    /** Conversion notes. `severity: "error"` entries are worth screaming about. */
-    problems: ConversionProblem[];
-};
-/**
- * Derive `kind`'s field schema from its JSON Schema.
- *
- * Pure and synchronous — no registry, no IO — so a host can call it from a
- * warm load, a cold fetch, a reducer, or a test.
- */
-declare function kindSchemaFromJsonSchema(kind: string, jsonSchema: unknown): KindSchemaFromJsonResult;
-
-/**
- * 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, type KindSchemaFromJsonResult, 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 RawObjectCause, 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, kindSchemaFromJsonSchema, 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 };
+export { C as CanonicalBlockIR, a as CanonicalContent, b as CanonicalSegment, I as IR_ENVELOPE_KEY, c as IR_VERSION, d as IrDiscriminator, e as IrKindState, f as IrPath, g as IrResidue, h as IrStructuredNode, i as irPathIsUnderOrEqual, j as irPathKey, k as irPathLabel, l as irPathsEqual, m as isEmptyResidue } from './ir-types-95bA2cXH.cjs';
+export { I as IrTree, a as IrTreeNode, J as JsonPath, K as KindStreamEvent, b as KindStreamParser, c as KindStreamParserOptions, R as RawObjectCause, S as SchemaResolver, d as createKindStreamParser, s as setJsonRootKeyLookup } from './ir-tree-DbLVxbf1.cjs';
+export { CompleteValueEnvelopeOptions, CompliantKindSnapshot, ContentRegionInit, Fingerprinter, IR_ENVELOPE_CACHE_VERSION, InboundEnvelopeHooks, InboundEnvelopeVerdict, IrEnvelopeCache, JSON_DISCRIMINATOR, JsonStreamTokenizer, JsonToken, KindResolution, NormalizeJsonRegionOptions, Punct, RegionEndReason, RegionFormat, RegionSourceKind, SchemaLayoutMode, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, createFingerprinter, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fingerprintText, formatBlockLabel, isCanonicalBlockIR, isIrEnvelopeCache, mergeResidueIntoValue, normalizeJsonRegion, readEnvelope, reconstructRegionValue, reuseEnvelopeIfCurrent, sanitizeInboundEnvelopeMetadata, schemaLayoutMode, schemaStructureDepth, stripKindDeep, xmlDiscriminator } from './core.cjs';
+export { A as ArrayItemScalarType, F as FieldSchema, K as KIND_KEY, a as KindSchema, R as RecordValueType, S as ScalarFieldType, i as isJsonAnyField, b as isScalarArrayType, r as readObjectKind, s as scalarArrayItemType } from './kind-schema.types-CwncWj9U.cjs';
+export { ParseSession, ParseSessionOptions, disposeParseSession, getParseSession, openParseSession } from './session.cjs';
+export { DualGateDefinition, DualGateInput, DualGateResolvedComponent, DualGateResult, KindBlockProps, KindDefinition, KindEdgeSpec, KindStorageError, KindStorageShape, KindTier, LegResult, ROOT_STORAGE_NAME, StoredFieldElement, describeDualGateFailure, kindSchemaToStorage, runKindDualGate, storageToKindSchema, validateStructuralLeg } from './registry.cjs';
+export { ArrayItemKindBinding, BlockSchemaDraft, ConversionProblem, DroppedMetadata, FieldComparison, ItemKindRefCheck, JsonSchemaNode, KindJsonSchemaExport, KindJsonSchemaOptions, KindSchemaFromJsonResult, SavePlanEntry, SavePlanValidation, SchemaConversionResult, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, validateBlockSchemaSavePlan } from './convert.cjs';
+export { AnyPartialKindEvent, IR_PARTIAL_KEY, KindVerdict, NODE_OUTCOME_KIND, NodeOutcomeWrapper, PartialKindEvent, PartialKindNode, PartialKindState, RUN_RESULT_KIND, RetractedKindEvent, RunResultWrapper, SupersededKindEvent, advancePartialKind, emitPayloadFence, emitPayloadJson, isProvisionalKind, isTerminalKindEvent, kindVerdictOf, makePartialKindStalenessGate, readNodeOutcomeValue, readOutputRef, readPartialKindEvent, readRunResultValue, rehydrateNodeOutcome, rehydrateRunResult, sanitizeInboundPartialKindMetadata, withRootKind } from './wire.cjs';
+import 'react';