@ai-matrx/content-ir 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.6.0 — 2026-08-29
+
+- **`$ref` / `$defs` resolution — a kind's child kinds are no longer invisible
+  to JSON Schema → KindSchema.** `convertAiSchemaToBlockFields` resolves `#`,
+  `#/$defs/<name>` and `#/definitions/<name>` in field position, in array
+  `items`, and inside `anyOf`/`oneOf` (including `items: {anyOf: [$ref, …]}`,
+  the multi-kind array). Referenced defs are registered as their own drafts,
+  with a cycle brake so a self-referencing kind terminates. An unresolvable
+  ref is a loud error, never a guess.
+
+  WHY: `kindSchemaToJsonSchema` externalizes every child kind as a `$def`, and
+  the reverse direction rejected `$ref` outright — so every
+  `{type:"object", kind}` and `{type:"array", itemKinds}` field came back
+  EMPTY. Measured over the 62 live kinds carrying both a stored field list and
+  a schema, 36 lost fields this way (sections, slides, nodes, edges, criteria,
+  questions, segments, …).
+
+- **A `__kind`-carrying record reads back as a record.** An object whose only
+  declared property is `__kind`, with typed `additionalProperties`, is the
+  forward converter's emission for `{type:"record", values}` — it was widening
+  to an open `inline_object` and losing the value type.
+
+- Live-corpus result: schema-derived KindSchemas now match the stored field
+  list byte-for-byte for 48 of 62 kinds, with 1 strictly richer. The remaining
+  13 are DIVERGENCE BETWEEN THE TWO STORED COPIES, not conversion gaps — 4
+  stored lists carry `__kind` as a data field (it is the discriminator, never
+  a field), and 9 disagree on enums, bounds, required flags or descriptions
+  the schema states and the copy does not. That is the evidence for retiring
+  the stored copy.
+
 ## 0.5.0 — 2026-08-29
 
 - **A multi-type union is no longer silently narrowed to its first member.**

package/dist/index.cjs

@@ -3177,6 +3177,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;
 }
@@ -3213,12 +3236,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;
@@ -3234,12 +3266,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);
@@ -3442,6 +3480,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),
@@ -3476,11 +3535,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;
         }
@@ -3614,6 +3691,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({
@@ -3730,12 +3815,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;