@ai-matrx/content-ir 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1656,6 +1656,54 @@ declare function collectReferencedKinds(fields: Record<string, FieldSchema>): st
 declare function collectSchemaReferencedKinds(schema: KindSchema): string[];
 declare function kindSchemaToJsonSchema(kind: string, resolve: (kind: string) => KindSchema | undefined, options?: KindJsonSchemaOptions): KindJsonSchemaExport | null;
 
+/**
+ * JSON Schema → KindSchema — THE registry-facing direction.
+ *
+ * 🚨 WHY THIS FILE IS THE POINT OF THE WHOLE CONVERT LAYER (Arman's ruling,
+ * 2026-08-29): a kind's fields must be DERIVED from its schema, never stored a
+ * second time. `content_ir.kind_definition` used to carry both — a JSON Schema
+ * AND a flattened field list written beside it — and the two had already
+ * diverged on 13 of the 62 live kinds that carried both: stored lists holding
+ * `__kind` as if it were a data field, enums flattened to bare strings,
+ * min/max bounds and required flags the schema states and the copy never
+ * learned. A cache that can disagree with its source is not a cache.
+ *
+ * The heavy lifting lives in `openai-schema-converter.ts` (it also serves the
+ * agent-authoring flow, which needs the problems/dropped-metadata detail).
+ * This module is the narrow, honest door the registry calls: one schema in,
+ * one `KindSchema` out, plus whatever child kinds the schema declared inline
+ * or through `$defs`.
+ *
+ * Accepts both storage shapes seen in the wild: a bare JSON Schema, and the
+ * provider `{name, schema, strict}` response-format envelope that 5 live rows
+ * carry.
+ */
+
+type KindSchemaFromJsonResult = {
+    /**
+     * The requested kind's schema, or null when the input could not be read as
+     * an object contract at all. NEVER a partial guess: a field the vocabulary
+     * cannot express degrades to `json` (widening, always safe), and only a
+     * structurally unusable root yields null.
+     */
+    schema: KindSchema | null;
+    /**
+     * Child kinds the schema declared inline or via `$defs`, keyed by slug.
+     * A registry that ingests these gets the whole tree from ONE row's schema —
+     * which is how a nested kind renders before its children's rows load.
+     */
+    children: Record<string, KindSchema>;
+    /** Conversion notes. `severity: "error"` entries are worth screaming about. */
+    problems: ConversionProblem[];
+};
+/**
+ * Derive `kind`'s field schema from its JSON Schema.
+ *
+ * Pure and synchronous — no registry, no IO — so a host can call it from a
+ * warm load, a cold fetch, a reducer, or a test.
+ */
+declare function kindSchemaFromJsonSchema(kind: string, jsonSchema: unknown): KindSchemaFromJsonResult;
+
 /**
  * Streaming partial kinds — the TS twin of the Python producer's contract.
  *
@@ -1979,4 +2027,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 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 };
+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, type KindSchemaFromJsonResult, 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, kindSchemaFromJsonSchema, 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

@@ -1656,6 +1656,54 @@ declare function collectReferencedKinds(fields: Record<string, FieldSchema>): st
 declare function collectSchemaReferencedKinds(schema: KindSchema): string[];
 declare function kindSchemaToJsonSchema(kind: string, resolve: (kind: string) => KindSchema | undefined, options?: KindJsonSchemaOptions): KindJsonSchemaExport | null;
 
+/**
+ * JSON Schema → KindSchema — THE registry-facing direction.
+ *
+ * 🚨 WHY THIS FILE IS THE POINT OF THE WHOLE CONVERT LAYER (Arman's ruling,
+ * 2026-08-29): a kind's fields must be DERIVED from its schema, never stored a
+ * second time. `content_ir.kind_definition` used to carry both — a JSON Schema
+ * AND a flattened field list written beside it — and the two had already
+ * diverged on 13 of the 62 live kinds that carried both: stored lists holding
+ * `__kind` as if it were a data field, enums flattened to bare strings,
+ * min/max bounds and required flags the schema states and the copy never
+ * learned. A cache that can disagree with its source is not a cache.
+ *
+ * The heavy lifting lives in `openai-schema-converter.ts` (it also serves the
+ * agent-authoring flow, which needs the problems/dropped-metadata detail).
+ * This module is the narrow, honest door the registry calls: one schema in,
+ * one `KindSchema` out, plus whatever child kinds the schema declared inline
+ * or through `$defs`.
+ *
+ * Accepts both storage shapes seen in the wild: a bare JSON Schema, and the
+ * provider `{name, schema, strict}` response-format envelope that 5 live rows
+ * carry.
+ */
+
+type KindSchemaFromJsonResult = {
+    /**
+     * The requested kind's schema, or null when the input could not be read as
+     * an object contract at all. NEVER a partial guess: a field the vocabulary
+     * cannot express degrades to `json` (widening, always safe), and only a
+     * structurally unusable root yields null.
+     */
+    schema: KindSchema | null;
+    /**
+     * Child kinds the schema declared inline or via `$defs`, keyed by slug.
+     * A registry that ingests these gets the whole tree from ONE row's schema —
+     * which is how a nested kind renders before its children's rows load.
+     */
+    children: Record<string, KindSchema>;
+    /** Conversion notes. `severity: "error"` entries are worth screaming about. */
+    problems: ConversionProblem[];
+};
+/**
+ * Derive `kind`'s field schema from its JSON Schema.
+ *
+ * Pure and synchronous — no registry, no IO — so a host can call it from a
+ * warm load, a cold fetch, a reducer, or a test.
+ */
+declare function kindSchemaFromJsonSchema(kind: string, jsonSchema: unknown): KindSchemaFromJsonResult;
+
 /**
  * Streaming partial kinds — the TS twin of the Python producer's contract.
  *
@@ -1979,4 +2027,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 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 };
+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, type KindSchemaFromJsonResult, 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, kindSchemaFromJsonSchema, 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

@@ -3171,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;
 }
@@ -3207,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;
@@ -3228,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);
@@ -3436,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),
@@ -3470,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;
         }
@@ -3608,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({
@@ -3724,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;
@@ -4195,6 +4289,41 @@ function kindSchemaToJsonSchema(kind, resolve, options = {}) {
   return { name: kind, schema: { ...rootNode, $defs: defs }, strict, unresolved };
 }
 
+// convert/json-schema-to-kind.ts
+function kindSchemaFromJsonSchema(kind, jsonSchema) {
+  if (jsonSchema === null || jsonSchema === void 0) {
+    return { schema: null, children: {}, problems: [] };
+  }
+  const normalized = normalizeAiSchemaInput(jsonSchema);
+  const rootSchema = normalized.rootSchema ?? (typeof jsonSchema === "object" && !Array.isArray(jsonSchema) ? jsonSchema : null);
+  if (!rootSchema) {
+    return {
+      schema: null,
+      children: {},
+      problems: [
+        {
+          severity: "error",
+          path: "",
+          message: `Kind "${kind}": emitted_json_schema is not a JSON object.`
+        }
+      ]
+    };
+  }
+  const converted = convertAiSchemaToBlockFields(kind, rootSchema, false);
+  let schema = null;
+  const children = {};
+  for (const draft of converted.blockSchemas) {
+    const asKindSchema = {
+      kind: draft.slug,
+      fields: draft.fields,
+      ...draft.root ? { root: draft.root } : {}
+    };
+    if (draft.slug === kind) schema = asKindSchema;
+    else children[draft.slug] = asKindSchema;
+  }
+  return { schema, children, problems: converted.problems };
+}
+
 // wire/partial-kind.ts
 var IR_PARTIAL_KEY = "__ir_partial";
 var PARTIAL_STATES = [
@@ -4477,6 +4606,6 @@ function emitPayloadFence(kind, value) {
   return "```json\n" + emitPayloadJson(kind, value) + "\n```";
 }
 
-export { IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, IrTree, JSON_DISCRIMINATOR, JsonStreamTokenizer, KIND_KEY, KindStorageError, KindStreamParser, NODE_OUTCOME_KIND, ParseSession, ROOT_STORAGE_NAME, RUN_RESULT_KIND, 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 { IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, IrTree, JSON_DISCRIMINATOR, JsonStreamTokenizer, KIND_KEY, KindStorageError, KindStreamParser, NODE_OUTCOME_KIND, ParseSession, ROOT_STORAGE_NAME, RUN_RESULT_KIND, 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, kindSchemaFromJsonSchema, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map