@ai-matrx/content-ir 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1601 @@
+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. */
+type IrKindState = "resolved" | "speculative" | "pending_kind" | "pending_schema" | "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;
+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 raw —
+     * present ONLY for schema-availability failures ("no schema registered"
+     * for an identified/declared kind), never for structural failures
+     * (missing __kind, duplicate keys, schema violations). Consumers use it
+     * to preserve a known-but-unrenderable kind on the envelope so the
+     * render seam can route to the generic viewer (or upgrade when the
+     * schema arrives late) instead of dumping raw JSON.
+     */
+    kind?: string;
+    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 options;
+    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;
+    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 recognised 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;
+    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 SCHEMA-AVAILABILITY raw
+     * fallback (parser stamped `kind` on the raw_object event). Structural raws
+     * (missing __kind, duplicate key, validation failure) never land here.
+     */
+    private readonly rawKinds;
+    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 readonly onToken;
+    private mode;
+    private pos;
+    private stringBuffer;
+    private primitiveBuffer;
+    private unicodeBuffer;
+    private tokenStart;
+    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: features/content-ir/docs/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 (the parser injects it into snapshots). */
+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 (KIND_REGISTRY_STORAGE.md §4):
+ *   - 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 (KIND_REGISTRY_STORAGE.md §2): 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 + `__kind`-stripping semantics as activation — 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;
+
+export { type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type LegResult, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type Punct, ROOT_STORAGE_NAME, type RecordValueType, type RegionEndReason, type RegionFormat, type RegionSourceKind, type SavePlanEntry, type SavePlanValidation, type ScalarFieldType, type SchemaConversionResult, type SchemaLayoutMode, type SchemaResolver, type StoredFieldElement, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isScalarArrayType, kindSchemaToJsonSchema, kindSchemaToStorage, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readObjectKind, reconstructRegionValue, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, xmlDiscriminator };