@ai-matrx/content-ir 0.19.20 → 0.19.25

package/dist/index.d.cts

@@ -4,8 +4,8 @@ export { CompleteValueEnvelopeOptions, CompliantKindSnapshot, ContentRegionInit,
 export { A as ArrayItemScalarType, F as FieldSchema, K as KIND_KEY, a as KindSchema, R as RecordValueType, S as ScalarFieldType, i as isJsonAnyField, b as isScalarArrayType, r as readObjectKind, s as scalarArrayItemType } from './kind-schema.types-CwncWj9U.cjs';
 export { ParseSession, ParseSessionOptions, disposeParseSession, getParseSession, openParseSession } from './session.cjs';
 export { DualGateDefinition, DualGateInput, DualGateResolvedComponent, DualGateResult, Json, KindBlockProps, KindDefinition, KindEdgeSpec, KindStorageError, KindStorageShape, KindTier, KindValidationResult, KindValidator, KindValidatorOptions, LegResult, ROOT_STORAGE_NAME, SchemaSourcePort, SchemaUnavailableReason, StoredFieldElement, createKindValidator, describeDualGateFailure, kindSchemaToStorage, runKindDualGate, storageToKindSchema, validateStructuralLeg } from './registry.cjs';
-export { ArrayItemKindBinding, BlockSchemaDraft, ConversionProblem, DroppedMetadata, FieldComparison, ItemKindRefCheck, JsonSchemaNode, KindJsonSchemaExport, KindJsonSchemaOptions, KindSchemaFromJsonResult, SavePlanEntry, SavePlanValidation, SchemaConversionResult, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, validateBlockSchemaSavePlan } from './convert.cjs';
+export { ArrayItemKindBinding, BlockSchemaDraft, CONTROL_KEYS, CONTROL_KEY_FIELDS, ControlKey, ControlKeysMode, ConversionProblem, DroppedMetadata, FieldComparison, ItemKindRefCheck, JsonSchemaNode, KindJsonSchemaExport, KindJsonSchemaOptions, KindSchemaFromJsonOptions, KindSchemaFromJsonResult, RECORD_DISPOSITION, SavePlanEntry, SavePlanValidation, SchemaConversionResult, WithControlKeysOptions, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, controlKeysApplyTo, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, stripControlKeys, validateBlockSchemaSavePlan, withControlKeyFields, withControlKeys } from './convert.cjs';
 export { AnyPartialKindEvent, IR_PARTIAL_KEY, KindVerdict, NODE_OUTCOME_KIND, NodeOutcomeWrapper, PartialKindEvent, PartialKindNode, PartialKindState, RUN_RESULT_KIND, RetractedKindEvent, RunResultWrapper, SupersededKindEvent, advancePartialKind, emitPayloadFence, emitPayloadJson, isProvisionalKind, isTerminalKindEvent, kindVerdictOf, makePartialKindStalenessGate, readNodeOutcomeValue, readOutputRef, readPartialKindEvent, readRunResultValue, rehydrateNodeOutcome, rehydrateRunResult, sanitizeInboundPartialKindMetadata, withRootKind } from './wire.cjs';
 export { ACTION_BY_CLASS, CAPABILITY_BY_CLASS, CLASSES, DIRECTIVE_VERSION, DecodedDirective, DirectiveCapability, DirectiveClass, DirectiveDecodeError, DirectiveDisplay, DirectiveItemKindLookup, DirectiveItemsEdge, DirectiveNounCatalog, DirectiveNounEntry, DirectiveSlug, IN_CONTENT_CLASSES, ItemFact, KindDirectiveShell, RESERVED_PREFIX, SIDE_EFFECT_CLASSES, SLUG_PREFIX, asKindInstance, buildDirectiveSlug, buildKindDirective, capabilityOf, decodeDirective, directiveDisplay, directiveItemKindFromEdges, directiveSlugOf, executesAtOutputRoot, isDirectiveClass, isKindDirective, isLegacyShell, isReservedDirectiveSlug, itemFacts, itemSubtitle, itemTitle, legacyShellUses, looksLikeDirectiveHead, nounFamily, nounLabel, nounTitleColumn, parseDirectiveSlug, resetLegacyShellUses, resolvesInContent, titleCaseToken, tryDecodeDirective, tryDecodeDirectiveContent } from './directives.cjs';
-export { AFTER_WINDOW, BacktickRuns, BlockIslandType, CALLOUT_NAMES, CodePointIndex, CodeRange, DisturbedIsland, FENCE_OPENER_WHITESPACE, FENCE_WHITESPACE, FenceEnd, FenceLineKind, FenceLines, FenceOpener, FenceReader, InlineIslandType, InnerFenceLine, IslandMeta, IslandType, LinkDefinition, MapOptions, MappedPosition, MappedRange, NESTING_FENCE_LANGUAGES, ReadXmlTag, SourceBlock, SourceBlockKind, SourceChange, SourceEdit, SourceIsland, SourceSpan, SourceSpliceError, SourceSpliceErrorCode, SpliceIntegrity, SpliceOptions, SpliceResult, TokenizeOptions, XmlContainerTracker, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, classifyInnerFenceLine, closeFence, codeSpanText, collectLinkDefinitions, continuesTable, fenceLineKinds, fenceNestsInnerFences, fenceOpenerOf, fenceParts, findCodeRanges, findInlineCodeSpans, findLinkDefinitionLines, findTableEnd, findTableStart, isEscapedBracketMath, isGfmDelimiterRow, isHtmlBlockTagName, isMathPlaceholder, isPipeLedRow, isSingleDollarMath, islandEdit, joinSource, lineIndent, listIslands, looksLikeDisplayMath, looksLikeOpenInlineMath, mapCodeRanges, mapInlineCodeSpans, mapPosition, mapRange, normalizeLinkLabel, opensStrippedHtmlBlock, opensTable, pairDisplayMath, parseFenceOpener, pendingDisplayMathOpener, readXmlTag, resolveReferenceLinks, rowCells, singleDollarAfter, singleDollarMathEnd, spliceSave, splitRowSegments, splitsSurrogatePair, startsHtmlBlock, startsPipelessTable, tableContainerIndent, tableStartsAt, toCodePointOffset, toUtf16Offset, tokenizeSource, trimFenceLine, unescapeCellPipes } from './source.cjs';
+export { AFTER_WINDOW, BacktickRuns, BlockIslandType, CALLOUT_NAMES, CodePointIndex, CodeRange, DisturbedIsland, FENCE_OPENER_WHITESPACE, FENCE_WHITESPACE, FenceEnd, FenceLineKind, FenceLines, FenceOpener, FenceReader, InlineIslandType, InnerFenceLine, IslandMeta, IslandType, LinkDefinition, MapOptions, MappedPosition, MappedRange, NESTING_FENCE_LANGUAGES, ReadXmlTag, SourceBlock, SourceBlockKind, SourceChange, SourceEdit, SourceIsland, SourceSpan, SourceSpliceError, SourceSpliceErrorCode, SpliceIntegrity, SpliceOptions, SpliceResult, TokenizeOptions, XmlContainerTracker, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, classifyInnerFenceLine, closeFence, codeSpanText, collectLinkDefinitions, continuesTable, fenceLineKinds, fenceNestsInnerFences, fenceOpenerOf, fenceParts, findCodeRanges, findInlineCodeSpans, findLinkDefinitionLines, findTableEnd, findTableStart, isEscapedBracketMath, isGfmDelimiterRow, isHtmlBlockTagName, isMathPlaceholder, isPipeLedRow, isSingleDollarMath, islandEdit, joinSource, lineIndent, listIslands, looksLikeDisplayMath, looksLikeOpenInlineMath, mapCodeRanges, mapInlineCodeSpans, mapPosition, mapRange, normalizeLinkLabel, opensStrippedHtmlBlock, opensTable, pairDisplayMath, parseFenceOpener, pendingCodeSpanStart, pendingDisplayMathOpener, readXmlTag, resolveReferenceLinks, rowCells, singleDollarAfter, singleDollarMathEnd, spliceSave, splitRowSegments, splitsSurrogatePair, startsHtmlBlock, startsPipelessTable, tableContainerIndent, tableStartsAt, toCodePointOffset, toUtf16Offset, tokenizeSource, trimFenceLine, unescapeCellPipes } from './source.cjs';
 import 'react';

package/dist/index.d.ts

@@ -4,8 +4,8 @@ export { CompleteValueEnvelopeOptions, CompliantKindSnapshot, ContentRegionInit,
 export { A as ArrayItemScalarType, F as FieldSchema, K as KIND_KEY, a as KindSchema, R as RecordValueType, S as ScalarFieldType, i as isJsonAnyField, b as isScalarArrayType, r as readObjectKind, s as scalarArrayItemType } from './kind-schema.types-CwncWj9U.js';
 export { ParseSession, ParseSessionOptions, disposeParseSession, getParseSession, openParseSession } from './session.js';
 export { DualGateDefinition, DualGateInput, DualGateResolvedComponent, DualGateResult, Json, KindBlockProps, KindDefinition, KindEdgeSpec, KindStorageError, KindStorageShape, KindTier, KindValidationResult, KindValidator, KindValidatorOptions, LegResult, ROOT_STORAGE_NAME, SchemaSourcePort, SchemaUnavailableReason, StoredFieldElement, createKindValidator, describeDualGateFailure, kindSchemaToStorage, runKindDualGate, storageToKindSchema, validateStructuralLeg } from './registry.js';
-export { ArrayItemKindBinding, BlockSchemaDraft, ConversionProblem, DroppedMetadata, FieldComparison, ItemKindRefCheck, JsonSchemaNode, KindJsonSchemaExport, KindJsonSchemaOptions, KindSchemaFromJsonResult, SavePlanEntry, SavePlanValidation, SchemaConversionResult, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, validateBlockSchemaSavePlan } from './convert.js';
+export { ArrayItemKindBinding, BlockSchemaDraft, CONTROL_KEYS, CONTROL_KEY_FIELDS, ControlKey, ControlKeysMode, ConversionProblem, DroppedMetadata, FieldComparison, ItemKindRefCheck, JsonSchemaNode, KindJsonSchemaExport, KindJsonSchemaOptions, KindSchemaFromJsonOptions, KindSchemaFromJsonResult, RECORD_DISPOSITION, SavePlanEntry, SavePlanValidation, SchemaConversionResult, WithControlKeysOptions, buildAgentSchemaWithRenderBlockSupport, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, controlKeysApplyTo, convertAiSchemaToBlockFields, fieldsToDbPayload, injectKindIntoObjectSchema, isDuplicateBlockSlug, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, normalizeAiSchemaInput, runSchemaConversion, stripControlKeys, validateBlockSchemaSavePlan, withControlKeyFields, withControlKeys } from './convert.js';
 export { AnyPartialKindEvent, IR_PARTIAL_KEY, KindVerdict, NODE_OUTCOME_KIND, NodeOutcomeWrapper, PartialKindEvent, PartialKindNode, PartialKindState, RUN_RESULT_KIND, RetractedKindEvent, RunResultWrapper, SupersededKindEvent, advancePartialKind, emitPayloadFence, emitPayloadJson, isProvisionalKind, isTerminalKindEvent, kindVerdictOf, makePartialKindStalenessGate, readNodeOutcomeValue, readOutputRef, readPartialKindEvent, readRunResultValue, rehydrateNodeOutcome, rehydrateRunResult, sanitizeInboundPartialKindMetadata, withRootKind } from './wire.js';
 export { ACTION_BY_CLASS, CAPABILITY_BY_CLASS, CLASSES, DIRECTIVE_VERSION, DecodedDirective, DirectiveCapability, DirectiveClass, DirectiveDecodeError, DirectiveDisplay, DirectiveItemKindLookup, DirectiveItemsEdge, DirectiveNounCatalog, DirectiveNounEntry, DirectiveSlug, IN_CONTENT_CLASSES, ItemFact, KindDirectiveShell, RESERVED_PREFIX, SIDE_EFFECT_CLASSES, SLUG_PREFIX, asKindInstance, buildDirectiveSlug, buildKindDirective, capabilityOf, decodeDirective, directiveDisplay, directiveItemKindFromEdges, directiveSlugOf, executesAtOutputRoot, isDirectiveClass, isKindDirective, isLegacyShell, isReservedDirectiveSlug, itemFacts, itemSubtitle, itemTitle, legacyShellUses, looksLikeDirectiveHead, nounFamily, nounLabel, nounTitleColumn, parseDirectiveSlug, resetLegacyShellUses, resolvesInContent, titleCaseToken, tryDecodeDirective, tryDecodeDirectiveContent } from './directives.js';
-export { AFTER_WINDOW, BacktickRuns, BlockIslandType, CALLOUT_NAMES, CodePointIndex, CodeRange, DisturbedIsland, FENCE_OPENER_WHITESPACE, FENCE_WHITESPACE, FenceEnd, FenceLineKind, FenceLines, FenceOpener, FenceReader, InlineIslandType, InnerFenceLine, IslandMeta, IslandType, LinkDefinition, MapOptions, MappedPosition, MappedRange, NESTING_FENCE_LANGUAGES, ReadXmlTag, SourceBlock, SourceBlockKind, SourceChange, SourceEdit, SourceIsland, SourceSpan, SourceSpliceError, SourceSpliceErrorCode, SpliceIntegrity, SpliceOptions, SpliceResult, TokenizeOptions, XmlContainerTracker, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, classifyInnerFenceLine, closeFence, codeSpanText, collectLinkDefinitions, continuesTable, fenceLineKinds, fenceNestsInnerFences, fenceOpenerOf, fenceParts, findCodeRanges, findInlineCodeSpans, findLinkDefinitionLines, findTableEnd, findTableStart, isEscapedBracketMath, isGfmDelimiterRow, isHtmlBlockTagName, isMathPlaceholder, isPipeLedRow, isSingleDollarMath, islandEdit, joinSource, lineIndent, listIslands, looksLikeDisplayMath, looksLikeOpenInlineMath, mapCodeRanges, mapInlineCodeSpans, mapPosition, mapRange, normalizeLinkLabel, opensStrippedHtmlBlock, opensTable, pairDisplayMath, parseFenceOpener, pendingDisplayMathOpener, readXmlTag, resolveReferenceLinks, rowCells, singleDollarAfter, singleDollarMathEnd, spliceSave, splitRowSegments, splitsSurrogatePair, startsHtmlBlock, startsPipelessTable, tableContainerIndent, tableStartsAt, toCodePointOffset, toUtf16Offset, tokenizeSource, trimFenceLine, unescapeCellPipes } from './source.js';
+export { AFTER_WINDOW, BacktickRuns, BlockIslandType, CALLOUT_NAMES, CodePointIndex, CodeRange, DisturbedIsland, FENCE_OPENER_WHITESPACE, FENCE_WHITESPACE, FenceEnd, FenceLineKind, FenceLines, FenceOpener, FenceReader, InlineIslandType, InnerFenceLine, IslandMeta, IslandType, LinkDefinition, MapOptions, MappedPosition, MappedRange, NESTING_FENCE_LANGUAGES, ReadXmlTag, SourceBlock, SourceBlockKind, SourceChange, SourceEdit, SourceIsland, SourceSpan, SourceSpliceError, SourceSpliceErrorCode, SpliceIntegrity, SpliceOptions, SpliceResult, TokenizeOptions, XmlContainerTracker, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, classifyInnerFenceLine, closeFence, codeSpanText, collectLinkDefinitions, continuesTable, fenceLineKinds, fenceNestsInnerFences, fenceOpenerOf, fenceParts, findCodeRanges, findInlineCodeSpans, findLinkDefinitionLines, findTableEnd, findTableStart, isEscapedBracketMath, isGfmDelimiterRow, isHtmlBlockTagName, isMathPlaceholder, isPipeLedRow, isSingleDollarMath, islandEdit, joinSource, lineIndent, listIslands, looksLikeDisplayMath, looksLikeOpenInlineMath, mapCodeRanges, mapInlineCodeSpans, mapPosition, mapRange, normalizeLinkLabel, opensStrippedHtmlBlock, opensTable, pairDisplayMath, parseFenceOpener, pendingCodeSpanStart, pendingDisplayMathOpener, readXmlTag, resolveReferenceLinks, rowCells, singleDollarAfter, singleDollarMathEnd, spliceSave, splitRowSegments, splitsSurrogatePair, startsHtmlBlock, startsPipelessTable, tableContainerIndent, tableStartsAt, toCodePointOffset, toUtf16Offset, tokenizeSource, trimFenceLine, unescapeCellPipes } from './source.js';
 import 'react';

package/dist/index.js

@@ -1268,7 +1268,7 @@ var KindStreamParser = class {
     }
     if (!declaredKind2 && committedKind && this.speculativeKinds.has(pathKey)) {
       this.speculativeKinds.delete(pathKey);
-      this.finalizeSpeculatedObject(path, objectValue, committedKind, at);
+      this.finalizeSpeculatedObject(path, objectValue, committedKind, at, true);
       return;
     }
     if (path.length === 0 && !declaredKind2 && !committedKind && this.rootSurfaceKind) {
@@ -1346,7 +1346,7 @@ var KindStreamParser = class {
     });
   }
   /** Validate + complete an object typed purely by parent prediction. */
-  finalizeSpeculatedObject(path, objectValue, kind, at) {
+  finalizeSpeculatedObject(path, objectValue, kind, at, requireSharedField = false) {
     const schema = this.lookupSchema(kind);
     if (!schema) {
       this.emitRawObject(
@@ -1359,6 +1359,15 @@ var KindStreamParser = class {
       );
       return;
     }
+    if (requireSharedField && !Object.keys(objectValue).some((key) => key in schema.fields)) {
+      this.emitRawObject(
+        path,
+        objectValue,
+        `Object carries none of "${kind}"'s fields.`,
+        at
+      );
+      return;
+    }
     const outcome = this.validateObjectAgainstSchema(
       { ...objectValue, [KIND_KEY]: kind },
       schema
@@ -1619,16 +1628,7 @@ var KindStreamParser = class {
         ...emptyOutcome
       };
     }
-    for (const [fieldName, fieldSchema] of Object.entries(schema.fields)) {
-      if (fieldSchema.required) {
-        if (!(fieldName in objectValue)) {
-          return {
-            error: `Kind "${schema.kind}" is missing required field "${fieldName}".`,
-            ...emptyOutcome
-          };
-        }
-        continue;
-      }
+    for (const fieldName of Object.keys(schema.fields)) {
       if (!(fieldName in objectValue)) {
         optionalMissing.push(fieldName);
       }
@@ -1835,17 +1835,7 @@ var KindStreamParser = class {
   validateObjectAgainstFields(objectValue, fields) {
     const optionalMissing = [];
     const extraFields = [];
-    const emptyOutcome = { optionalMissing, extraFields };
-    for (const [fieldName, fieldSchema] of Object.entries(fields)) {
-      if (fieldSchema.required) {
-        if (!(fieldName in objectValue)) {
-          return {
-            error: `Inline object is missing required field "${fieldName}".`,
-            ...emptyOutcome
-          };
-        }
-        continue;
-      }
+    for (const fieldName of Object.keys(fields)) {
       if (!(fieldName in objectValue)) {
         optionalMissing.push(fieldName);
       }
@@ -3192,13 +3182,13 @@ function makeKindJsonSchemaProperty(kindSlug, strict) {
   return { ...base2, enum: [kindSlug] };
 }
 function injectKindIntoObjectSchema(objectSchema, kindSlug, strict) {
-  const clone = deepClone(objectSchema);
-  const properties = isRecord4(clone.properties) ? { ...clone.properties } : {};
+  const clone2 = deepClone(objectSchema);
+  const properties = isRecord4(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 } : {}
@@ -4395,8 +4385,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: [] };
   }
@@ -4427,6 +4541,9 @@ 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 };
 }
 
@@ -7931,6 +8048,6 @@ function resolveReferenceLinks(fragment, defs) {
   return resolved.replace(new RegExp(`${PLACEHOLDER}(\\d+)${PLACEHOLDER}`, "g"), (_m, i) => spans[Number(i)] ?? "");
 }
 
-export { ACTION_BY_CLASS, AFTER_WINDOW, BacktickRuns, CALLOUT_NAMES, CAPABILITY_BY_CLASS, CLASSES, DIRECTIVE_VERSION, DirectiveDecodeError, FENCE_OPENER_WHITESPACE, FENCE_WHITESPACE, FenceReader, IN_CONTENT_CLASSES, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, IrTree, JSON_DISCRIMINATOR, JsonStreamTokenizer, KIND_KEY, KindStorageError, KindStreamParser, NESTING_FENCE_LANGUAGES, NODE_OUTCOME_KIND, ParseSession, RESERVED_PREFIX, ROOT_STORAGE_NAME, RUN_RESULT_KIND, SIDE_EFFECT_CLASSES, SLUG_PREFIX, SourceSpliceError, XmlContainerTracker, advancePartialKind, asKindInstance, blockAt, blockEdit, blockRangeEdit, buildAgentSchemaWithRenderBlockSupport, buildCodePointIndex, buildCompliantKindSnapshot, buildDirectiveSlug, buildKindDirective, capabilityOf, classifyInboundEnvelopeMetadata, classifyInnerFenceLine, closeFence, codeSpanText, collectLinkDefinitions, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, continuesTable, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, createKindValidator, decodeDirective, describeDualGateFailure, directiveDisplay, directiveItemKindFromEdges, directiveSlugOf, disposeParseSession, emitPayloadFence, emitPayloadJson, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, executesAtOutputRoot, fenceDiscriminator, fenceLineKinds, fenceNestsInnerFences, fenceOpenerOf, fenceParts, fieldsToDbPayload, findCodeRanges, findInlineCodeSpans, findLinkDefinitionLines, findTableEnd, findTableStart, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDirectiveClass, isDuplicateBlockSlug, isEmptyResidue, isEscapedBracketMath, isGfmDelimiterRow, isHtmlBlockTagName, isIrEnvelopeCache, isJsonAnyField, isKindDirective, isLegacyShell, isMathPlaceholder, isPipeLedRow, isProvisionalKind, isReservedDirectiveSlug, isScalarArrayType, isSingleDollarMath, isTerminalKindEvent, islandEdit, itemFacts, itemSubtitle, itemTitle, joinSource, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, legacyShellUses, lineIndent, listIslands, looksLikeDirectiveHead, looksLikeDisplayMath, looksLikeOpenInlineMath, makePartialKindStalenessGate, mapCodeRanges, mapInlineCodeSpans, mapPosition, mapRange, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, normalizeLinkLabel, nounFamily, nounLabel, nounTitleColumn, openParseSession, opensStrippedHtmlBlock, opensTable, pairDisplayMath, parseDirectiveSlug, parseFenceOpener, pendingDisplayMathOpener, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, readXmlTag, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, resetLegacyShellUses, resolveReferenceLinks, resolvesInContent, reuseEnvelopeIfCurrent, rowCells, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, singleDollarAfter, singleDollarMathEnd, spliceSave, splitRowSegments, splitsSurrogatePair, startsHtmlBlock, startsPipelessTable, storageToKindSchema, stripKindDeep, tableContainerIndent, tableStartsAt, titleCaseToken, toCodePointOffset, toUtf16Offset, tokenizeSource, trimFenceLine, tryDecodeDirective, tryDecodeDirectiveContent, unescapeCellPipes, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };
+export { ACTION_BY_CLASS, AFTER_WINDOW, BacktickRuns, CALLOUT_NAMES, CAPABILITY_BY_CLASS, CLASSES, CONTROL_KEYS, CONTROL_KEY_FIELDS, DIRECTIVE_VERSION, DirectiveDecodeError, FENCE_OPENER_WHITESPACE, FENCE_WHITESPACE, FenceReader, IN_CONTENT_CLASSES, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, IrTree, JSON_DISCRIMINATOR, JsonStreamTokenizer, KIND_KEY, KindStorageError, KindStreamParser, NESTING_FENCE_LANGUAGES, NODE_OUTCOME_KIND, ParseSession, RECORD_DISPOSITION, RESERVED_PREFIX, ROOT_STORAGE_NAME, RUN_RESULT_KIND, SIDE_EFFECT_CLASSES, SLUG_PREFIX, SourceSpliceError, XmlContainerTracker, advancePartialKind, asKindInstance, blockAt, blockEdit, blockRangeEdit, buildAgentSchemaWithRenderBlockSupport, buildCodePointIndex, buildCompliantKindSnapshot, buildDirectiveSlug, buildKindDirective, capabilityOf, classifyInboundEnvelopeMetadata, classifyInnerFenceLine, closeFence, codeSpanText, collectLinkDefinitions, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, continuesTable, controlKeysApplyTo, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, createKindValidator, decodeDirective, describeDualGateFailure, directiveDisplay, directiveItemKindFromEdges, directiveSlugOf, disposeParseSession, emitPayloadFence, emitPayloadJson, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, executesAtOutputRoot, fenceDiscriminator, fenceLineKinds, fenceNestsInnerFences, fenceOpenerOf, fenceParts, fieldsToDbPayload, findCodeRanges, findInlineCodeSpans, findLinkDefinitionLines, findTableEnd, findTableStart, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDirectiveClass, isDuplicateBlockSlug, isEmptyResidue, isEscapedBracketMath, isGfmDelimiterRow, isHtmlBlockTagName, isIrEnvelopeCache, isJsonAnyField, isKindDirective, isLegacyShell, isMathPlaceholder, isPipeLedRow, isProvisionalKind, isReservedDirectiveSlug, isScalarArrayType, isSingleDollarMath, isTerminalKindEvent, islandEdit, itemFacts, itemSubtitle, itemTitle, joinSource, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, legacyShellUses, lineIndent, listIslands, looksLikeDirectiveHead, looksLikeDisplayMath, looksLikeOpenInlineMath, makePartialKindStalenessGate, mapCodeRanges, mapInlineCodeSpans, mapPosition, mapRange, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, normalizeLinkLabel, nounFamily, nounLabel, nounTitleColumn, openParseSession, opensStrippedHtmlBlock, opensTable, pairDisplayMath, parseDirectiveSlug, parseFenceOpener, pendingCodeSpanStart, pendingDisplayMathOpener, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, readXmlTag, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, resetLegacyShellUses, resolveReferenceLinks, resolvesInContent, reuseEnvelopeIfCurrent, rowCells, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, singleDollarAfter, singleDollarMathEnd, spliceSave, splitRowSegments, splitsSurrogatePair, startsHtmlBlock, startsPipelessTable, storageToKindSchema, stripControlKeys, stripKindDeep, tableContainerIndent, tableStartsAt, titleCaseToken, toCodePointOffset, toUtf16Offset, tokenizeSource, trimFenceLine, tryDecodeDirective, tryDecodeDirectiveContent, unescapeCellPipes, validateBlockSchemaSavePlan, validateStructuralLeg, withControlKeyFields, withControlKeys, withRootKind, xmlDiscriminator };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map