@ai-matrx/content-ir 0.3.0 → 0.6.0

package/dist/index.d.cts

@@ -12,8 +12,20 @@ import { ComponentType } from 'react';
  */
 /** 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";
+/**
+ * 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
@@ -290,6 +302,16 @@ interface SchemaResolver {
     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;
@@ -336,15 +358,23 @@ type KindStreamEvent = {
     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.
+     * 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";
@@ -508,6 +538,14 @@ declare class KindStreamParser {
     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;
@@ -596,11 +634,20 @@ declare class IrTree {
      */
     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.
+     * 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;
@@ -1932,4 +1979,4 @@ declare function emitPayloadJson(kind: string, value: unknown): string;
  */
 declare function emitPayloadFence(kind: string, value: unknown): string;
 
-export { type AnyPartialKindEvent, type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type KindVerdict, type LegResult, NODE_OUTCOME_KIND, type NodeOutcomeWrapper, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type PartialKindEvent, type PartialKindNode, type PartialKindState, type Punct, ROOT_STORAGE_NAME, RUN_RESULT_KIND, type RecordValueType, type RegionEndReason, type RegionFormat, type RegionSourceKind, type RetractedKindEvent, type RunResultWrapper, type SavePlanEntry, type SavePlanValidation, type ScalarFieldType, type SchemaConversionResult, type SchemaLayoutMode, type SchemaResolver, type StoredFieldElement, type SupersededKindEvent, advancePartialKind, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emitPayloadFence, emitPayloadJson, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isProvisionalKind, isScalarArrayType, isTerminalKindEvent, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, makePartialKindStalenessGate, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };
+export { type AnyPartialKindEvent, type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type KindVerdict, type LegResult, NODE_OUTCOME_KIND, type NodeOutcomeWrapper, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type PartialKindEvent, type PartialKindNode, type PartialKindState, type Punct, ROOT_STORAGE_NAME, RUN_RESULT_KIND, type 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, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, makePartialKindStalenessGate, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };

package/dist/index.d.ts

@@ -12,8 +12,20 @@ import { ComponentType } from 'react';
  */
 /** 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";
+/**
+ * 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
@@ -290,6 +302,16 @@ interface SchemaResolver {
     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;
@@ -336,15 +358,23 @@ type KindStreamEvent = {
     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.
+     * 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";
@@ -508,6 +538,14 @@ declare class KindStreamParser {
     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;
@@ -596,11 +634,20 @@ declare class IrTree {
      */
     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.
+     * 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;
@@ -1932,4 +1979,4 @@ declare function emitPayloadJson(kind: string, value: unknown): string;
  */
 declare function emitPayloadFence(kind: string, value: unknown): string;
 
-export { type AnyPartialKindEvent, type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type KindVerdict, type LegResult, NODE_OUTCOME_KIND, type NodeOutcomeWrapper, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type PartialKindEvent, type PartialKindNode, type PartialKindState, type Punct, ROOT_STORAGE_NAME, RUN_RESULT_KIND, type RecordValueType, type RegionEndReason, type RegionFormat, type RegionSourceKind, type RetractedKindEvent, type RunResultWrapper, type SavePlanEntry, type SavePlanValidation, type ScalarFieldType, type SchemaConversionResult, type SchemaLayoutMode, type SchemaResolver, type StoredFieldElement, type SupersededKindEvent, advancePartialKind, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emitPayloadFence, emitPayloadJson, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isProvisionalKind, isScalarArrayType, isTerminalKindEvent, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, makePartialKindStalenessGate, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };
+export { type AnyPartialKindEvent, type ArrayItemKindBinding, type ArrayItemScalarType, type BlockSchemaDraft, type CanonicalBlockIR, type CanonicalContent, type CanonicalSegment, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, type ConversionProblem, type DroppedMetadata, type DualGateDefinition, type DualGateInput, type DualGateResolvedComponent, type DualGateResult, type FieldComparison, type FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, type IrDiscriminator, type IrEnvelopeCache, type IrKindState, type IrPath, type IrResidue, type IrStructuredNode, IrTree, type IrTreeNode, type ItemKindRefCheck, JSON_DISCRIMINATOR, type JsonPath, type JsonSchemaNode, JsonStreamTokenizer, type JsonToken, KIND_KEY, type KindBlockProps, type KindDefinition, type KindEdgeSpec, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindResolution, type KindSchema, KindStorageError, type KindStorageShape, type KindStreamEvent, KindStreamParser, type KindStreamParserOptions, type KindTier, type KindVerdict, type LegResult, NODE_OUTCOME_KIND, type NodeOutcomeWrapper, type NormalizeJsonRegionOptions, ParseSession, type ParseSessionOptions, type PartialKindEvent, type PartialKindNode, type PartialKindState, type Punct, ROOT_STORAGE_NAME, RUN_RESULT_KIND, type 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, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, makePartialKindStalenessGate, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };

package/dist/index.js

@@ -105,11 +105,20 @@ var IrTree = class {
    */
   earlyFields = /* @__PURE__ */ new Map();
   /**
-   * 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.
+   * 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.
    */
   rawKinds = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  rawCauses = /* @__PURE__ */ new Map();
   regionStatus = "streaming";
   errorReason = null;
   rootRawValue = null;
@@ -162,6 +171,7 @@ var IrTree = class {
         this.pendingSchemaPaths.delete(pathKey);
         this.earlyFields.delete(pathKey);
         if (event.kind) this.rawKinds.set(pathKey, event.kind);
+        this.rawCauses.set(pathKey, event.cause ?? "invalid");
         this.markRaw(event.path, event.reason, event.value);
         return;
       }
@@ -360,10 +370,11 @@ var IrTree = class {
     const isRaw = rootRawReason !== null;
     const identifiedKind = this.identifiedKinds.get("") ?? "";
     const rootKind = isRaw ? this.rawKinds.get("") ?? "" : rootNode?.kind ?? (this.completedKind || identifiedKind);
+    const rootRawState = this.rawCauses.get("") === "unverified" ? "unverified" : "raw";
     const root = {
       role: "structured",
       kind: rootKind,
-      kindState: isRaw ? "raw" : rootNode ? rootNode.kindState : this.pendingSchemaPaths.has("") ? "pending_schema" : this.regionStatus === "streaming" ? identifiedKind ? "pending_schema" : "pending_kind" : "raw",
+      kindState: isRaw ? rootRawState : rootNode ? rootNode.kindState : this.pendingSchemaPaths.has("") ? "pending_schema" : this.regionStatus === "streaming" ? identifiedKind ? "pending_schema" : "pending_kind" : "raw",
       discriminator: JSON_DISCRIMINATOR,
       path: [],
       status: this.regionStatus,
@@ -386,7 +397,7 @@ var IrTree = class {
       if (pathKey === "") continue;
       nodeIndex[pathKey] = {
         kind: this.rawKinds.get(pathKey) ?? "",
-        kindState: "raw",
+        kindState: this.rawCauses.get(pathKey) === "unverified" ? "unverified" : "raw",
         status: "complete"
       };
     }
@@ -726,7 +737,8 @@ var KindStreamParser = class {
           safeCopy(value),
           `No block schema registered for "${kind}".`,
           at,
-          kind
+          kind,
+          "unverified"
         );
       }
     }
@@ -760,7 +772,8 @@ var KindStreamParser = class {
           safeCopy(value ?? {}),
           `No block schema registered for "${kind}".`,
           at,
-          kind
+          kind,
+          "unverified"
         );
         this.closedPendingPaths.delete(pathKey);
         continue;
@@ -1306,7 +1319,8 @@ var KindStreamParser = class {
         objectValue,
         `No block schema registered for "${kind}".`,
         at,
-        kind
+        kind,
+        "unverified"
       );
       return;
     }
@@ -1340,7 +1354,8 @@ var KindStreamParser = class {
         objectValue,
         `No block schema registered for "${kind}".`,
         at,
-        kind
+        kind,
+        "unverified"
       );
       return;
     }
@@ -1413,7 +1428,15 @@ var KindStreamParser = class {
     this.speculativeKinds.delete(pathKey);
     this.emitRawObject(path, safeCopy(liveValue), reason, at, identifiedKind);
   }
-  emitRawObject(path, value, reason, at, identifiedKind) {
+  /**
+   * 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`.
+   */
+  emitRawObject(path, value, reason, at, identifiedKind, cause = "invalid") {
     const pathKey = this.pathKey(path);
     if (this.rawObjectPaths.has(pathKey)) return;
     this.rawObjectPaths.add(pathKey);
@@ -1424,6 +1447,7 @@ var KindStreamParser = class {
       value,
       reason,
       ...identifiedKind !== void 0 && { kind: identifiedKind },
+      cause,
       at
     });
   }
@@ -2993,21 +3017,26 @@ function fieldSchemaSummary(field) {
 function resolvePrimaryType(node) {
   const raw = node.type;
   if (typeof raw === "string") {
-    return { type: raw === "integer" ? "number" : raw, nullable: false };
+    const t = raw === "integer" ? "number" : raw;
+    return { type: t, nullable: false, members: [t] };
   }
   if (Array.isArray(raw)) {
     const types = raw.filter((t) => typeof t === "string");
     const nullable = types.includes("null");
-    const primary = types.find((t) => t !== "null") ?? (nullable && types.length === 1 ? "null" : null);
-    if (primary === "integer") {
-      return { type: "number", nullable };
-    }
-    return { type: primary ?? null, nullable };
-  }
-  if (node.enum) return { type: "string", nullable: false };
-  if (node.properties) return { type: "object", nullable: false };
-  if (node.items) return { type: "array", nullable: false };
-  return { type: null, nullable: false };
+    const members = [
+      ...new Set(
+        types.filter((t) => t !== "null").map((t) => t === "integer" ? "number" : t)
+      )
+    ];
+    const primary = members[0] ?? (nullable && types.length === 1 ? "null" : null);
+    return { type: primary ?? null, nullable, members };
+  }
+  if (node.enum) return { type: "string", nullable: false, members: ["string"] };
+  if (node.properties)
+    return { type: "object", nullable: false, members: ["object"] };
+  if (node.items)
+    return { type: "array", nullable: false, members: ["array"] };
+  return { type: null, nullable: false, members: [] };
 }
 function carriedMetadataKeys(field) {
   if (field === null) return /* @__PURE__ */ new Set();
@@ -3142,6 +3171,29 @@ function buildAgentSchemaWithRenderBlockSupport(input, rootKindSlug, arrayBindin
   }
   return updatedRoot;
 }
+function resolveRef(ref, ctx) {
+  if (ref === "#" || ref === "#/") {
+    return { slug: ctx.schemaName, node: ctx.rootSchema };
+  }
+  const match = /^#\/(?:\$defs|definitions)\/(.+)$/.exec(ref);
+  if (!match) return null;
+  const name = decodeURIComponent(
+    (match[1] ?? "").replace(/~1/g, "/").replace(/~0/g, "~")
+  );
+  const node = ctx.defs[name];
+  if (!isRecord4(node)) return null;
+  const declared = isRecord4(node.properties) ? readBlockKindFromProperties(node.properties) : null;
+  return { slug: declared ?? name, node };
+}
+function refToObjectField(resolved, path, ctx) {
+  if (ctx.refsInProgress.has(resolved.slug)) return;
+  ctx.refsInProgress.add(resolved.slug);
+  try {
+    registerDeclaredKindDraft(resolved.slug, resolved.node, path, ctx);
+  } finally {
+    ctx.refsInProgress.delete(resolved.slug);
+  }
+}
 function isAnyValueSchema(node) {
   return node.type === void 0 && node.enum === void 0 && node.const === void 0 && node.properties === void 0 && node.items === void 0 && node.additionalProperties === void 0 && node.anyOf === void 0 && node.oneOf === void 0 && node.allOf === void 0 && node.$ref === void 0;
 }
@@ -3178,12 +3230,21 @@ function convertProperty(fieldName, node, required, path, ctx) {
 }
 function convertPropertyCore(fieldName, node, required, path, ctx) {
   if (typeof node.$ref === "string") {
-    ctx.problems.push({
-      severity: "error",
-      path,
-      message: `$ref is not supported ("${node.$ref}"). Inline the schema manually.`
-    });
-    return null;
+    const resolved = resolveRef(node.$ref, ctx);
+    if (!resolved) {
+      ctx.problems.push({
+        severity: "error",
+        path,
+        message: `Unresolvable $ref ("${node.$ref}") \u2014 only "#", "#/$defs/<name>" and "#/definitions/<name>" are supported.`
+      });
+      return null;
+    }
+    refToObjectField(resolved, path, ctx);
+    return {
+      ...requiredNullableFlags(required),
+      type: "object",
+      kind: resolved.slug
+    };
   }
   if (Array.isArray(node.anyOf) || Array.isArray(node.oneOf)) {
     const variants = node.anyOf ?? node.oneOf;
@@ -3199,12 +3260,18 @@ function convertPropertyCore(fieldName, node, required, path, ctx) {
         continue;
       }
       if (typeof variant.$ref === "string") {
-        ctx.problems.push({
-          severity: "error",
-          path,
-          message: `$ref inside anyOf/oneOf is not supported ("${variant.$ref}"). Inline the schema manually.`
-        });
-        unsupported = true;
+        const resolvedVariant = resolveRef(variant.$ref, ctx);
+        if (!resolvedVariant) {
+          ctx.problems.push({
+            severity: "error",
+            path,
+            message: `Unresolvable $ref inside anyOf/oneOf ("${variant.$ref}").`
+          });
+          unsupported = true;
+          continue;
+        }
+        refToObjectField(resolvedVariant, path, ctx);
+        memberKinds.push(resolvedVariant.slug);
         continue;
       }
       const { type: type2, nullable: nullable2 } = resolvePrimaryType(variant);
@@ -3325,7 +3392,34 @@ function convertPropertyCore(fieldName, node, required, path, ctx) {
     });
     return { ...requiredNullableFlags(required), type: "json" };
   }
-  const { type, nullable } = resolvePrimaryType(node);
+  const { type, nullable, members } = resolvePrimaryType(node);
+  if (members.length > 1) {
+    const objectish = members.some((m) => m === "object" || m === "array");
+    if (objectish) {
+      ctx.problems.push({
+        severity: "info",
+        path,
+        message: `Union of [${members.join(", ")}] at "${path || "(root)"}" spans objects/arrays \u2014 carried as any JSON value (json).`
+      });
+      return { ...requiredNullableFlags(required), type: "json" };
+    }
+    const scalars = members.filter(
+      (m) => m === "string" || m === "number" || m === "boolean"
+    );
+    if (scalars.length === members.length && scalars.length > 1) {
+      return {
+        ...requiredNullableFlags(required, nullable),
+        type: "union",
+        scalars
+      };
+    }
+    ctx.problems.push({
+      severity: "warning",
+      path,
+      message: `Union of [${members.join(", ")}] at "${path || "(root)"}" has no exact field type \u2014 carried as any JSON value (json) rather than narrowed to "${type}".`
+    });
+    return { ...requiredNullableFlags(required), type: "json" };
+  }
   if (type === "string") {
     if (Array.isArray(node.enum)) {
       const values = node.enum.filter(
@@ -3380,6 +3474,27 @@ function convertPropertyCore(fieldName, node, required, path, ctx) {
       });
       return null;
     }
+    if (typeof itemNode.$ref === "string") {
+      const resolvedItem = resolveRef(itemNode.$ref, ctx);
+      if (!resolvedItem) {
+        ctx.problems.push({
+          severity: "error",
+          path: `${path}[]`,
+          message: `Unresolvable $ref in array items ("${itemNode.$ref}").`
+        });
+        return null;
+      }
+      refToObjectField(resolvedItem, `${path}[]`, ctx);
+      ctx.arrayBindings.push({
+        arrayField: fieldName,
+        itemKindSlug: resolvedItem.slug
+      });
+      return {
+        ...requiredNullableFlags(required, nullable),
+        type: "array",
+        itemKinds: [resolvedItem.slug]
+      };
+    }
     if (isAnyValueSchema(itemNode)) {
       return {
         ...requiredNullableFlags(required, nullable),
@@ -3414,11 +3529,29 @@ function convertPropertyCore(fieldName, node, required, path, ctx) {
       }
       const itemKinds = [];
       for (const variant of itemVariants) {
+        if (isRecord4(variant) && typeof variant.$ref === "string") {
+          const resolvedVariant = resolveRef(variant.$ref, ctx);
+          if (!resolvedVariant) {
+            ctx.problems.push({
+              severity: "error",
+              path: `${path}[]`,
+              message: `Unresolvable $ref in array items anyOf ("${variant.$ref}").`
+            });
+            return null;
+          }
+          itemKinds.push(resolvedVariant.slug);
+          refToObjectField(resolvedVariant, `${path}[]<${resolvedVariant.slug}>`, ctx);
+          ctx.arrayBindings.push({
+            arrayField: fieldName,
+            itemKindSlug: resolvedVariant.slug
+          });
+          continue;
+        }
         if (!isRecord4(variant) || !isRecord4(variant.properties)) {
           ctx.problems.push({
             severity: "error",
             path: `${path}[]`,
-            message: "Array items anyOf/oneOf variants must be inline objects declaring __kind."
+            message: "Array items anyOf/oneOf variants must be inline objects declaring __kind, or $refs to defs."
           });
           return null;
         }
@@ -3552,6 +3685,14 @@ function convertPropertyCore(fieldName, node, required, path, ctx) {
           kind: referencedKind
         };
       }
+      if (Object.keys(nestedFields).length === 0 && !apIsOpen && isRecord4(ap) && KIND_KEY in node.properties) {
+        const apType = resolvePrimaryType(ap).type;
+        return {
+          ...requiredNullableFlags(required, nullable),
+          type: "record",
+          values: apType === "string" || apType === "number" || apType === "boolean" ? apType : "json"
+        };
+      }
       let open = apIsOpen;
       if (!apIsOpen && isRecord4(ap)) {
         ctx.problems.push({
@@ -3668,12 +3809,21 @@ function normalizeAiSchemaInput(input) {
   return { name: null, strict: null, rootSchema: null, parseErrors };
 }
 function convertAiSchemaToBlockFields(schemaName, rootSchema, strict) {
+  const rawDefs = isRecord4(rootSchema.$defs) ? rootSchema.$defs : isRecord4(rootSchema.definitions) ? rootSchema.definitions : {};
+  const defs = {};
+  for (const [name, node] of Object.entries(rawDefs)) {
+    if (isRecord4(node)) defs[name] = node;
+  }
   const ctx = {
     schemaName,
+    strict,
     problems: [],
     droppedMetadata: [],
     blockSchemas: [],
-    arrayBindings: []
+    arrayBindings: [],
+    defs,
+    rootSchema,
+    refsInProgress: /* @__PURE__ */ new Set()
   };
   ctx.droppedMetadata.push(...collectDropped(rootSchema, ""));
   const rootAp = rootSchema.additionalProperties;