@ai-matrx/content-ir 0.9.0 → 0.10.1

package/dist/convert.d.ts

@@ -0,0 +1,230 @@
+import { F as FieldSchema, a as KindSchema } from './kind-schema.types-CwncWj9U.js';
+
+/**
+ * OpenAI/provider JSON Schema → KindSchema converter + __kind injection.
+ *
+ * The strategic keystone: `buildAgentSchemaWithRenderBlockSupport` turns "a
+ * user/agent defined an output schema" into "the platform has a render
+ * contract for it" by injecting the `__kind` discriminator into the agent's
+ * output schema (root + array items), so the model emits self-identifying
+ * objects from then on.
+ *
+ * Moved from app/(dev)/demos/json-block-detector/schema-converter.ts.
+ */
+
+type JsonSchemaNode = Record<string, unknown>;
+type ConversionProblem = {
+    severity: "error" | "warning" | "info";
+    path: string;
+    message: string;
+};
+type DroppedMetadata = {
+    path: string;
+    dropped: Record<string, unknown>;
+};
+type FieldComparison = {
+    field: string;
+    aiPresent: boolean;
+    blockPresent: boolean;
+    aiSummary: string | null;
+    blockSummary: string | null;
+    status: "match" | "ai_only" | "block_only" | "type_mismatch" | "ai_richer" | "block_richer";
+    detail?: string;
+};
+/** One standalone flexible_data block schema row. */
+type BlockSchemaDraft = {
+    slug: string;
+    label: string;
+    fields: Record<string, FieldSchema>;
+    /**
+     * NON-OBJECT ROOT form (KindSchema.root): the kind's value is this field's
+     * shape at the top level (scalar / array / json / OPEN object). When set,
+     * `fields` is empty — mirror of `KindSchema.root`.
+     */
+    root?: FieldSchema;
+};
+type ArrayItemKindBinding = {
+    arrayField: string;
+    itemKindSlug: string;
+};
+type SchemaConversionResult = {
+    schemaName: string | null;
+    strict: boolean | null;
+    /** Every block schema row required for the converted shape (1..n). */
+    blockSchemas: BlockSchemaDraft[];
+    /** OPTION 2 — same input shape with __kind injected for agent output. */
+    agentSchemaWithKinds: unknown | null;
+    problems: ConversionProblem[];
+    droppedMetadata: DroppedMetadata[];
+    comparisons: FieldComparison[];
+};
+type SavePlanEntry = {
+    draft: BlockSchemaDraft;
+    existsInDb: boolean;
+    willSave: boolean;
+};
+type ItemKindRefCheck = {
+    parentSlug: string;
+    field: string;
+    itemKind: string;
+    satisfied: boolean;
+    source: "batch" | "database" | "missing";
+};
+type SavePlanValidation = {
+    entries: SavePlanEntry[];
+    itemKindRefs: ItemKindRefCheck[];
+    newCount: number;
+    canSave: boolean;
+    errors: string[];
+};
+/**
+ * Inject the `__kind` discriminator into one object schema (const when
+ * strict, enum otherwise; `__kind` prepended to required; strict also pins
+ * additionalProperties:false). Shared with the REVERSE converter
+ * (kind-to-json-schema.ts) so both directions stamp identical discriminators.
+ */
+declare function injectKindIntoObjectSchema(objectSchema: JsonSchemaNode, kindSlug: string, strict: boolean): JsonSchemaNode;
+declare function buildAgentSchemaWithRenderBlockSupport(input: unknown, rootKindSlug: string, arrayBindings: ArrayItemKindBinding[], strict: boolean): unknown | null;
+declare function normalizeAiSchemaInput(input: unknown): {
+    name: string | null;
+    strict: boolean | null;
+    rootSchema: JsonSchemaNode | null;
+    parseErrors: string[];
+};
+type ConversionCore = {
+    schemaName: string | null;
+    strict: boolean | null;
+    blockSchemas: BlockSchemaDraft[];
+    problems: ConversionProblem[];
+    droppedMetadata: DroppedMetadata[];
+};
+declare function convertAiSchemaToBlockFields(schemaName: string, rootSchema: JsonSchemaNode, strict: boolean): ConversionCore;
+declare function compareWithExistingKindSchema(convertedFields: Record<string, FieldSchema>, existing: KindSchema | null): FieldComparison[];
+declare function runSchemaConversion(input: unknown, existingSchemas: Record<string, KindSchema>): SchemaConversionResult & {
+    parseErrors: string[];
+};
+declare function validateBlockSchemaSavePlan(blockSchemas: BlockSchemaDraft[], existingSlugs: string[], hasConversionErrors: boolean): SavePlanValidation;
+declare function fieldsToDbPayload(fields: Record<string, FieldSchema>): Record<string, unknown>;
+declare function isDuplicateBlockSlug(slug: string, entries: Array<{
+    slug: string;
+}>): boolean;
+
+/**
+ * KindSchema → provider-ready JSON Schema — the REVERSE of the OpenAI
+ * converter in openai-schema-converter.ts.
+ *
+ * The requested root kind renders INLINE as the top-level object; every
+ * OTHER kind it transitively references (via `{type:"object", kind}` and
+ * `{type:"array", itemKinds}` fields, including inside inline_objects)
+ * becomes a `$defs` entry referenced with `$ref: "#/$defs/<slug>"`.
+ * References back to the ROOT kind use `"#"` — the standard JSON Schema
+ * recursive-root reference (OpenAI structured outputs support both forms).
+ * Collection is cycle-safe: each kind enters the closure exactly once.
+ *
+ * Round-trip contract — output fed through `runSchemaConversion`
+ * (openai-schema-converter.ts) reproduces the source KindSchemas for the
+ * root and every array-item child (enforced by
+ * __tests__/kind-to-json-schema.test.ts). The 2026-07-15 expressivity
+ * extension closed the three historical asymmetries: `record` now has a
+ * forward target (properties-less objects → record scalar/json), multi-
+ * itemKind arrays read back through items-anyOf when each variant declares
+ * its `__kind`, and nullable anyOf preserves the member list + nullable flag
+ * instead of flattening to `string`. Remaining accepted narrowings:
+ * - multi-kind array items emitted as $refs (not inline __kind objects)
+ *   still cannot be read back — the forward converter rejects $ref.
+ * - a nullable object-REF (`anyOf: [$ref, {type:"null"}]`) degrades for the
+ *   same $ref reason.
+ * - JSON Schema `integer` narrows to `number` (the map_result precedent).
+ */
+
+type KindJsonSchemaOptions = {
+    /**
+     * Provider strict mode: additionalProperties:false on every kind object
+     * and inline object, and `const` (vs `enum`) __kind discriminators —
+     * mirrors makeKindJsonSchemaProperty / injectKindIntoObjectSchema.
+     */
+    strict?: boolean;
+    /**
+     * Inject the `__kind` discriminator (+ required) into the root and every
+     * $defs kind object. Default true — this is what makes the emitted
+     * objects self-identifying for the render pipeline.
+     */
+    injectKind?: boolean;
+};
+type KindJsonSchemaExport = {
+    /** The root kind slug — doubles as the provider schema name. */
+    name: string;
+    schema: JsonSchemaNode;
+    strict: boolean;
+    /**
+     * Referenced kinds the resolver could not supply. Each still gets a
+     * permissive `$defs` object stub (never additionalProperties:false, even
+     * in strict mode — a __kind-only strict object would reject every real
+     * payload) so the export stays structurally valid. Surface these loudly.
+     */
+    unresolved: string[];
+};
+/**
+ * Every kind referenced by a field map — `{type:"object", kind}` refs and
+ * `{type:"array", itemKinds}` members, recursing through inline_objects.
+ * First-sighting order, deduplicated. Shared read helper (the registry
+ * catalog builds its uses / used-by graph from this).
+ */
+declare function collectReferencedKinds(fields: Record<string, FieldSchema>): string[];
+/**
+ * Schema-level referenced kinds — field-map refs PLUS the refs a non-object
+ * root form carries. Use this (not `collectReferencedKinds(schema.fields)`)
+ * whenever the schema in hand may be root-form.
+ */
+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;
+
+export { type ArrayItemKindBinding, type BlockSchemaDraft, type ConversionProblem, type DroppedMetadata, type FieldComparison, type ItemKindRefCheck, type JsonSchemaNode, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindSchemaFromJsonResult, type SavePlanEntry, type SavePlanValidation, type SchemaConversionResult, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, validateBlockSchemaSavePlan };