@ai-matrx/content-ir 0.10.3 → 0.11.0

package/dist/index.cjs

@@ -4631,6 +4631,354 @@ function emitPayloadFence(kind, value) {
   return "```json\n" + emitPayloadJson(kind, value) + "\n```";
 }
 
+// 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 };
+}
+
+exports.ACTION_BY_CLASS = ACTION_BY_CLASS;
+exports.CAPABILITY_BY_CLASS = CAPABILITY_BY_CLASS;
+exports.CLASSES = CLASSES;
+exports.DIRECTIVE_VERSION = DIRECTIVE_VERSION;
+exports.DirectiveDecodeError = DirectiveDecodeError;
+exports.IN_CONTENT_CLASSES = IN_CONTENT_CLASSES;
 exports.IR_ENVELOPE_CACHE_VERSION = IR_ENVELOPE_CACHE_VERSION;
 exports.IR_ENVELOPE_KEY = IR_ENVELOPE_KEY;
 exports.IR_PARTIAL_KEY = IR_PARTIAL_KEY;
@@ -4643,11 +4991,18 @@ exports.KindStorageError = KindStorageError;
 exports.KindStreamParser = KindStreamParser;
 exports.NODE_OUTCOME_KIND = NODE_OUTCOME_KIND;
 exports.ParseSession = ParseSession;
+exports.RESERVED_PREFIX = RESERVED_PREFIX;
 exports.ROOT_STORAGE_NAME = ROOT_STORAGE_NAME;
 exports.RUN_RESULT_KIND = RUN_RESULT_KIND;
+exports.SIDE_EFFECT_CLASSES = SIDE_EFFECT_CLASSES;
+exports.SLUG_PREFIX = SLUG_PREFIX;
 exports.advancePartialKind = advancePartialKind;
+exports.asKindInstance = asKindInstance;
 exports.buildAgentSchemaWithRenderBlockSupport = buildAgentSchemaWithRenderBlockSupport;
 exports.buildCompliantKindSnapshot = buildCompliantKindSnapshot;
+exports.buildDirectiveSlug = buildDirectiveSlug;
+exports.buildKindDirective = buildKindDirective;
+exports.capabilityOf = capabilityOf;
 exports.classifyInboundEnvelopeMetadata = classifyInboundEnvelopeMetadata;
 exports.collectReferencedKinds = collectReferencedKinds;
 exports.collectSchemaReferencedKinds = collectSchemaReferencedKinds;
@@ -4655,13 +5010,18 @@ exports.compareWithExistingKindSchema = compareWithExistingKindSchema;
 exports.convertAiSchemaToBlockFields = convertAiSchemaToBlockFields;
 exports.createFingerprinter = createFingerprinter;
 exports.createKindStreamParser = createKindStreamParser;
+exports.decodeDirective = decodeDirective;
 exports.describeDualGateFailure = describeDualGateFailure;
+exports.directiveDisplay = directiveDisplay;
+exports.directiveItemKindFromEdges = directiveItemKindFromEdges;
+exports.directiveSlugOf = directiveSlugOf;
 exports.disposeParseSession = disposeParseSession;
 exports.emitPayloadFence = emitPayloadFence;
 exports.emitPayloadJson = emitPayloadJson;
 exports.emptyValueForFieldSchema = emptyValueForFieldSchema;
 exports.envelopeCacheFromEnvelopes = envelopeCacheFromEnvelopes;
 exports.envelopeFromCompleteValue = envelopeFromCompleteValue;
+exports.executesAtOutputRoot = executesAtOutputRoot;
 exports.fenceDiscriminator = fenceDiscriminator;
 exports.fieldsToDbPayload = fieldsToDbPayload;
 exports.fingerprintText = fingerprintText;
@@ -4673,22 +5033,35 @@ exports.irPathKey = irPathKey;
 exports.irPathLabel = irPathLabel;
 exports.irPathsEqual = irPathsEqual;
 exports.isCanonicalBlockIR = isCanonicalBlockIR;
+exports.isDirectiveClass = isDirectiveClass;
 exports.isDuplicateBlockSlug = isDuplicateBlockSlug;
 exports.isEmptyResidue = isEmptyResidue;
 exports.isIrEnvelopeCache = isIrEnvelopeCache;
 exports.isJsonAnyField = isJsonAnyField;
+exports.isKindDirective = isKindDirective;
+exports.isLegacyShell = isLegacyShell;
 exports.isProvisionalKind = isProvisionalKind;
+exports.isReservedDirectiveSlug = isReservedDirectiveSlug;
 exports.isScalarArrayType = isScalarArrayType;
 exports.isTerminalKindEvent = isTerminalKindEvent;
+exports.itemFacts = itemFacts;
+exports.itemSubtitle = itemSubtitle;
+exports.itemTitle = itemTitle;
 exports.kindSchemaFromJsonSchema = kindSchemaFromJsonSchema;
 exports.kindSchemaToJsonSchema = kindSchemaToJsonSchema;
 exports.kindSchemaToStorage = kindSchemaToStorage;
 exports.kindVerdictOf = kindVerdictOf;
+exports.legacyShellUses = legacyShellUses;
+exports.looksLikeDirectiveHead = looksLikeDirectiveHead;
 exports.makePartialKindStalenessGate = makePartialKindStalenessGate;
 exports.mergeResidueIntoValue = mergeResidueIntoValue;
 exports.normalizeAiSchemaInput = normalizeAiSchemaInput;
 exports.normalizeJsonRegion = normalizeJsonRegion;
+exports.nounFamily = nounFamily;
+exports.nounLabel = nounLabel;
+exports.nounTitleColumn = nounTitleColumn;
 exports.openParseSession = openParseSession;
+exports.parseDirectiveSlug = parseDirectiveSlug;
 exports.readEnvelope = readEnvelope;
 exports.readNodeOutcomeValue = readNodeOutcomeValue;
 exports.readObjectKind = readObjectKind;
@@ -4698,6 +5071,8 @@ exports.readRunResultValue = readRunResultValue;
 exports.reconstructRegionValue = reconstructRegionValue;
 exports.rehydrateNodeOutcome = rehydrateNodeOutcome;
 exports.rehydrateRunResult = rehydrateRunResult;
+exports.resetLegacyShellUses = resetLegacyShellUses;
+exports.resolvesInContent = resolvesInContent;
 exports.reuseEnvelopeIfCurrent = reuseEnvelopeIfCurrent;
 exports.runKindDualGate = runKindDualGate;
 exports.runSchemaConversion = runSchemaConversion;
@@ -4709,6 +5084,9 @@ exports.schemaStructureDepth = schemaStructureDepth;
 exports.setJsonRootKeyLookup = setJsonRootKeyLookup;
 exports.storageToKindSchema = storageToKindSchema;
 exports.stripKindDeep = stripKindDeep;
+exports.titleCaseToken = titleCaseToken;
+exports.tryDecodeDirective = tryDecodeDirective;
+exports.tryDecodeDirectiveContent = tryDecodeDirectiveContent;
 exports.validateBlockSchemaSavePlan = validateBlockSchemaSavePlan;
 exports.validateStructuralLeg = validateStructuralLeg;
 exports.withRootKind = withRootKind;