@ai-matrx/content-ir 0.10.4 → 0.11.1

package/dist/index.d.cts

@@ -6,4 +6,5 @@ export { ParseSession, ParseSessionOptions, disposeParseSession, getParseSession
 export { DualGateDefinition, DualGateInput, DualGateResolvedComponent, DualGateResult, KindBlockProps, KindDefinition, KindEdgeSpec, KindStorageError, KindStorageShape, KindTier, LegResult, ROOT_STORAGE_NAME, StoredFieldElement, 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 { 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';
 import 'react';

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export { ParseSession, ParseSessionOptions, disposeParseSession, getParseSession
 export { DualGateDefinition, DualGateInput, DualGateResolvedComponent, DualGateResult, KindBlockProps, KindDefinition, KindEdgeSpec, KindStorageError, KindStorageShape, KindTier, LegResult, ROOT_STORAGE_NAME, StoredFieldElement, 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 { 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';
 import 'react';

package/dist/index.js

@@ -4625,6 +4625,348 @@ 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, 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 };
+// directives/grammar.ts
+var RESERVED_PREFIX = "directive_v";
+var DIRECTIVE_VERSION = 1;
+var SLUG_PREFIX = `${RESERVED_PREFIX}${DIRECTIVE_VERSION}_`;
+var CLASSES = [
+  "reference",
+  "view",
+  "create",
+  "update",
+  "delete",
+  "action",
+  "validation",
+  "secret"
+];
+var CAPABILITY_BY_CLASS = {
+  reference: "pure",
+  view: "pure",
+  validation: "pure",
+  secret: "sensitive",
+  create: "side_effect",
+  update: "side_effect",
+  delete: "side_effect",
+  action: "side_effect"
+};
+var SIDE_EFFECT_CLASSES = new Set(
+  CLASSES.filter((c) => CAPABILITY_BY_CLASS[c] === "side_effect")
+);
+var IN_CONTENT_CLASSES = /* @__PURE__ */ new Set([
+  "reference",
+  "secret"
+]);
+function isDirectiveClass(value) {
+  return typeof value === "string" && Object.prototype.hasOwnProperty.call(CAPABILITY_BY_CLASS, value);
+}
+function isReservedDirectiveSlug(slug) {
+  return typeof slug === "string" && slug.startsWith(RESERVED_PREFIX);
+}
+function isToken(value) {
+  return /^[a-z][a-z0-9_]*$/.test(value);
+}
+function buildDirectiveSlug(directiveClass, noun, version = DIRECTIVE_VERSION) {
+  if (!isDirectiveClass(directiveClass)) {
+    throw new Error(
+      `unknown directive class ${JSON.stringify(directiveClass)}; the vocabulary is CLOSED: ${CLASSES.join(", ")}.`
+    );
+  }
+  if (typeof noun !== "string" || !isToken(noun)) {
+    throw new Error(
+      `invalid directive noun ${JSON.stringify(noun)} for class ${JSON.stringify(directiveClass)}: a noun is lowercase [a-z0-9_], starts with a letter, and is non-empty.`
+    );
+  }
+  return `${RESERVED_PREFIX}${version}_${directiveClass}_${noun}`;
+}
+function parseDirectiveSlug(slug) {
+  if (!isReservedDirectiveSlug(slug)) return null;
+  const rest = slug.slice(RESERVED_PREFIX.length);
+  const firstSep = rest.indexOf("_");
+  if (firstSep <= 0) return null;
+  const versionDigits = rest.slice(0, firstSep);
+  if (!/^[0-9]+$/.test(versionDigits)) return null;
+  const remainder = rest.slice(firstSep + 1);
+  const classSep = remainder.indexOf("_");
+  if (classSep <= 0) return null;
+  const directiveClass = remainder.slice(0, classSep);
+  const noun = remainder.slice(classSep + 1);
+  if (!isDirectiveClass(directiveClass) || !isToken(noun)) return null;
+  return {
+    slug,
+    version: Number.parseInt(versionDigits, 10),
+    directiveClass,
+    noun,
+    capability: CAPABILITY_BY_CLASS[directiveClass],
+    executes: executesAtOutputRoot(directiveClass),
+    inContent: resolvesInContent(directiveClass)
+  };
+}
+function capabilityOf(directiveClass) {
+  return CAPABILITY_BY_CLASS[directiveClass];
+}
+function executesAtOutputRoot(directiveClass) {
+  return isDirectiveClass(directiveClass) && SIDE_EFFECT_CLASSES.has(directiveClass);
+}
+function resolvesInContent(directiveClass) {
+  return isDirectiveClass(directiveClass) && IN_CONTENT_CLASSES.has(directiveClass);
+}
+function directiveSlugOf(obj) {
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) return null;
+  const slug = obj[KIND_KEY];
+  return isReservedDirectiveSlug(slug) ? slug : null;
+}
+function isKindDirective(obj) {
+  return directiveSlugOf(obj) !== null;
+}
+function buildKindDirective(slug, items) {
+  return { [KIND_KEY]: slug, items };
+}
+function looksLikeDirectiveHead(content) {
+  const match = content.trimStart().match(/^\{\s*"__kind"\s*:\s*"([^"]*)/);
+  return !!match && isReservedDirectiveSlug(match[1]);
+}
+
+// directives/legacy-shell.ts
+var LEGACY_SENTINEL = "matrx_version";
+var CLASS_BY_LEGACY_KIND = {
+  reference: "reference",
+  secret: "secret",
+  validation: "validation"
+};
+var LEGACY_SIDE_EFFECT_KINDS = /* @__PURE__ */ new Set(["output_directive", "function"]);
+var VERB_NOUN_RE = /^(create|update|delete):([a-z][a-z0-9_]*)$/;
+var USES_SLOT = /* @__PURE__ */ Symbol.for("ai-matrx.content-ir.legacy-shell-uses");
+var uses = globalThis[USES_SLOT] ??= { count: 0 };
+function legacyShellUses() {
+  return uses.count;
+}
+function resetLegacyShellUses() {
+  uses.count = 0;
+}
+function isLegacyShell(obj) {
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) return false;
+  const record = obj;
+  if (!(LEGACY_SENTINEL in record)) return false;
+  const kind = record.kind;
+  return typeof kind === "string" && (kind in CLASS_BY_LEGACY_KIND || LEGACY_SIDE_EFFECT_KINDS.has(kind));
+}
+function slugForLegacy(kind, type) {
+  let directiveClass;
+  let noun;
+  if (LEGACY_SIDE_EFFECT_KINDS.has(kind)) {
+    const match = VERB_NOUN_RE.exec(type);
+    if (match) {
+      directiveClass = match[1];
+      noun = match[2];
+    } else {
+      directiveClass = "action";
+      noun = type;
+    }
+  } else {
+    const mapped = CLASS_BY_LEGACY_KIND[kind];
+    if (!mapped) return null;
+    directiveClass = mapped;
+    noun = type;
+  }
+  try {
+    return buildDirectiveSlug(directiveClass, noun);
+  } catch {
+    return null;
+  }
+}
+function translateLegacyShell(obj) {
+  const kind = obj.kind;
+  const type = obj.type;
+  if (typeof kind !== "string" || typeof type !== "string") return null;
+  const slug = slugForLegacy(kind, type);
+  if (slug === null) return null;
+  const items = obj.items;
+  uses.count += 1;
+  return { [KIND_KEY]: slug, items: Array.isArray(items) ? [...items] : [] };
+}
+
+// directives/decode.ts
+var DirectiveDecodeError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DirectiveDecodeError";
+  }
+};
+function asObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value;
+}
+function decodeDirective(value) {
+  let obj = asObject(value);
+  if (obj === null) return null;
+  let legacy = false;
+  if (isLegacyShell(obj)) {
+    const translated = translateLegacyShell(obj);
+    if (translated === null) {
+      throw new DirectiveDecodeError(
+        `a retired 4-key shell with kind=${JSON.stringify(obj.kind)} type=${JSON.stringify(obj.type)} does not map onto the Kind Directives grammar. Emit the current shell: {"${KIND_KEY}": "directive_v1_<class>_<noun>", "items": [...]}.`
+      );
+    }
+    obj = translated;
+    legacy = true;
+  }
+  const rawSlug = obj[KIND_KEY];
+  if (!isReservedDirectiveSlug(rawSlug)) return null;
+  const parsed = parseDirectiveSlug(rawSlug);
+  if (parsed === null) {
+    throw new DirectiveDecodeError(
+      `malformed directive slug ${JSON.stringify(rawSlug)} \u2014 it claims the reserved "directive_v" namespace but does not parse as directive_v<version>_<class>_<noun>.`
+    );
+  }
+  const rawItems = obj.items;
+  const items = Array.isArray(rawItems) ? rawItems.filter((i) => asObject(i) !== null) : [];
+  return {
+    parsed,
+    slug: parsed.slug,
+    directiveClass: parsed.directiveClass,
+    noun: parsed.noun,
+    items,
+    shell: { [KIND_KEY]: parsed.slug, items },
+    legacyShell: legacy
+  };
+}
+function tryDecodeDirective(value, onError) {
+  try {
+    return decodeDirective(value);
+  } catch (error) {
+    onError?.(error instanceof Error ? error.message : "directive decode failed");
+    return null;
+  }
+}
+function tryDecodeDirectiveContent(content, onError) {
+  if (typeof content !== "string") return tryDecodeDirective(content, onError);
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  return tryDecodeDirective(parsed, onError);
+}
+
+// directives/display.ts
+function titleCaseToken(token) {
+  const words = token.replace(/_/g, " ").trim();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : token;
+}
+var ACTION_BY_CLASS = {
+  reference: "Reference",
+  view: "View",
+  create: "Create",
+  update: "Update",
+  delete: "Delete",
+  action: "Run",
+  validation: "Validate",
+  secret: "Secret"
+};
+function nounLabel(noun, catalog) {
+  const label = catalog?.(noun)?.label;
+  return label && label.length > 0 ? label : titleCaseToken(noun);
+}
+function nounFamily(noun, catalog) {
+  return catalog?.(noun)?.family ?? "";
+}
+function nounTitleColumn(noun, catalog) {
+  return catalog?.(noun)?.titleColumn ?? null;
+}
+function directiveDisplay(directiveClass, noun, catalog) {
+  const label = nounLabel(noun, catalog);
+  const action = ACTION_BY_CLASS[directiveClass];
+  return {
+    noun: label,
+    family: nounFamily(noun, catalog),
+    action,
+    title: `${action} ${label}`
+  };
+}
+
+// directives/item-summary.ts
+var NAME_KEYS = ["name", "title", "label", "heading", "slug", "key", "question", "summary"];
+var FACT_EXCLUDE = /* @__PURE__ */ new Set([
+  "__kind",
+  ...NAME_KEYS,
+  "id",
+  "description",
+  "about",
+  "notes",
+  "content",
+  "text",
+  "body",
+  "organization_id",
+  "user_id",
+  "created_by",
+  "resource_type"
+]);
+function firstString(item, keys) {
+  for (const key of keys) {
+    const value = item[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+function itemTitle(item, titleColumn, index, total) {
+  const fromCatalog = titleColumn ? firstString(item, [titleColumn]) : null;
+  const name = fromCatalog ?? firstString(item, NAME_KEYS);
+  if (name) return name;
+  return total > 1 ? `Item ${index + 1} of ${total}` : "Item";
+}
+function itemSubtitle(item) {
+  return firstString(item, ["description", "about", "summary", "doc"]);
+}
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var FACT_LABEL_OVERRIDES = {
+  variable_definitions: "variables",
+  context_policies: "context",
+  custom_tools: "custom tools"
+};
+function factLabel(key) {
+  return FACT_LABEL_OVERRIDES[key] ?? key.replace(/_/g, " ");
+}
+function itemFacts(item, limit = 4) {
+  const facts = [];
+  for (const [key, value] of Object.entries(item)) {
+    if (facts.length >= limit) break;
+    if (FACT_EXCLUDE.has(key)) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) continue;
+      facts.push({ key, label: factLabel(key), value: String(value.length) });
+      continue;
+    }
+    if (typeof value === "string") {
+      const trimmed = value.trim();
+      if (!trimmed || trimmed.length > 40) continue;
+      if (UUID_RE.test(trimmed)) continue;
+      facts.push({ key, label: factLabel(key), value: trimmed });
+      continue;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+      facts.push({ key, label: factLabel(key), value: String(value) });
+    }
+  }
+  return facts;
+}
+
+// directives/item-kind.ts
+function directiveItemKindFromEdges(edges) {
+  for (const edge of edges ?? []) {
+    const field = edge.field_name ?? edge.fieldPath;
+    const child = edge.child_kind ?? edge.childKind;
+    if (field === "items" && typeof child === "string" && child) return child;
+  }
+  return null;
+}
+function asKindInstance(item, kind) {
+  const existing = item[KIND_KEY];
+  const resolved = typeof existing === "string" && existing ? existing : kind;
+  if (!resolved) return null;
+  return { [KIND_KEY]: resolved, ...item };
+}
+
+export { ACTION_BY_CLASS, CAPABILITY_BY_CLASS, CLASSES, DIRECTIVE_VERSION, DirectiveDecodeError, IN_CONTENT_CLASSES, IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, IrTree, JSON_DISCRIMINATOR, JsonStreamTokenizer, KIND_KEY, KindStorageError, KindStreamParser, NODE_OUTCOME_KIND, ParseSession, RESERVED_PREFIX, ROOT_STORAGE_NAME, RUN_RESULT_KIND, SIDE_EFFECT_CLASSES, SLUG_PREFIX, advancePartialKind, asKindInstance, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, buildDirectiveSlug, buildKindDirective, capabilityOf, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, decodeDirective, describeDualGateFailure, directiveDisplay, directiveItemKindFromEdges, directiveSlugOf, disposeParseSession, emitPayloadFence, emitPayloadJson, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, executesAtOutputRoot, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDirectiveClass, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isKindDirective, isLegacyShell, isProvisionalKind, isReservedDirectiveSlug, isScalarArrayType, isTerminalKindEvent, itemFacts, itemSubtitle, itemTitle, kindSchemaFromJsonSchema, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, legacyShellUses, looksLikeDirectiveHead, makePartialKindStalenessGate, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, nounFamily, nounLabel, nounTitleColumn, openParseSession, parseDirectiveSlug, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, resetLegacyShellUses, resolvesInContent, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, titleCaseToken, tryDecodeDirective, tryDecodeDirectiveContent, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map