@ai-matrx/content-ir 0.2.2 → 0.5.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";
@@ -462,7 +492,7 @@ declare class KindStreamParser {
      * 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
+     * legacy shapes are recognized by their whole payload, so speculating
      * mid-stream would flash a kind component over an object that may never
      * satisfy the schema. An explicit `expectedRootKind` (an agent's declared
      * output schema) is stronger context and always wins; an actual `__kind`
@@ -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;
@@ -877,7 +924,7 @@ declare function envelopeCacheFromEnvelopes(envelopes: readonly CanonicalBlockIR
  *
  * 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.
+ * its own. Contract: /Users/armanisadeghi/code/common-docs/systems/content-ir-system/PYTHON_ENVELOPE_CONTRACT.md.
  */
 
 /** Read a CanonicalBlockIR envelope off a block's metadata (or anything). */
@@ -1194,7 +1241,7 @@ interface KindDefinition {
  *     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):
+ * Design invariants (from the 2026-07-05 kind-registry storage design, since deleted):
  *   - The `data` element is `FieldSchema` + `name`, MINUS ref targets. Order is
  *     intrinsic to the array (fixes the jsonb key-reorder bug).
  *   - `kind_edge` is the SINGLE source of truth for kind→kind refs: `object`
@@ -1334,7 +1381,7 @@ declare function storageToKindSchema(kind: string, shape: KindStorageShape): Kin
  * 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
+ * Ownership split (the 2026-07-05 kind-registry storage design, since deleted; the live contract is the code below): the caller writes the outcome
  * to the LIVE `content_ir.kind_definition` row's `is_active`; the canonical
  * `_version_capture` trigger snapshots that state into `history.row_versions`
  * (never a post-hoc history mutation).
@@ -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";
@@ -462,7 +492,7 @@ declare class KindStreamParser {
      * 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
+     * legacy shapes are recognized by their whole payload, so speculating
      * mid-stream would flash a kind component over an object that may never
      * satisfy the schema. An explicit `expectedRootKind` (an agent's declared
      * output schema) is stronger context and always wins; an actual `__kind`
@@ -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;
@@ -877,7 +924,7 @@ declare function envelopeCacheFromEnvelopes(envelopes: readonly CanonicalBlockIR
  *
  * 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.
+ * its own. Contract: /Users/armanisadeghi/code/common-docs/systems/content-ir-system/PYTHON_ENVELOPE_CONTRACT.md.
  */
 
 /** Read a CanonicalBlockIR envelope off a block's metadata (or anything). */
@@ -1194,7 +1241,7 @@ interface KindDefinition {
  *     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):
+ * Design invariants (from the 2026-07-05 kind-registry storage design, since deleted):
  *   - The `data` element is `FieldSchema` + `name`, MINUS ref targets. Order is
  *     intrinsic to the array (fixes the jsonb key-reorder bug).
  *   - `kind_edge` is the SINGLE source of truth for kind→kind refs: `object`
@@ -1334,7 +1381,7 @@ declare function storageToKindSchema(kind: string, shape: KindStorageShape): Kin
  * 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
+ * Ownership split (the 2026-07-05 kind-registry storage design, since deleted; the live contract is the code below): the caller writes the outcome
  * to the LIVE `content_ir.kind_definition` row's `is_active`; the canonical
  * `_version_capture` trigger snapshots that state into `history.row_versions`
  * (never a post-hoc history mutation).
@@ -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,
@@ -384,7 +395,11 @@ var IrTree = class {
     }
     for (const [pathKey] of this.rawPaths) {
       if (pathKey === "") continue;
-      nodeIndex[pathKey] = { kind: "", kindState: "raw", status: "complete" };
+      nodeIndex[pathKey] = {
+        kind: this.rawKinds.get(pathKey) ?? "",
+        kindState: this.rawCauses.get(pathKey) === "unverified" ? "unverified" : "raw",
+        status: "complete"
+      };
     }
     return {
       v: IR_VERSION,
@@ -722,7 +737,8 @@ var KindStreamParser = class {
           safeCopy(value),
           `No block schema registered for "${kind}".`,
           at,
-          kind
+          kind,
+          "unverified"
         );
       }
     }
@@ -756,7 +772,8 @@ var KindStreamParser = class {
           safeCopy(value ?? {}),
           `No block schema registered for "${kind}".`,
           at,
-          kind
+          kind,
+          "unverified"
         );
         this.closedPendingPaths.delete(pathKey);
         continue;
@@ -899,7 +916,7 @@ var KindStreamParser = class {
    * 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
+   * legacy shapes are recognized by their whole payload, so speculating
    * mid-stream would flash a kind component over an object that may never
    * satisfy the schema. An explicit `expectedRootKind` (an agent's declared
    * output schema) is stronger context and always wins; an actual `__kind`
@@ -1302,18 +1319,19 @@ var KindStreamParser = class {
         objectValue,
         `No block schema registered for "${kind}".`,
         at,
-        kind
+        kind,
+        "unverified"
       );
       return;
     }
     const arrayItemError = this.validateArrayItemKind(path, kind);
     if (arrayItemError) {
-      this.emitRawObject(path, objectValue, arrayItemError, at);
+      this.emitRawObject(path, objectValue, arrayItemError, at, kind);
       return;
     }
     const outcome = this.validateObjectAgainstSchema(objectValue, schema);
     if (outcome.error) {
-      this.emitRawObject(path, objectValue, outcome.error, at);
+      this.emitRawObject(path, objectValue, outcome.error, at, kind);
       return;
     }
     this.objectKinds.set(pathKey, kind);
@@ -1336,7 +1354,8 @@ var KindStreamParser = class {
         objectValue,
         `No block schema registered for "${kind}".`,
         at,
-        kind
+        kind,
+        "unverified"
       );
       return;
     }
@@ -1345,7 +1364,7 @@ var KindStreamParser = class {
       schema
     );
     if (outcome.error) {
-      this.emitRawObject(path, objectValue, outcome.error, at);
+      this.emitRawObject(path, objectValue, outcome.error, at, kind);
       return;
     }
     this.emitSchemaNotices(path, kind, outcome, at);
@@ -1405,10 +1424,19 @@ var KindStreamParser = class {
   markNodeRaw(path, liveValue, reason, at) {
     const pathKey = this.pathKey(path);
     if (this.rawObjectPaths.has(pathKey)) return;
+    const identifiedKind = this.objectKinds.get(pathKey) ?? (typeof liveValue === "object" && liveValue !== null && !Array.isArray(liveValue) ? readObjectKind(liveValue) ?? void 0 : void 0);
     this.speculativeKinds.delete(pathKey);
-    this.emitRawObject(path, safeCopy(liveValue), reason, at);
+    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);
@@ -1419,6 +1447,7 @@ var KindStreamParser = class {
       value,
       reason,
       ...identifiedKind !== void 0 && { kind: identifiedKind },
+      cause,
       at
     });
   }
@@ -2988,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();
@@ -3320,7 +3354,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(