@ai-matrx/content-ir 0.19.20 → 0.19.25

package/dist/convert.d.cts

@@ -219,12 +219,81 @@ type KindSchemaFromJsonResult = {
     /** Conversion notes. `severity: "error"` entries are worth screaming about. */
     problems: ConversionProblem[];
 };
+type KindSchemaFromJsonOptions = {
+    /**
+     * The registry row's `metadata.disposition`. A `record` kind's schema gains the four
+     * control keys (`_replaces`, `_new`, `_record_id`, `_records`) as optional render fields
+     * (`withControlKeys`, KINDS-GLUE wave 2 §1.4), so an agent's patch, batch or signal draws
+     * through its kind instead of reading as unknown keys. Any other value adds nothing.
+     */
+    disposition?: string | null;
+};
 /**
  * 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;
+declare function kindSchemaFromJsonSchema(kind: string, jsonSchema: unknown, options?: KindSchemaFromJsonOptions): KindSchemaFromJsonResult;
+
+/**
+ * The four control keys an agent may put beside a kind's values — the TypeScript twin of
+ * `matrx_graph.kind_control_keys.with_control_keys` (aidream). ONE definition, two languages:
+ * for the same input both produce the same JSON (guard W2-G7, the shared golden
+ * `packages/matrx-graph/tests/fixtures/kind_control_keys_golden.json`).
+ *
+ * `_replaces` ("this replaces that output"), `_new` ("this is something new"), `_record_id`
+ * ("change this record") and `_records` ("several records") are never part of a kind and no
+ * registry row carries them — they are added where a schema is USED, for `record` kinds and
+ * table kinds only:
+ *
+ * - `withControlKeys(schema, { mode: "stored" })` — the JSON Schema a value is validated
+ *   against: all four declared optional (nullable), and the root's required Fields lifted when
+ *   the value is a patch (`_record_id`) or a batch (`_records`) — one branch APPENDED to `allOf`,
+ *   never replacing it.
+ * - `withControlKeys(schema, { mode: "authored", many, allowEdit })` — what the model is shown:
+ *   `_replaces`/`_new` always, `_record_id` only with `allowEdit`, and with `many` the root is
+ *   the batch `{__kind, _records: [<record without __kind>], ...}`. Signals are OPTIONAL — the
+ *   provider translators widen them to required-and-nullable on the wire and prune a null back.
+ * - `withControlKeyFields(kindSchema)` — the render-level twin: the four keys as optional
+ *   render fields of a `KindSchema`, so a patch, a batch or a signal is drawn by its kind's
+ *   component instead of being reported as unknown keys. The web schema is never stricter
+ *   than the store.
+ *
+ * Design: common-docs `projects/data-doctrine-adoption/v6/KINDS-GLUE-WAVE2-DESIGN.md` §1.4.
+ */
+
+/** The four keys, in the order they are declared. */
+declare const CONTROL_KEYS: readonly ["_replaces", "_new", "_record_id", "_records"];
+type ControlKey = (typeof CONTROL_KEYS)[number];
+/** The one disposition whose kinds take the control keys (table kinds are always `record`). */
+declare const RECORD_DISPOSITION = "record";
+type ControlKeysMode = "stored" | "authored";
+type WithControlKeysOptions = {
+    mode: ControlKeysMode;
+    /** Authored mode: the root becomes the batch `{__kind, _records: [...]}`. */
+    many?: boolean;
+    /** Authored mode: the model may name `_record_id` (the run may edit its own outputs). */
+    allowEdit?: boolean;
+};
+/** Whether a kind with this disposition takes the control keys. */
+declare function controlKeysApplyTo(disposition: string | null | undefined): boolean;
+/**
+ * A copy of `schema` that carries the control keys for `mode`. A schema that is not an object
+ * with `properties` (a root-form kind, the "any value" `{}`) is returned unchanged.
+ */
+declare function withControlKeys<T>(schema: T, options: WithControlKeysOptions): T;
+/** The render fields the control keys add to a `KindSchema` — all optional, none stricter than the store. */
+declare const CONTROL_KEY_FIELDS: Readonly<Record<ControlKey, FieldSchema>>;
+/**
+ * `schema` with the four control keys as optional render fields. A root-form kind (no field
+ * map) is returned unchanged. Keys the kind itself declares are left as the kind declares them.
+ */
+declare function withControlKeyFields(schema: KindSchema): KindSchema;
+/** Split a value into (values without the control keys, the control keys present). */
+declare function stripControlKeys(value: Record<string, unknown>): {
+    values: Record<string, unknown>;
+    signals: Partial<Record<ControlKey, unknown>>;
+};
 
-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 };
+export { type ArrayItemKindBinding, type BlockSchemaDraft, CONTROL_KEYS, CONTROL_KEY_FIELDS, type ControlKey, type ControlKeysMode, type ConversionProblem, type DroppedMetadata, type FieldComparison, type ItemKindRefCheck, type JsonSchemaNode, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindSchemaFromJsonOptions, type KindSchemaFromJsonResult, RECORD_DISPOSITION, type SavePlanEntry, type SavePlanValidation, type SchemaConversionResult, type WithControlKeysOptions, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, controlKeysApplyTo, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, stripControlKeys, validateBlockSchemaSavePlan, withControlKeyFields, withControlKeys };

package/dist/convert.d.ts

@@ -219,12 +219,81 @@ type KindSchemaFromJsonResult = {
     /** Conversion notes. `severity: "error"` entries are worth screaming about. */
     problems: ConversionProblem[];
 };
+type KindSchemaFromJsonOptions = {
+    /**
+     * The registry row's `metadata.disposition`. A `record` kind's schema gains the four
+     * control keys (`_replaces`, `_new`, `_record_id`, `_records`) as optional render fields
+     * (`withControlKeys`, KINDS-GLUE wave 2 §1.4), so an agent's patch, batch or signal draws
+     * through its kind instead of reading as unknown keys. Any other value adds nothing.
+     */
+    disposition?: string | null;
+};
 /**
  * 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;
+declare function kindSchemaFromJsonSchema(kind: string, jsonSchema: unknown, options?: KindSchemaFromJsonOptions): KindSchemaFromJsonResult;
+
+/**
+ * The four control keys an agent may put beside a kind's values — the TypeScript twin of
+ * `matrx_graph.kind_control_keys.with_control_keys` (aidream). ONE definition, two languages:
+ * for the same input both produce the same JSON (guard W2-G7, the shared golden
+ * `packages/matrx-graph/tests/fixtures/kind_control_keys_golden.json`).
+ *
+ * `_replaces` ("this replaces that output"), `_new` ("this is something new"), `_record_id`
+ * ("change this record") and `_records` ("several records") are never part of a kind and no
+ * registry row carries them — they are added where a schema is USED, for `record` kinds and
+ * table kinds only:
+ *
+ * - `withControlKeys(schema, { mode: "stored" })` — the JSON Schema a value is validated
+ *   against: all four declared optional (nullable), and the root's required Fields lifted when
+ *   the value is a patch (`_record_id`) or a batch (`_records`) — one branch APPENDED to `allOf`,
+ *   never replacing it.
+ * - `withControlKeys(schema, { mode: "authored", many, allowEdit })` — what the model is shown:
+ *   `_replaces`/`_new` always, `_record_id` only with `allowEdit`, and with `many` the root is
+ *   the batch `{__kind, _records: [<record without __kind>], ...}`. Signals are OPTIONAL — the
+ *   provider translators widen them to required-and-nullable on the wire and prune a null back.
+ * - `withControlKeyFields(kindSchema)` — the render-level twin: the four keys as optional
+ *   render fields of a `KindSchema`, so a patch, a batch or a signal is drawn by its kind's
+ *   component instead of being reported as unknown keys. The web schema is never stricter
+ *   than the store.
+ *
+ * Design: common-docs `projects/data-doctrine-adoption/v6/KINDS-GLUE-WAVE2-DESIGN.md` §1.4.
+ */
+
+/** The four keys, in the order they are declared. */
+declare const CONTROL_KEYS: readonly ["_replaces", "_new", "_record_id", "_records"];
+type ControlKey = (typeof CONTROL_KEYS)[number];
+/** The one disposition whose kinds take the control keys (table kinds are always `record`). */
+declare const RECORD_DISPOSITION = "record";
+type ControlKeysMode = "stored" | "authored";
+type WithControlKeysOptions = {
+    mode: ControlKeysMode;
+    /** Authored mode: the root becomes the batch `{__kind, _records: [...]}`. */
+    many?: boolean;
+    /** Authored mode: the model may name `_record_id` (the run may edit its own outputs). */
+    allowEdit?: boolean;
+};
+/** Whether a kind with this disposition takes the control keys. */
+declare function controlKeysApplyTo(disposition: string | null | undefined): boolean;
+/**
+ * A copy of `schema` that carries the control keys for `mode`. A schema that is not an object
+ * with `properties` (a root-form kind, the "any value" `{}`) is returned unchanged.
+ */
+declare function withControlKeys<T>(schema: T, options: WithControlKeysOptions): T;
+/** The render fields the control keys add to a `KindSchema` — all optional, none stricter than the store. */
+declare const CONTROL_KEY_FIELDS: Readonly<Record<ControlKey, FieldSchema>>;
+/**
+ * `schema` with the four control keys as optional render fields. A root-form kind (no field
+ * map) is returned unchanged. Keys the kind itself declares are left as the kind declares them.
+ */
+declare function withControlKeyFields(schema: KindSchema): KindSchema;
+/** Split a value into (values without the control keys, the control keys present). */
+declare function stripControlKeys(value: Record<string, unknown>): {
+    values: Record<string, unknown>;
+    signals: Partial<Record<ControlKey, unknown>>;
+};
 
-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 };
+export { type ArrayItemKindBinding, type BlockSchemaDraft, CONTROL_KEYS, CONTROL_KEY_FIELDS, type ControlKey, type ControlKeysMode, type ConversionProblem, type DroppedMetadata, type FieldComparison, type ItemKindRefCheck, type JsonSchemaNode, type KindJsonSchemaExport, type KindJsonSchemaOptions, type KindSchemaFromJsonOptions, type KindSchemaFromJsonResult, RECORD_DISPOSITION, type SavePlanEntry, type SavePlanValidation, type SchemaConversionResult, type WithControlKeysOptions, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, controlKeysApplyTo, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, stripControlKeys, validateBlockSchemaSavePlan, withControlKeyFields, withControlKeys };

package/dist/convert.js

@@ -423,13 +423,13 @@ function makeKindJsonSchemaProperty(kindSlug, strict) {
   return { ...base, enum: [kindSlug] };
 }
 function injectKindIntoObjectSchema(objectSchema, kindSlug, strict) {
-  const clone = deepClone(objectSchema);
-  const properties = isRecord(clone.properties) ? { ...clone.properties } : {};
+  const clone2 = deepClone(objectSchema);
+  const properties = isRecord(clone2.properties) ? { ...clone2.properties } : {};
   properties[KIND_KEY] = makeKindJsonSchemaProperty(kindSlug, strict);
-  const required = Array.isArray(clone.required) ? clone.required.filter((k) => typeof k === "string") : [];
+  const required = Array.isArray(clone2.required) ? clone2.required.filter((k) => typeof k === "string") : [];
   const nextRequired = required.includes(KIND_KEY) ? required : [KIND_KEY, ...required];
   return {
-    ...clone,
+    ...clone2,
     properties,
     required: nextRequired,
     ...strict ? { additionalProperties: false } : {}
@@ -1626,8 +1626,132 @@ function kindSchemaToJsonSchema(kind, resolve, options = {}) {
   return { name: kind, schema: { ...rootNode, $defs: defs }, strict, unresolved };
 }
 
+// convert/control-keys.ts
+var CONTROL_KEYS = ["_replaces", "_new", "_record_id", "_records"];
+var RECORD_DISPOSITION = "record";
+var KIND_KEY2 = "__kind";
+var DOCUMENT_KEYS = /* @__PURE__ */ new Set(["$schema", "$id", "$defs", "definitions", "title", "description"]);
+var CONTROL = new Set(CONTROL_KEYS);
+function controlKeysApplyTo(disposition) {
+  return disposition === RECORD_DISPOSITION;
+}
+function clone(value) {
+  return value === void 0 ? value : JSON.parse(JSON.stringify(value));
+}
+function isObjectSchema(schema) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return false;
+  const s = schema;
+  return s.type === "object" && !!s.properties && typeof s.properties === "object" && !Array.isArray(s.properties);
+}
+function requiredOf(schema) {
+  return Array.isArray(schema.required) ? schema.required : [];
+}
+function recordObject(schema) {
+  const item = {};
+  for (const [k, v] of Object.entries(schema)) {
+    if (!DOCUMENT_KEYS.has(k)) item[k] = clone(v);
+  }
+  const props = {};
+  for (const [k, v] of Object.entries(item.properties)) {
+    if (k !== KIND_KEY2 && !CONTROL.has(k)) props[k] = v;
+  }
+  item.properties = props;
+  const required = requiredOf(item).filter((k) => k !== KIND_KEY2 && !CONTROL.has(k));
+  if (required.length > 0) item.required = required;
+  else delete item.required;
+  return item;
+}
+function stored(schema) {
+  const out = clone(schema);
+  const item = recordObject(schema);
+  const props = out.properties;
+  props._replaces = { type: ["string", "null"], format: "uuid" };
+  props._new = { type: ["boolean", "null"] };
+  props._record_id = { type: ["string", "null"], format: "uuid" };
+  props._records = { type: ["array", "null"], items: item };
+  const rootRequired = requiredOf(out).filter((k) => !CONTROL.has(k));
+  const lifted = rootRequired.filter((k) => k !== KIND_KEY2);
+  if (lifted.length > 0) {
+    const kept = rootRequired.filter((k) => k === KIND_KEY2);
+    if (kept.length > 0) out.required = kept;
+    else delete out.required;
+    const branch = {
+      if: {
+        anyOf: [
+          { required: ["_record_id"], properties: { _record_id: { type: "string" } } },
+          { required: ["_records"], properties: { _records: { type: "array" } } }
+        ]
+      },
+      else: { required: lifted }
+    };
+    out.allOf = Array.isArray(out.allOf) ? [...out.allOf, branch] : [branch];
+  }
+  return out;
+}
+function authored(schema, many, allowEdit) {
+  const signals = {
+    _replaces: { type: "string", format: "uuid" },
+    _new: { type: "boolean" }
+  };
+  if (allowEdit) signals._record_id = { type: "string", format: "uuid" };
+  if (!many) {
+    const out2 = clone(schema);
+    Object.assign(out2.properties, clone(signals));
+    const required = requiredOf(out2).filter((k) => !CONTROL.has(k));
+    if (required.length > 0 || "required" in out2) out2.required = required;
+    return out2;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(schema)) {
+    if (DOCUMENT_KEYS.has(k)) out[k] = clone(v);
+  }
+  out.type = "object";
+  const kindProp = schema.properties[KIND_KEY2];
+  const properties = {};
+  if (kindProp !== void 0) properties[KIND_KEY2] = clone(kindProp);
+  properties._records = { type: "array", items: recordObject(schema) };
+  Object.assign(properties, clone(signals));
+  out.properties = properties;
+  out.required = [KIND_KEY2, "_records"].filter((k) => k in properties);
+  out.additionalProperties = false;
+  return out;
+}
+function withControlKeys(schema, options) {
+  const { mode, many = false, allowEdit = false } = options;
+  if (mode !== "stored" && mode !== "authored") {
+    throw new Error(`withControlKeys: mode must be "stored" or "authored", got ${String(mode)}`);
+  }
+  if (!isObjectSchema(schema)) return schema;
+  return mode === "stored" ? stored(schema) : authored(schema, many, allowEdit);
+}
+var CONTROL_KEY_FIELDS = Object.freeze({
+  _replaces: { type: "string", nullable: true },
+  _new: { type: "boolean", nullable: true },
+  _record_id: { type: "string", nullable: true },
+  // A batch's items are records of this kind WITHOUT `__kind`; the render layer reads them
+  // as opaque JSON (never stricter than the store, which validates each item).
+  _records: { type: "json[]", nullable: true }
+});
+function withControlKeyFields(schema) {
+  if (schema.root) return schema;
+  const fields = { ...schema.fields };
+  for (const key of CONTROL_KEYS) {
+    if (!(key in fields)) fields[key] = { ...CONTROL_KEY_FIELDS[key] };
+  }
+  return { ...schema, fields };
+}
+function stripControlKeys(value) {
+  const values = {};
+  const signals = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (CONTROL.has(k)) signals[k] = v;
+    else values[k] = v;
+  }
+  return { values, signals };
+}
+
 // convert/json-schema-to-kind.ts
-function kindSchemaFromJsonSchema(kind, jsonSchema) {
+function kindSchemaFromJsonSchema(kind, jsonSchema, options = {}) {
   if (jsonSchema === null || jsonSchema === void 0) {
     return { schema: null, children: {}, problems: [] };
   }
@@ -1658,9 +1782,12 @@ function kindSchemaFromJsonSchema(kind, jsonSchema) {
     if (draft.slug === kind) schema = asKindSchema;
     else children[draft.slug] = asKindSchema;
   }
+  if (schema && controlKeysApplyTo(options.disposition)) {
+    schema = withControlKeyFields(schema);
+  }
   return { schema, children, problems: converted.problems };
 }
 
-export { buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, validateBlockSchemaSavePlan };
+export { CONTROL_KEYS, CONTROL_KEY_FIELDS, RECORD_DISPOSITION, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, controlKeysApplyTo, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, stripControlKeys, validateBlockSchemaSavePlan, withControlKeyFields, withControlKeys };
 //# sourceMappingURL=convert.js.map
 //# sourceMappingURL=convert.js.map