@ai-matrx/content-ir 0.2.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.5.0 — 2026-08-29
+
+- **A multi-type union is no longer silently narrowed to its first member.**
+  `resolvePrimaryType` now reports every non-null member, and
+  `convertAiSchemaToBlockFields` branches on them: a union spanning
+  objects/arrays becomes `json`, a scalar-only union becomes
+  `{type:"union", scalars}`, and anything unnameable stays `json` with a
+  warning. Single-typed fields are untouched.
+
+  WHY: `type: ["string","number","boolean","object","array","null"]` —
+  pydantic's `Any`, and the commonest construct in user-authored kinds —
+  converted to plain `string`. The loss was invisible and it inverted the
+  field's meaning: an `estimated_count` of `1` then FAILED validation, so a
+  correct payload read as a broken instance. Widening is safe; silently
+  narrowing is not.
+
+- New `__tests__/json-schema-to-kind.test.ts` pins JSON Schema → KindSchema
+  over the constructs a stored field list historically could not hold —
+  pydantic-Any unions, `items: {}` arrays, arrays of `__kind` children,
+  nested `__kind` objects, and markerless inline objects. All convert with
+  zero errors, which is the evidence that `emitted_json_schema` is sufficient
+  on its own and a second stored copy of a kind's fields is unnecessary.
+
+## 0.4.0 — 2026-08-29
+
+- **`unverified` — "we never checked it" is no longer "we checked it and it
+  failed."** `IrKindState` gains `unverified`, and `raw_object` events carry a
+  `cause` (`"unverified" | "invalid"`, absent reads as `"invalid"`). The four
+  no-schema-registered degrades — the two pending-schema resolutions, plus the
+  typed and speculated finalizers — now report `unverified`; every validation
+  failure, array-item mismatch, duplicate key, bad placement, and contradicted
+  speculation still reports `invalid`. `IrTree` carries the cause onto
+  `root.kindState` and into `nodeIndex`.
+
+  WHY THIS EXISTS: `raw` meant both things, and on 2026-08-28 the render route
+  began reading `raw` as "broken instance" and diverting it away from the
+  kind's component. Every kind whose schema cannot be reconstructed — nested
+  objects, arrays of child kinds, loose fields — degrades on the no-schema
+  path, so ~221 live kinds with purpose-built components silently started
+  rendering as key/value dumps. Consumers MUST NOT treat `unverified` as a
+  failure: the value is intact and was never examined.
+
+## 0.3.0 — 2026-08-29
+
+- **KIND PRESERVATION now covers STRUCTURAL raws.** A node that degrades to
+  `raw_object` because its value failed schema validation, carried a duplicate
+  key, or violated the parent's `itemKinds` keeps its identified kind on the
+  raw event, the envelope root (`root.kind` with `kindState: "raw"`), and the
+  `nodeIndex` entry for nested children. Previously only schema-availability
+  raws preserved the kind, so a payload that was off by ONE field rendered as
+  anonymous raw JSON with no repaint subscription and no route — the single
+  most damaging class of the 2026-08-29 "kind slips through the cracks" audit
+  (crack #9). The render seam's registration boundary is unchanged: an
+  unregistered slug is still never claimed. Consumers should route a
+  registered kind-preserved raw to their generic floor and surface
+  `residue.notices` (the exact `raw_fallback` reason is recorded there).
+  Pinned by two new kind-parser tests.
+
 ## 0.2.2 — 2026-08-24
 
 - `rehydrateRunResult` now rejects nested entries whose `__kind` is not

package/dist/index.cjs

@@ -111,11 +111,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;
@@ -168,6 +177,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;
       }
@@ -366,10 +376,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,
@@ -390,7 +401,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,
@@ -728,7 +743,8 @@ var KindStreamParser = class {
           safeCopy(value),
           `No block schema registered for "${kind}".`,
           at,
-          kind
+          kind,
+          "unverified"
         );
       }
     }
@@ -762,7 +778,8 @@ var KindStreamParser = class {
           safeCopy(value ?? {}),
           `No block schema registered for "${kind}".`,
           at,
-          kind
+          kind,
+          "unverified"
         );
         this.closedPendingPaths.delete(pathKey);
         continue;
@@ -905,7 +922,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`
@@ -1308,18 +1325,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);
@@ -1342,7 +1360,8 @@ var KindStreamParser = class {
         objectValue,
         `No block schema registered for "${kind}".`,
         at,
-        kind
+        kind,
+        "unverified"
       );
       return;
     }
@@ -1351,7 +1370,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);
@@ -1411,10 +1430,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);
@@ -1425,6 +1453,7 @@ var KindStreamParser = class {
       value,
       reason,
       ...identifiedKind !== void 0 && { kind: identifiedKind },
+      cause,
       at
     });
   }
@@ -2994,21 +3023,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();
@@ -3326,7 +3360,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(