@ai-matrx/content-ir 0.19.21 → 0.19.25

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.19.25
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/content-ir-core/v0.19.21..npm/content-ir-core/v0.19.25 -- apps/shared/content-ir-core`).
+No source changes intended and no consumer action required.
+
+## 0.19.24
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/content-ir-core/v0.19.21..npm/content-ir-core/v0.19.24 -- apps/shared/content-ir-core`).
+No source changes intended and no consumer action required.
+
+## 0.19.23
+### Unreleased
+
+- `/convert` **The control keys, one definition in two languages** (KINDS-GLUE wave 2 slice 1a). `withControlKeys(schema, { mode: "stored" | "authored", many, allowEdit })` is the byte-identical twin of aidream's `matrx_graph.kind_control_keys.with_control_keys` (shared golden `packages/matrx-graph/tests/fixtures/kind_control_keys_golden.json`): stored mode declares `_replaces` / `_new` / `_record_id` / `_records` optional and lifts the root's required Fields for a patch or a batch with one appended `allOf` branch; authored mode adds `_replaces`/`_new` always, `_record_id` only with `allowEdit`, and with `many` the root is the batch `{__kind, _records: [...]}`. `withControlKeyFields(kindSchema)` adds the four as optional render fields; `kindSchemaFromJsonSchema(kind, schema, { disposition })` applies it for `record` kinds. Consumer action: pass the registry row's `metadata.disposition` to `kindSchemaFromJsonSchema` (matrx-frontend `schema-source-kind-tables.ts`).
+
+## 0.19.22
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/content-ir-core/v0.19.21..npm/content-ir-core/v0.19.22 -- apps/shared/content-ir-core`).
+No source changes intended and no consumer action required.
+
 ## 0.19.21
 ### Unreleased
 

package/dist/convert.cjs

@@ -425,13 +425,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 } : {}
@@ -1628,8 +1628,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: [] };
   }
@@ -1660,13 +1784,20 @@ 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 };
 }
 
+exports.CONTROL_KEYS = CONTROL_KEYS;
+exports.CONTROL_KEY_FIELDS = CONTROL_KEY_FIELDS;
+exports.RECORD_DISPOSITION = RECORD_DISPOSITION;
 exports.buildAgentSchemaWithRenderBlockSupport = buildAgentSchemaWithRenderBlockSupport;
 exports.collectReferencedKinds = collectReferencedKinds;
 exports.collectSchemaReferencedKinds = collectSchemaReferencedKinds;
 exports.compareWithExistingKindSchema = compareWithExistingKindSchema;
+exports.controlKeysApplyTo = controlKeysApplyTo;
 exports.convertAiSchemaToBlockFields = convertAiSchemaToBlockFields;
 exports.fieldsToDbPayload = fieldsToDbPayload;
 exports.injectKindIntoObjectSchema = injectKindIntoObjectSchema;
@@ -1675,6 +1806,9 @@ exports.kindSchemaFromJsonSchema = kindSchemaFromJsonSchema;
 exports.kindSchemaToJsonSchema = kindSchemaToJsonSchema;
 exports.normalizeAiSchemaInput = normalizeAiSchemaInput;
 exports.runSchemaConversion = runSchemaConversion;
+exports.stripControlKeys = stripControlKeys;
 exports.validateBlockSchemaSavePlan = validateBlockSchemaSavePlan;
+exports.withControlKeyFields = withControlKeyFields;
+exports.withControlKeys = withControlKeys;
 //# sourceMappingURL=convert.cjs.map
 //# sourceMappingURL=convert.cjs.map