@ai-matrx/agents 0.31.0 → 0.33.0

package/dist/envelope/index.d.ts

@@ -0,0 +1,314 @@
+import { DirectiveClass, buildDirectiveSlug, DecodedDirective } from '@ai-matrx/content-ir';
+
+/**
+ * Matrx reference taxonomy + the directive-apply receipt events.
+ *
+ * 🚨 THE SHELL NO LONGER LIVES HERE. A directive is
+ * `{"__kind":"directive_v1_<class>_<noun>","items":[…]}` and its grammar,
+ * detector and decoder are `@ai-matrx/content-ir/directives` — one shape, one
+ * discriminator, shared with every other kind. What remains in this module is
+ * what is genuinely reference-specific: the reference NOUN taxonomy and the
+ * per-noun item shapes the chips render, plus the typed stream receipts.
+ *
+ * The retired 4-key shell (`matrx_version`/`kind`/`type`/`items`) is READ-ONLY
+ * and understood in exactly one place — `directives/legacyShell.ts`, reachable
+ * only through `decodeDirective`. Nothing here emits it and nothing here
+ * detects it. See docs/protocol/KIND_DIRECTIVES.md.
+ */
+type DirectiveApplyStatus = "applied" | "already_applied" | "failed";
+type DirectiveFault = "agent" | "processor";
+/**
+ * 🚨 EVERY receipt's identity field is `directive` and it carries the SLUG.
+ * There is deliberately no second field and no alias: the slug is the identity,
+ * and a receipt that named the thing differently from the payload it describes
+ * is the exact split the Kind Directives merge closed. Server contract:
+ * aidream `services/output_directives/events.py`.
+ */
+interface DirectiveApplyStarted {
+    kind: "directive_apply.started";
+    directive: string;
+    item_count: number;
+}
+/**
+ * 🚨 THE RECEIPT SENTENCE (DD-118). Every outcome-bearing receipt carries
+ * `message`: ONE sentence, in ordinary words, authored by the SERVER
+ * (`aidream/services/output_directives/receipt_words.py`) from the apply's own
+ * result. A client may never compose it — only the server knows whether the
+ * ledger replayed, what the write-tree touched, or what the handler called it.
+ * Before this field an applied write, a deduped re-send and an unconfirmed
+ * proposal all rendered identically, which is how a user came to see two
+ * identical cards for one project (walk K-1, 2026-09-12).
+ */
+interface DirectiveItemApplied {
+    kind: "directive_apply.item";
+    directive: string;
+    index: number;
+    status: Exclude<DirectiveApplyStatus, "failed">;
+    resource_kind: string;
+    resource_ids: string[];
+    summary: string;
+    /** The server's own sentence for THIS outcome. Render verbatim. */
+    message: string;
+}
+interface DirectiveItemFailed {
+    kind: "directive_apply.failed";
+    directive: string;
+    index: number;
+    error: string;
+    fault: DirectiveFault;
+    /** The server's own sentence: what did not happen, and why. */
+    message: string;
+}
+interface DirectiveApplyCompleted {
+    kind: "directive_apply.completed";
+    directive: string;
+    applied: number;
+    failed: number;
+    /** The server's own closing line for the batch. */
+    message: string;
+}
+/**
+ * A model-emitted directive whose resolved apply policy is `ask` — NOT applied.
+ * The client renders an approve/decline card and, on accept, POSTs `shell`
+ * back to `/directives/confirm`. Idempotent by `proposal_id`. See the backend
+ * cascade: aidream services/output_directives/policy.py + confirm.py.
+ */
+interface DirectiveProposed {
+    kind: "directive_apply.proposed";
+    directive: string;
+    proposal_id: string;
+    item_count: number;
+    /** Display hints DERIVED from the slug — never a second source of identity. */
+    directive_class: string;
+    noun: string;
+    summary: string | null;
+    /** The server's own sentence: what confirming WILL make. Render verbatim. */
+    message: string;
+    /** The two-key shell, POSTed back to /directives/confirm verbatim. */
+    shell: Record<string, unknown>;
+}
+/** A directive suppressed by the cascade (`off`, or `ask` with no human). */
+interface DirectiveApplyBlocked {
+    kind: "directive_apply.blocked";
+    directive: string;
+    reason: string;
+    /** The server's own sentence: nothing was written, and why. */
+    message: string;
+}
+type DirectiveApplyEvent = DirectiveApplyStarted | DirectiveItemApplied | DirectiveItemFailed | DirectiveApplyCompleted | DirectiveProposed | DirectiveApplyBlocked;
+declare function isDirectiveApplyEvent(value: unknown): value is DirectiveApplyEvent;
+declare function isDirectiveProposed(value: unknown): value is DirectiveProposed;
+
+/**
+ * UDT + record reference taxonomy. `dataset_cell` is a legacy alias of `table_cell`.
+ * Record types (`task`, `note`, …) share the backend `RecordRef { id }` item shape.
+ */
+declare const REFERENCE_TYPES: readonly ["structured_list", "structured_list_group", "structured_list_item", "picklist", "picklist_group", "picklist_item", "table", "table_schema", "table_column", "table_row", "table_cell", "task", "note", "project", "agent", "agent_app", "transcript", "transcript_segment", "transcript_session", "session_transcript", "workbook", "workbook_sheet", "document", "document_page", "file", "file_page", "organization", "scope_type", "scope", "context_item", "context_value", "url"];
+type ReferenceType = (typeof REFERENCE_TYPES)[number];
+/**
+ * Display hints — all optional, all non-authoritative (re-fetched live on every
+ * read). Present only for instant paint + offline/LLM readability. `extra="allow"`
+ * on the backend item model is mirrored here by the open-ended index signature so
+ * UI fetch hints (limit / offset / sort) survive a round-trip.
+ */
+interface ReferenceItemHints {
+    label?: string;
+    table_name?: string;
+    list_name?: string;
+    column_display_name?: string;
+    description?: string;
+    [extra: string]: unknown;
+}
+interface PicklistRefItem extends ReferenceItemHints {
+    list_id: string;
+}
+interface PicklistGroupRefItem extends ReferenceItemHints {
+    list_id: string;
+    group_name: string;
+}
+interface PicklistItemRefItem extends ReferenceItemHints {
+    list_id: string;
+    item_id: string;
+}
+interface TableRefItem extends ReferenceItemHints {
+    table_id: string;
+}
+/** Column definitions only — no row payload (`table_schema` / bookmark `table_schema`). */
+interface TableSchemaRefItem extends ReferenceItemHints {
+    table_id: string;
+}
+interface TranscriptSegmentRefItem extends ReferenceItemHints {
+    transcript_id: string;
+    segment_index: string;
+}
+interface SessionTranscriptRefItem extends ReferenceItemHints {
+    session_id: string;
+    transcript_id: string;
+}
+interface WorkbookSheetRefItem extends ReferenceItemHints {
+    workbook_id: string;
+    sheet_id: string;
+}
+interface DocumentPageRefItem extends ReferenceItemHints {
+    document_id: string;
+    page_index: string;
+}
+interface FilePageRefItem extends ReferenceItemHints {
+    file_id: string;
+    page_number: string;
+}
+/** Filled cell at scope × context_item (`ctx_context_item_values`, current row). */
+interface ContextValueRefItem extends ReferenceItemHints {
+    scope_id: string;
+    context_item_id: string;
+}
+interface TableColumnRefItem extends ReferenceItemHints {
+    table_id: string;
+    column_name: string;
+}
+interface TableRowRefItem extends ReferenceItemHints {
+    table_id: string;
+    row_id: string;
+}
+interface TableCellRefItem extends ReferenceItemHints {
+    table_id: string;
+    row_id: string;
+    column_name: string;
+}
+/** Generic id-keyed record (`task`, `note`, `agent`, …). */
+interface RecordRefItem extends ReferenceItemHints {
+    id: string;
+}
+/**
+ * An arbitrary external URL — the one reference type with no Matrx-owned id.
+ * Covers anything not already modeled by a canonical entity type (a public
+ * web page, a third-party doc link, …). Context items that allow `file` for
+ * "our" documents allow `url` alongside it for links we don't own.
+ */
+interface UrlRefItem extends ReferenceItemHints {
+    url: string;
+}
+/**
+ * The canonical reference item — a flat union over the reference taxonomy. Every
+ * member is identity ids + {@link ReferenceItemHints}. The open index signature
+ * keeps it assignable from a generic decoded envelope (`Record<string,unknown>`).
+ */
+type ReferenceItem = PicklistRefItem | PicklistGroupRefItem | PicklistItemRefItem | TableRefItem | TableSchemaRefItem | TableColumnRefItem | TableRowRefItem | TableCellRefItem | TranscriptSegmentRefItem | SessionTranscriptRefItem | WorkbookSheetRefItem | DocumentPageRefItem | FilePageRefItem | ContextValueRefItem | RecordRefItem | UrlRefItem;
+type JsonSchema = Record<string, unknown>;
+/**
+ * Build the strict output_schema (`{ name, schema, strict }`) for a directive
+ * shape: the two-key shell with `__kind` pinned `const` and FIRST, plus `items`
+ * as an array of the provided per-item JSON schema.
+ *
+ * `__kind` first is load-bearing, not cosmetic — the streaming detector types a
+ * JSON document by its first key alone, and a provider that emits the keys in
+ * declaration order is what makes a directive route through the kind pipeline
+ * from its first bytes instead of arriving as raw text and swapping at the end.
+ *
+ * `additionalProperties: false` mirrors the server's `extra="forbid"`: it makes
+ * "everything lives inside items" structurally true, so a stray top-level key
+ * is a hard error and never a silent passthrough. The server owns the canonical
+ * generator (`scripts/generate_kind_directive_registry.py`); this mirrors it for
+ * FE authoring.
+ */
+declare function buildDirectiveOutputSchema(args: {
+    name: string;
+    directiveClass: DirectiveClass;
+    noun: string;
+    itemSchema: JsonSchema;
+    strict?: boolean;
+}): {
+    name: string;
+    strict: boolean;
+    schema: JsonSchema;
+};
+
+/**
+ * Matrx Envelope — reference-fence serializer + reader (the missing authoring
+ * primitive named in the backend handoff).
+ *
+ * ONE in-content encoding for a reference: a ```matrx fence carrying the two-key
+ * Kind Directive shell `{"__kind":"directive_v1_reference_<noun>","items":[…]}`.
+ * This module is the
+ * single FE home for PRODUCING that fence (authoring) and READING it back
+ * (round-trip + display) — used by the picklist variable path today, by table /
+ * secret authoring later. Never hand-assemble a fence string elsewhere.
+ *
+ * `readPicklistSelection` normalizes a stored picklist value (fence string, or a
+ * multi-select array of fence strings + "Other" free text) into `{refs, otherText,
+ * labels}`. The fence is the ONLY encoding — the legacy `picklist_ref` envelope and
+ * its `legacyTranslate.ts` dual-read seam were retired 2026-07-08 after every stored
+ * value was backfilled to fences.
+ */
+
+/**
+ * Serialize a reference directive as the canonical ```matrx fence string
+ * (verbatim-persistable). Items are the FLAT canonical shape typed per the
+ * reference noun (`structured_list_item`, `table_cell`, …).
+ *
+ * THE ONE PLACE THE CLIENT MINTS A FENCE. Every copy-shortcut builder in this
+ * feature funnels here, so the wire shape is decided once: the two-key Kind
+ * Directive shell with `__kind` FIRST, serialized as one minified JSON line
+ * (`{"__kind":"directive_v1_reference_<noun>","items":[…]}`). The retired 4-key
+ * shell is never emitted again — it is only ever READ, by the decoder's shim.
+ *
+ * `type` is passed as a NOUN and the slug is BUILT by the grammar, so a fence
+ * whose slug could not be parsed back is unmintable: an unknown noun throws
+ * here rather than shipping a string nothing can route.
+ */
+declare function buildReferenceFence(args: {
+    type: ReferenceType | string;
+    items: ReferenceItem[];
+}): string;
+/**
+ * The class-generic form of `buildReferenceFence` — same fence, same minified
+ * shell, any grammar class (`reference`, `delete`, …). The slug is still built
+ * by the grammar, so an unroutable class/noun pair throws instead of shipping.
+ * Side-effect classes found in content render as a button and only run on a
+ * human click (KIND_DIRECTIVES.md §4, THE POSITION LAW).
+ */
+declare function buildDirectiveFence(directiveClass: Parameters<typeof buildDirectiveSlug>[0], noun: string, items: ReferenceItem[]): string;
+/**
+ * Convenience builder for a picklist selection: one `picklist_item` reference
+ * fence carrying N FLAT items (`{ list_id, item_id, label? }`). The model
+ * resolves each to the item's hidden description on the wire. There is no
+ * `purpose` / `slot` / `ref` / `display` — intent is decided by position; the
+ * variable-map key the fence is bound to IS the slot.
+ */
+declare function buildPicklistItemFence(args: {
+    listId: string;
+    selections: Array<{
+        itemId: string;
+        label: string;
+    }>;
+}): string;
+/**
+ * Parse the first `reference` directive from a fence string (with or without
+ * the ``` wrapper). Returns `null` when nothing decodes — never throws.
+ */
+declare function parseReferenceFence(value: string): {
+    directive: DecodedDirective;
+    items: ReferenceItem[];
+} | null;
+interface PicklistRefRead {
+    list_id?: string | undefined;
+    item_id: string;
+    label: string;
+}
+interface PicklistSelectionRead {
+    /** Ordered picklist-item refs read from the ```matrx fence(s). */
+    refs: PicklistRefRead[];
+    /** Ordered free-text ("Other") entries that are not picklist items. */
+    otherText: string[];
+    /** `refs` labels, non-empty — convenience for display. */
+    labels: string[];
+}
+/**
+ * Normalize a stored picklist value into `{ refs, otherText, labels }` — a
+ * ```matrx reference fence string, or a multi-select array of fence strings +
+ * "Other" free-text entries. The single read-site every picklist display /
+ * round-trip caller uses.
+ */
+declare function readPicklistSelection(value: unknown): PicklistSelectionRead;
+
+export { type ContextValueRefItem, type DirectiveApplyBlocked, type DirectiveApplyCompleted, type DirectiveApplyEvent, type DirectiveApplyStarted, type DirectiveApplyStatus, type DirectiveFault, type DirectiveItemApplied, type DirectiveItemFailed, type DirectiveProposed, type DocumentPageRefItem, type FilePageRefItem, type PicklistGroupRefItem, type PicklistItemRefItem, type PicklistRefItem, type PicklistRefRead, type PicklistSelectionRead, REFERENCE_TYPES, type RecordRefItem, type ReferenceItem, type ReferenceItemHints, type ReferenceType, type SessionTranscriptRefItem, type TableCellRefItem, type TableColumnRefItem, type TableRefItem, type TableRowRefItem, type TableSchemaRefItem, type TranscriptSegmentRefItem, type UrlRefItem, type WorkbookSheetRefItem, buildDirectiveFence, buildDirectiveOutputSchema, buildPicklistItemFence, buildReferenceFence, isDirectiveApplyEvent, isDirectiveProposed, parseReferenceFence, readPicklistSelection };

package/dist/envelope/index.js

@@ -0,0 +1,192 @@
+// envelope/envelope.ts
+import {
+  KIND_KEY,
+  buildDirectiveSlug
+} from "@ai-matrx/content-ir";
+function isDirectiveApplyEvent(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const k = value.kind;
+  return k === "directive_apply.started" || k === "directive_apply.item" || k === "directive_apply.failed" || k === "directive_apply.completed" || k === "directive_apply.proposed" || k === "directive_apply.blocked";
+}
+function isDirectiveProposed(value) {
+  return typeof value === "object" && value !== null && value.kind === "directive_apply.proposed";
+}
+var REFERENCE_TYPES = [
+  "structured_list",
+  "structured_list_group",
+  "structured_list_item",
+  // Legacy (read-only): pre-rename historical references. NEW content emits the
+  // structured_list* tokens above. See common-docs/projects/structured-lists-rename.
+  "picklist",
+  "picklist_group",
+  "picklist_item",
+  "table",
+  "table_schema",
+  "table_column",
+  "table_row",
+  "table_cell",
+  "task",
+  "note",
+  "project",
+  "agent",
+  "agent_app",
+  "transcript",
+  "transcript_segment",
+  "transcript_session",
+  "session_transcript",
+  "workbook",
+  "workbook_sheet",
+  "document",
+  "document_page",
+  "file",
+  "file_page",
+  "organization",
+  "scope_type",
+  "scope",
+  "context_item",
+  "context_value",
+  "url"
+];
+function buildDirectiveOutputSchema(args) {
+  const { name, directiveClass, noun, itemSchema, strict = false } = args;
+  return {
+    name,
+    strict,
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      required: [KIND_KEY, "items"],
+      properties: {
+        [KIND_KEY]: {
+          type: "string",
+          const: buildDirectiveSlug(directiveClass, noun)
+        },
+        items: { type: "array", items: itemSchema }
+      }
+    }
+  };
+}
+
+// envelope/referenceFence.ts
+import {
+  buildDirectiveSlug as buildDirectiveSlug2,
+  buildKindDirective,
+  tryDecodeDirective
+} from "@ai-matrx/content-ir";
+var FENCE_OPEN = "```matrx";
+var FENCE_CLOSE = "```";
+var matrxFenceRe = () => /```matrx[ \t]*\r?\n([\s\S]*?)\r?\n```/g;
+function tryParseJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function buildReferenceFence(args) {
+  return buildDirectiveFence("reference", args.type, args.items);
+}
+function buildDirectiveFence(directiveClass, noun, items) {
+  const shell = buildKindDirective(
+    buildDirectiveSlug2(directiveClass, noun),
+    items
+  );
+  return `${FENCE_OPEN}
+${JSON.stringify(shell)}
+${FENCE_CLOSE}`;
+}
+function buildPicklistItemFence(args) {
+  const { listId, selections } = args;
+  const items = selections.map((s) => {
+    const item = {
+      list_id: listId,
+      item_id: s.itemId
+    };
+    if (s.label) item.label = s.label;
+    return item;
+  });
+  return buildReferenceFence({ type: "structured_list_item", items });
+}
+function extractDirectives(text) {
+  const out = [];
+  if (!text) return out;
+  if (text.includes(FENCE_OPEN)) {
+    for (const match of text.matchAll(matrxFenceRe())) {
+      const decoded2 = tryDecodeDirective(tryParseJson(match[1] ?? ""));
+      if (decoded2) out.push(decoded2);
+    }
+    return out;
+  }
+  const decoded = tryDecodeDirective(tryParseJson(text.trim()));
+  if (decoded) out.push(decoded);
+  return out;
+}
+function parseReferenceFence(value) {
+  const directive = extractDirectives(value).find(
+    (d) => d.directiveClass === "reference"
+  );
+  if (!directive) return null;
+  return { directive, items: directive.items };
+}
+function refsFromItems(items, into) {
+  if (!Array.isArray(items)) return;
+  for (const raw of items) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const o = raw;
+    const itemId = typeof o.item_id === "string" ? o.item_id : void 0;
+    if (!itemId) continue;
+    const listId = typeof o.list_id === "string" ? o.list_id : void 0;
+    const label = typeof o.label === "string" ? o.label : "";
+    into.push({ list_id: listId, item_id: itemId, label });
+  }
+}
+function finalize(refs, otherText) {
+  return { refs, otherText, labels: refs.map((r) => r.label).filter(Boolean) };
+}
+function readPicklistSelection(value) {
+  const refs = [];
+  const otherText = [];
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      if (typeof entry === "string" && entry.trim()) {
+        const sub = readPicklistSelection(entry);
+        if (sub.refs.length) {
+          refs.push(...sub.refs);
+          otherText.push(...sub.otherText);
+        } else {
+          otherText.push(entry.trim());
+        }
+      }
+    }
+    return finalize(refs, otherText);
+  }
+  if (typeof value === "string" && value.trim()) {
+    const directives = extractDirectives(value);
+    for (const d of directives) {
+      if (d.directiveClass === "reference") refsFromItems(d.items, refs);
+    }
+    if (directives.length === 0) {
+      otherText.push(value.trim());
+    } else {
+      const residual = value.replace(matrxFenceRe(), "").trim();
+      for (const line of residual.split("\n")) {
+        const t = line.trim();
+        if (t) otherText.push(t);
+      }
+    }
+    return finalize(refs, otherText);
+  }
+  return finalize(refs, otherText);
+}
+export {
+  REFERENCE_TYPES,
+  buildDirectiveFence,
+  buildDirectiveOutputSchema,
+  buildPicklistItemFence,
+  buildReferenceFence,
+  isDirectiveApplyEvent,
+  isDirectiveProposed,
+  parseReferenceFence,
+  readPicklistSelection
+};
+//# sourceMappingURL=index.js.map

package/dist/envelope/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../envelope/envelope.ts","../../envelope/referenceFence.ts"],"sourcesContent":["/**\n * Matrx reference taxonomy + the directive-apply receipt events.\n *\n * 🚨 THE SHELL NO LONGER LIVES HERE. A directive is\n * `{\"__kind\":\"directive_v1_<class>_<noun>\",\"items\":[…]}` and its grammar,\n * detector and decoder are `@ai-matrx/content-ir/directives` — one shape, one\n * discriminator, shared with every other kind. What remains in this module is\n * what is genuinely reference-specific: the reference NOUN taxonomy and the\n * per-noun item shapes the chips render, plus the typed stream receipts.\n *\n * The retired 4-key shell (`matrx_version`/`kind`/`type`/`items`) is READ-ONLY\n * and understood in exactly one place — `directives/legacyShell.ts`, reachable\n * only through `decodeDirective`. Nothing here emits it and nothing here\n * detects it. See docs/protocol/KIND_DIRECTIVES.md.\n */\n\n// ── Output-directive receipt events (stream `data` events) ───────────────────\n\nexport type DirectiveApplyStatus = \"applied\" | \"already_applied\" | \"failed\";\nexport type DirectiveFault = \"agent\" | \"processor\";\n\n/**\n * 🚨 EVERY receipt's identity field is `directive` and it carries the SLUG.\n * There is deliberately no second field and no alias: the slug is the identity,\n * and a receipt that named the thing differently from the payload it describes\n * is the exact split the Kind Directives merge closed. Server contract:\n * aidream `services/output_directives/events.py`.\n */\nexport interface DirectiveApplyStarted {\n  kind: \"directive_apply.started\";\n  directive: string;\n  item_count: number;\n}\n/**\n * 🚨 THE RECEIPT SENTENCE (DD-118). Every outcome-bearing receipt carries\n * `message`: ONE sentence, in ordinary words, authored by the SERVER\n * (`aidream/services/output_directives/receipt_words.py`) from the apply's own\n * result. A client may never compose it — only the server knows whether the\n * ledger replayed, what the write-tree touched, or what the handler called it.\n * Before this field an applied write, a deduped re-send and an unconfirmed\n * proposal all rendered identically, which is how a user came to see two\n * identical cards for one project (walk K-1, 2026-09-12).\n */\nexport interface DirectiveItemApplied {\n  kind: \"directive_apply.item\";\n  directive: string;\n  index: number;\n  status: Exclude<DirectiveApplyStatus, \"failed\">;\n  resource_kind: string;\n  resource_ids: string[];\n  summary: string;\n  /** The server's own sentence for THIS outcome. Render verbatim. */\n  message: string;\n}\nexport interface DirectiveItemFailed {\n  kind: \"directive_apply.failed\";\n  directive: string;\n  index: number;\n  error: string;\n  fault: DirectiveFault;\n  /** The server's own sentence: what did not happen, and why. */\n  message: string;\n}\nexport interface DirectiveApplyCompleted {\n  kind: \"directive_apply.completed\";\n  directive: string;\n  applied: number;\n  failed: number;\n  /** The server's own closing line for the batch. */\n  message: string;\n}\n/**\n * A model-emitted directive whose resolved apply policy is `ask` — NOT applied.\n * The client renders an approve/decline card and, on accept, POSTs `shell`\n * back to `/directives/confirm`. Idempotent by `proposal_id`. See the backend\n * cascade: aidream services/output_directives/policy.py + confirm.py.\n */\nexport interface DirectiveProposed {\n  kind: \"directive_apply.proposed\";\n  directive: string;\n  proposal_id: string;\n  item_count: number;\n  /** Display hints DERIVED from the slug — never a second source of identity. */\n  directive_class: string;\n  noun: string;\n  summary: string | null;\n  /** The server's own sentence: what confirming WILL make. Render verbatim. */\n  message: string;\n  /** The two-key shell, POSTed back to /directives/confirm verbatim. */\n  shell: Record<string, unknown>;\n}\n/** A directive suppressed by the cascade (`off`, or `ask` with no human). */\nexport interface DirectiveApplyBlocked {\n  kind: \"directive_apply.blocked\";\n  directive: string;\n  reason: string;\n  /** The server's own sentence: nothing was written, and why. */\n  message: string;\n}\nexport type DirectiveApplyEvent =\n  | DirectiveApplyStarted\n  | DirectiveItemApplied\n  | DirectiveItemFailed\n  | DirectiveApplyCompleted\n  | DirectiveProposed\n  | DirectiveApplyBlocked;\n\nexport function isDirectiveApplyEvent(\n  value: unknown,\n): value is DirectiveApplyEvent {\n  if (typeof value !== \"object\" || value === null) return false;\n  const k = (value as { kind?: unknown }).kind;\n  return (\n    k === \"directive_apply.started\" ||\n    k === \"directive_apply.item\" ||\n    k === \"directive_apply.failed\" ||\n    k === \"directive_apply.completed\" ||\n    k === \"directive_apply.proposed\" ||\n    k === \"directive_apply.blocked\"\n  );\n}\n\nexport function isDirectiveProposed(\n  value: unknown,\n): value is DirectiveProposed {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    (value as { kind?: unknown }).kind === \"directive_apply.proposed\"\n  );\n}\n\nimport {\n  type DirectiveClass,\n  KIND_KEY,\n  buildDirectiveSlug,\n} from \"@ai-matrx/content-ir\";\n\n// ── Reference item (in a ```matrx fence) ─────────────────────────────────────\n//\n// The CANONICAL reference item is PURE FLAT IDENTITY: the typed ids that name\n// the thing + optional, non-authoritative display hints. NOTHING ELSE. There is\n// no `purpose` / `slot` / `ref` / `display` nesting — intent is decided by the\n// item's POSITION (in-content fence = resolve in place; variable binding = the\n// map key is the slot), never a field on the item. (See\n// docs/protocol/MATRX_REFERENCES.md — \"The item shape\" + \"Where purpose went\".)\n\n// (The legacy `purpose` intent field and the `legacyTranslate.ts` translation layer were\n// deleted 2026-07-08 — no stored value carries the old nested/`picklist_ref` shapes anymore;\n// resolution intent is decided by POSITION only.)\n\n/**\n * UDT + record reference taxonomy. `dataset_cell` is a legacy alias of `table_cell`.\n * Record types (`task`, `note`, …) share the backend `RecordRef { id }` item shape.\n */\nexport const REFERENCE_TYPES = [\n  \"structured_list\",\n  \"structured_list_group\",\n  \"structured_list_item\",\n  // Legacy (read-only): pre-rename historical references. NEW content emits the\n  // structured_list* tokens above. See common-docs/projects/structured-lists-rename.\n  \"picklist\",\n  \"picklist_group\",\n  \"picklist_item\",\n  \"table\",\n  \"table_schema\",\n  \"table_column\",\n  \"table_row\",\n  \"table_cell\",\n  \"task\",\n  \"note\",\n  \"project\",\n  \"agent\",\n  \"agent_app\",\n  \"transcript\",\n  \"transcript_segment\",\n  \"transcript_session\",\n  \"session_transcript\",\n  \"workbook\",\n  \"workbook_sheet\",\n  \"document\",\n  \"document_page\",\n  \"file\",\n  \"file_page\",\n  \"organization\",\n  \"scope_type\",\n  \"scope\",\n  \"context_item\",\n  \"context_value\",\n  \"url\",\n] as const;\n\nexport type ReferenceType = (typeof REFERENCE_TYPES)[number];\n\n/**\n * Display hints — all optional, all non-authoritative (re-fetched live on every\n * read). Present only for instant paint + offline/LLM readability. `extra=\"allow\"`\n * on the backend item model is mirrored here by the open-ended index signature so\n * UI fetch hints (limit / offset / sort) survive a round-trip.\n */\nexport interface ReferenceItemHints {\n  label?: string;\n  table_name?: string;\n  list_name?: string;\n  column_display_name?: string;\n  description?: string;\n  [extra: string]: unknown;\n}\n\nexport interface PicklistRefItem extends ReferenceItemHints {\n  list_id: string;\n}\nexport interface PicklistGroupRefItem extends ReferenceItemHints {\n  list_id: string;\n  group_name: string;\n}\nexport interface PicklistItemRefItem extends ReferenceItemHints {\n  list_id: string;\n  item_id: string;\n}\nexport interface TableRefItem extends ReferenceItemHints {\n  table_id: string;\n}\n/** Column definitions only — no row payload (`table_schema` / bookmark `table_schema`). */\nexport interface TableSchemaRefItem extends ReferenceItemHints {\n  table_id: string;\n}\nexport interface TranscriptSegmentRefItem extends ReferenceItemHints {\n  transcript_id: string;\n  segment_index: string;\n}\nexport interface SessionTranscriptRefItem extends ReferenceItemHints {\n  session_id: string;\n  transcript_id: string;\n}\nexport interface WorkbookSheetRefItem extends ReferenceItemHints {\n  workbook_id: string;\n  sheet_id: string;\n}\nexport interface DocumentPageRefItem extends ReferenceItemHints {\n  document_id: string;\n  page_index: string;\n}\nexport interface FilePageRefItem extends ReferenceItemHints {\n  file_id: string;\n  page_number: string;\n}\n/** Filled cell at scope × context_item (`ctx_context_item_values`, current row). */\nexport interface ContextValueRefItem extends ReferenceItemHints {\n  scope_id: string;\n  context_item_id: string;\n}\nexport interface TableColumnRefItem extends ReferenceItemHints {\n  table_id: string;\n  column_name: string;\n}\nexport interface TableRowRefItem extends ReferenceItemHints {\n  table_id: string;\n  row_id: string;\n}\nexport interface TableCellRefItem extends ReferenceItemHints {\n  table_id: string;\n  row_id: string;\n  column_name: string;\n}\n\n/** Generic id-keyed record (`task`, `note`, `agent`, …). */\nexport interface RecordRefItem extends ReferenceItemHints {\n  id: string;\n}\n/**\n * An arbitrary external URL — the one reference type with no Matrx-owned id.\n * Covers anything not already modeled by a canonical entity type (a public\n * web page, a third-party doc link, …). Context items that allow `file` for\n * \"our\" documents allow `url` alongside it for links we don't own.\n */\nexport interface UrlRefItem extends ReferenceItemHints {\n  url: string;\n}\n\n/**\n * The canonical reference item — a flat union over the reference taxonomy. Every\n * member is identity ids + {@link ReferenceItemHints}. The open index signature\n * keeps it assignable from a generic decoded envelope (`Record<string,unknown>`).\n */\nexport type ReferenceItem =\n  | PicklistRefItem\n  | PicklistGroupRefItem\n  | PicklistItemRefItem\n  | TableRefItem\n  | TableSchemaRefItem\n  | TableColumnRefItem\n  | TableRowRefItem\n  | TableCellRefItem\n  | TranscriptSegmentRefItem\n  | SessionTranscriptRefItem\n  | WorkbookSheetRefItem\n  | DocumentPageRefItem\n  | FilePageRefItem\n  | ContextValueRefItem\n  | RecordRefItem\n  | UrlRefItem;\n\n// ── Output-schema builder (generic; mirrors aidream's schema_gen) ─────────────\n\ntype JsonSchema = Record<string, unknown>;\n\n/**\n * Build the strict output_schema (`{ name, schema, strict }`) for a directive\n * shape: the two-key shell with `__kind` pinned `const` and FIRST, plus `items`\n * as an array of the provided per-item JSON schema.\n *\n * `__kind` first is load-bearing, not cosmetic — the streaming detector types a\n * JSON document by its first key alone, and a provider that emits the keys in\n * declaration order is what makes a directive route through the kind pipeline\n * from its first bytes instead of arriving as raw text and swapping at the end.\n *\n * `additionalProperties: false` mirrors the server's `extra=\"forbid\"`: it makes\n * \"everything lives inside items\" structurally true, so a stray top-level key\n * is a hard error and never a silent passthrough. The server owns the canonical\n * generator (`scripts/generate_kind_directive_registry.py`); this mirrors it for\n * FE authoring.\n */\nexport function buildDirectiveOutputSchema(args: {\n  name: string;\n  directiveClass: DirectiveClass;\n  noun: string;\n  itemSchema: JsonSchema;\n  strict?: boolean;\n}): { name: string; strict: boolean; schema: JsonSchema } {\n  const { name, directiveClass, noun, itemSchema, strict = false } = args;\n  return {\n    name,\n    strict,\n    schema: {\n      type: \"object\",\n      additionalProperties: false,\n      required: [KIND_KEY, \"items\"],\n      properties: {\n        [KIND_KEY]: {\n          type: \"string\",\n          const: buildDirectiveSlug(directiveClass, noun),\n        },\n        items: { type: \"array\", items: itemSchema },\n      },\n    },\n  };\n}\n","/**\n * Matrx Envelope — reference-fence serializer + reader (the missing authoring\n * primitive named in the backend handoff).\n *\n * ONE in-content encoding for a reference: a ```matrx fence carrying the two-key\n * Kind Directive shell `{\"__kind\":\"directive_v1_reference_<noun>\",\"items\":[…]}`.\n * This module is the\n * single FE home for PRODUCING that fence (authoring) and READING it back\n * (round-trip + display) — used by the picklist variable path today, by table /\n * secret authoring later. Never hand-assemble a fence string elsewhere.\n *\n * `readPicklistSelection` normalizes a stored picklist value (fence string, or a\n * multi-select array of fence strings + \"Other\" free text) into `{refs, otherText,\n * labels}`. The fence is the ONLY encoding — the legacy `picklist_ref` envelope and\n * its `legacyTranslate.ts` dual-read seam were retired 2026-07-08 after every stored\n * value was backfilled to fences.\n */\n\nimport {\n  type DecodedDirective,\n  buildDirectiveSlug,\n  buildKindDirective,\n  tryDecodeDirective,\n} from \"@ai-matrx/content-ir\";\nimport type {\n  ReferenceItem,\n  ReferenceType,\n} from \"./envelope\";\n\nconst FENCE_OPEN = \"```matrx\";\nconst FENCE_CLOSE = \"```\";\n\n/**\n * Fresh global regex each call — a shared global regex carries `lastIndex`\n * state that would corrupt interleaved `matchAll` / `replace` calls.\n */\nconst matrxFenceRe = (): RegExp => /```matrx[ \\t]*\\r?\\n([\\s\\S]*?)\\r?\\n```/g;\n\nfunction tryParseJson(raw: string): unknown {\n  try {\n    return JSON.parse(raw);\n  } catch {\n    return null;\n  }\n}\n\n// ── Build (authoring) ────────────────────────────────────────────────────────\n\n/**\n * Serialize a reference directive as the canonical ```matrx fence string\n * (verbatim-persistable). Items are the FLAT canonical shape typed per the\n * reference noun (`structured_list_item`, `table_cell`, …).\n *\n * THE ONE PLACE THE CLIENT MINTS A FENCE. Every copy-shortcut builder in this\n * feature funnels here, so the wire shape is decided once: the two-key Kind\n * Directive shell with `__kind` FIRST, serialized as one minified JSON line\n * (`{\"__kind\":\"directive_v1_reference_<noun>\",\"items\":[…]}`). The retired 4-key\n * shell is never emitted again — it is only ever READ, by the decoder's shim.\n *\n * `type` is passed as a NOUN and the slug is BUILT by the grammar, so a fence\n * whose slug could not be parsed back is unmintable: an unknown noun throws\n * here rather than shipping a string nothing can route.\n */\nexport function buildReferenceFence(args: {\n  type: ReferenceType | string;\n  items: ReferenceItem[];\n}): string {\n  return buildDirectiveFence(\"reference\", args.type, args.items);\n}\n\n/**\n * The class-generic form of `buildReferenceFence` — same fence, same minified\n * shell, any grammar class (`reference`, `delete`, …). The slug is still built\n * by the grammar, so an unroutable class/noun pair throws instead of shipping.\n * Side-effect classes found in content render as a button and only run on a\n * human click (KIND_DIRECTIVES.md §4, THE POSITION LAW).\n */\nexport function buildDirectiveFence(\n  directiveClass: Parameters<typeof buildDirectiveSlug>[0],\n  noun: string,\n  items: ReferenceItem[],\n): string {\n  const shell = buildKindDirective(\n    buildDirectiveSlug(directiveClass, noun),\n    items,\n  );\n  return `${FENCE_OPEN}\\n${JSON.stringify(shell)}\\n${FENCE_CLOSE}`;\n}\n\n/**\n * Convenience builder for a picklist selection: one `picklist_item` reference\n * fence carrying N FLAT items (`{ list_id, item_id, label? }`). The model\n * resolves each to the item's hidden description on the wire. There is no\n * `purpose` / `slot` / `ref` / `display` — intent is decided by position; the\n * variable-map key the fence is bound to IS the slot.\n */\nexport function buildPicklistItemFence(args: {\n  listId: string;\n  selections: Array<{ itemId: string; label: string }>;\n}): string {\n  const { listId, selections } = args;\n  const items: ReferenceItem[] = selections.map((s) => {\n    const item: { list_id: string; item_id: string; label?: string } = {\n      list_id: listId,\n      item_id: s.itemId,\n    };\n    if (s.label) item.label = s.label;\n    return item as ReferenceItem;\n  });\n  return buildReferenceFence({ type: \"structured_list_item\", items });\n}\n\n// ── Parse (round-trip) ───────────────────────────────────────────────────────\n\n/**\n * Every Kind Directive embedded in a host string (each ```matrx fence that\n * decodes). Stored 4-key fences decode here too — that is the decoder's shim\n * doing its one job — so a value saved in 2025 reads back identically.\n */\nfunction extractDirectives(text: string): DecodedDirective[] {\n  const out: DecodedDirective[] = [];\n  if (!text) return out;\n\n  if (text.includes(FENCE_OPEN)) {\n    for (const match of text.matchAll(matrxFenceRe())) {\n      const decoded = tryDecodeDirective(tryParseJson(match[1] ?? \"\"));\n      if (decoded) out.push(decoded);\n    }\n    return out;\n  }\n\n  // Tolerant: a bare shell JSON with no fence wrapper.\n  const decoded = tryDecodeDirective(tryParseJson(text.trim()));\n  if (decoded) out.push(decoded);\n  return out;\n}\n\n/**\n * Parse the first `reference` directive from a fence string (with or without\n * the ``` wrapper). Returns `null` when nothing decodes — never throws.\n */\nexport function parseReferenceFence(\n  value: string,\n): { directive: DecodedDirective; items: ReferenceItem[] } | null {\n  const directive = extractDirectives(value).find(\n    (d) => d.directiveClass === \"reference\",\n  );\n  if (!directive) return null;\n  return { directive, items: directive.items as unknown as ReferenceItem[] };\n}\n\n// ── Dual-read (migration bridge) ─────────────────────────────────────────────\n\nexport interface PicklistRefRead {\n  list_id?: string | undefined;\n  item_id: string;\n  label: string;\n}\n\nexport interface PicklistSelectionRead {\n  /** Ordered picklist-item refs read from the ```matrx fence(s). */\n  refs: PicklistRefRead[];\n  /** Ordered free-text (\"Other\") entries that are not picklist items. */\n  otherText: string[];\n  /** `refs` labels, non-empty — convenience for display. */\n  labels: string[];\n}\n\nfunction refsFromItems(items: unknown, into: PicklistRefRead[]): void {\n  if (!Array.isArray(items)) return;\n  for (const raw of items) {\n    if (!raw || typeof raw !== \"object\" || Array.isArray(raw)) continue;\n    const o = raw as Record<string, unknown>;\n    const itemId = typeof o.item_id === \"string\" ? o.item_id : undefined;\n    if (!itemId) continue;\n    const listId = typeof o.list_id === \"string\" ? o.list_id : undefined;\n    const label = typeof o.label === \"string\" ? o.label : \"\";\n    into.push({ list_id: listId, item_id: itemId, label });\n  }\n}\n\nfunction finalize(\n  refs: PicklistRefRead[],\n  otherText: string[],\n): PicklistSelectionRead {\n  return { refs, otherText, labels: refs.map((r) => r.label).filter(Boolean) };\n}\n\n/**\n * Normalize a stored picklist value into `{ refs, otherText, labels }` — a\n * ```matrx reference fence string, or a multi-select array of fence strings +\n * \"Other\" free-text entries. The single read-site every picklist display /\n * round-trip caller uses.\n */\nexport function readPicklistSelection(value: unknown): PicklistSelectionRead {\n  const refs: PicklistRefRead[] = [];\n  const otherText: string[] = [];\n\n  // Multi array: fence-string elements + \"Other\" free-text strings.\n  if (Array.isArray(value)) {\n    for (const entry of value) {\n      if (typeof entry === \"string\" && entry.trim()) {\n        const sub = readPicklistSelection(entry);\n        if (sub.refs.length) {\n          refs.push(...sub.refs);\n          otherText.push(...sub.otherText);\n        } else {\n          otherText.push(entry.trim());\n        }\n      }\n    }\n    return finalize(refs, otherText);\n  }\n\n  // New string form: zero+ ```matrx fences with residual \"Other\" lines, OR pure\n  // free text with no fence.\n  if (typeof value === \"string\" && value.trim()) {\n    const directives = extractDirectives(value);\n    for (const d of directives) {\n      if (d.directiveClass === \"reference\") refsFromItems(d.items, refs);\n    }\n    if (directives.length === 0) {\n      otherText.push(value.trim()); // pure free text — preserve as one entry\n    } else {\n      const residual = value.replace(matrxFenceRe(), \"\").trim();\n      for (const line of residual.split(\"\\n\")) {\n        const t = line.trim();\n        if (t) otherText.push(t);\n      }\n    }\n    return finalize(refs, otherText);\n  }\n\n  return finalize(refs, otherText);\n}\n"],"mappings":";AAoIA;AAAA,EAEE;AAAA,EACA;AAAA,OACK;AA7BA,SAAS,sBACd,OAC8B;AAC9B,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,IAAK,MAA6B;AACxC,SACE,MAAM,6BACN,MAAM,0BACN,MAAM,4BACN,MAAM,+BACN,MAAM,8BACN,MAAM;AAEV;AAEO,SAAS,oBACd,OAC4B;AAC5B,SACE,OAAO,UAAU,YACjB,UAAU,QACT,MAA6B,SAAS;AAE3C;AAyBO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAqIO,SAAS,2BAA2B,MAMe;AACxD,QAAM,EAAE,MAAM,gBAAgB,MAAM,YAAY,SAAS,MAAM,IAAI;AACnE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,QAAQ;AAAA,MACN,MAAM;AAAA,MACN,sBAAsB;AAAA,MACtB,UAAU,CAAC,UAAU,OAAO;AAAA,MAC5B,YAAY;AAAA,QACV,CAAC,QAAQ,GAAG;AAAA,UACV,MAAM;AAAA,UACN,OAAO,mBAAmB,gBAAgB,IAAI;AAAA,QAChD;AAAA,QACA,OAAO,EAAE,MAAM,SAAS,OAAO,WAAW;AAAA,MAC5C;AAAA,IACF;AAAA,EACF;AACF;;;ACzUA;AAAA,EAEE,sBAAAA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAMP,IAAM,aAAa;AACnB,IAAM,cAAc;AAMpB,IAAM,eAAe,MAAc;AAEnC,SAAS,aAAa,KAAsB;AAC1C,MAAI;AACF,WAAO,KAAK,MAAM,GAAG;AAAA,EACvB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAmBO,SAAS,oBAAoB,MAGzB;AACT,SAAO,oBAAoB,aAAa,KAAK,MAAM,KAAK,KAAK;AAC/D;AASO,SAAS,oBACd,gBACA,MACA,OACQ;AACR,QAAM,QAAQ;AAAA,IACZA,oBAAmB,gBAAgB,IAAI;AAAA,IACvC;AAAA,EACF;AACA,SAAO,GAAG,UAAU;AAAA,EAAK,KAAK,UAAU,KAAK,CAAC;AAAA,EAAK,WAAW;AAChE;AASO,SAAS,uBAAuB,MAG5B;AACT,QAAM,EAAE,QAAQ,WAAW,IAAI;AAC/B,QAAM,QAAyB,WAAW,IAAI,CAAC,MAAM;AACnD,UAAM,OAA6D;AAAA,MACjE,SAAS;AAAA,MACT,SAAS,EAAE;AAAA,IACb;AACA,QAAI,EAAE,MAAO,MAAK,QAAQ,EAAE;AAC5B,WAAO;AAAA,EACT,CAAC;AACD,SAAO,oBAAoB,EAAE,MAAM,wBAAwB,MAAM,CAAC;AACpE;AASA,SAAS,kBAAkB,MAAkC;AAC3D,QAAM,MAA0B,CAAC;AACjC,MAAI,CAAC,KAAM,QAAO;AAElB,MAAI,KAAK,SAAS,UAAU,GAAG;AAC7B,eAAW,SAAS,KAAK,SAAS,aAAa,CAAC,GAAG;AACjD,YAAMC,WAAU,mBAAmB,aAAa,MAAM,CAAC,KAAK,EAAE,CAAC;AAC/D,UAAIA,SAAS,KAAI,KAAKA,QAAO;AAAA,IAC/B;AACA,WAAO;AAAA,EACT;AAGA,QAAM,UAAU,mBAAmB,aAAa,KAAK,KAAK,CAAC,CAAC;AAC5D,MAAI,QAAS,KAAI,KAAK,OAAO;AAC7B,SAAO;AACT;AAMO,SAAS,oBACd,OACgE;AAChE,QAAM,YAAY,kBAAkB,KAAK,EAAE;AAAA,IACzC,CAAC,MAAM,EAAE,mBAAmB;AAAA,EAC9B;AACA,MAAI,CAAC,UAAW,QAAO;AACvB,SAAO,EAAE,WAAW,OAAO,UAAU,MAAoC;AAC3E;AAmBA,SAAS,cAAc,OAAgB,MAA+B;AACpE,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG;AAC3B,aAAW,OAAO,OAAO;AACvB,QAAI,CAAC,OAAO,OAAO,QAAQ,YAAY,MAAM,QAAQ,GAAG,EAAG;AAC3D,UAAM,IAAI;AACV,UAAM,SAAS,OAAO,EAAE,YAAY,WAAW,EAAE,UAAU;AAC3D,QAAI,CAAC,OAAQ;AACb,UAAM,SAAS,OAAO,EAAE,YAAY,WAAW,EAAE,UAAU;AAC3D,UAAM,QAAQ,OAAO,EAAE,UAAU,WAAW,EAAE,QAAQ;AACtD,SAAK,KAAK,EAAE,SAAS,QAAQ,SAAS,QAAQ,MAAM,CAAC;AAAA,EACvD;AACF;AAEA,SAAS,SACP,MACA,WACuB;AACvB,SAAO,EAAE,MAAM,WAAW,QAAQ,KAAK,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,OAAO,EAAE;AAC7E;AAQO,SAAS,sBAAsB,OAAuC;AAC3E,QAAM,OAA0B,CAAC;AACjC,QAAM,YAAsB,CAAC;AAG7B,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,eAAW,SAAS,OAAO;AACzB,UAAI,OAAO,UAAU,YAAY,MAAM,KAAK,GAAG;AAC7C,cAAM,MAAM,sBAAsB,KAAK;AACvC,YAAI,IAAI,KAAK,QAAQ;AACnB,eAAK,KAAK,GAAG,IAAI,IAAI;AACrB,oBAAU,KAAK,GAAG,IAAI,SAAS;AAAA,QACjC,OAAO;AACL,oBAAU,KAAK,MAAM,KAAK,CAAC;AAAA,QAC7B;AAAA,MACF;AAAA,IACF;AACA,WAAO,SAAS,MAAM,SAAS;AAAA,EACjC;AAIA,MAAI,OAAO,UAAU,YAAY,MAAM,KAAK,GAAG;AAC7C,UAAM,aAAa,kBAAkB,KAAK;AAC1C,eAAW,KAAK,YAAY;AAC1B,UAAI,EAAE,mBAAmB,YAAa,eAAc,EAAE,OAAO,IAAI;AAAA,IACnE;AACA,QAAI,WAAW,WAAW,GAAG;AAC3B,gBAAU,KAAK,MAAM,KAAK,CAAC;AAAA,IAC7B,OAAO;AACL,YAAM,WAAW,MAAM,QAAQ,aAAa,GAAG,EAAE,EAAE,KAAK;AACxD,iBAAW,QAAQ,SAAS,MAAM,IAAI,GAAG;AACvC,cAAM,IAAI,KAAK,KAAK;AACpB,YAAI,EAAG,WAAU,KAAK,CAAC;AAAA,MACzB;AAAA,IACF;AACA,WAAO,SAAS,MAAM,SAAS;AAAA,EACjC;AAEA,SAAO,SAAS,MAAM,SAAS;AACjC;","names":["buildDirectiveSlug","decoded"]}

package/dist/field-flags/index.cjs

@@ -0,0 +1,63 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// field-flags/index.ts
+var field_flags_exports = {};
+__export(field_flags_exports, {
+  addField: () => addField,
+  assignField: () => assignField,
+  createFieldFlags: () => createFieldFlags,
+  fieldFlagsKeys: () => fieldFlagsKeys,
+  fieldFlagsSize: () => fieldFlagsSize,
+  forEachField: () => forEachField,
+  hasField: () => hasField,
+  readField: () => readField,
+  removeField: () => removeField
+});
+module.exports = __toCommonJS(field_flags_exports);
+function createFieldFlags() {
+  return {};
+}
+function hasField(flags, field) {
+  return flags[field] === true;
+}
+function addField(flags, field) {
+  flags[field] = true;
+}
+function removeField(flags, field) {
+  delete flags[field];
+}
+function fieldFlagsSize(flags) {
+  return Object.keys(flags).length;
+}
+function fieldFlagsKeys(flags) {
+  return Object.keys(flags);
+}
+function forEachField(flags, fn) {
+  for (const key of Object.keys(flags)) {
+    fn(key);
+  }
+}
+function assignField(record, field, value) {
+  record[field] = value;
+}
+function readField(record, field) {
+  return record[field];
+}
+//# sourceMappingURL=index.cjs.map

package/dist/field-flags/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../field-flags/index.ts"],"sourcesContent":["/**\n * FieldFlags — serializable replacement for `Set<keyof T>` used in per-record\n * dirty/loaded tracking across the agent-definition and agent-shortcuts slices.\n *\n * `Set` is not JSON-serializable, which blocks:\n *   - Redux state persistence (localStorage, AsyncStorage)\n *   - Extracting the agent Redux stack into a framework-agnostic shared package\n *   - DevTools time-travel (Sets render as opaque placeholders)\n *\n * Replacement shape: `Partial<Record<K, true>>`. The presence of a key means\n * the flag is set; `true` is the canonical marker. `delete record[key]` clears.\n *\n * Use the helpers below instead of raw object access so the intent at each\n * callsite remains readable (`hasField(flags, \"messages\")` vs `!!flags.messages`).\n */\n\nexport type FieldFlags<K extends string> = Partial<Record<K, true>>;\n\nexport function createFieldFlags<K extends string>(): FieldFlags<K> {\n  return {};\n}\n\nexport function hasField<K extends string>(flags: FieldFlags<K>, field: K): boolean {\n  return flags[field] === true;\n}\n\nexport function addField<K extends string>(flags: FieldFlags<K>, field: K): void {\n  flags[field] = true;\n}\n\nexport function removeField<K extends string>(flags: FieldFlags<K>, field: K): void {\n  delete flags[field];\n}\n\nexport function fieldFlagsSize<K extends string>(flags: FieldFlags<K>): number {\n  return Object.keys(flags).length;\n}\n\nexport function fieldFlagsKeys<K extends string>(flags: FieldFlags<K>): K[] {\n  return Object.keys(flags) as K[];\n}\n\nexport function forEachField<K extends string>(\n  flags: FieldFlags<K>,\n  fn: (field: K) => void,\n): void {\n  for (const key of Object.keys(flags) as K[]) {\n    fn(key);\n  }\n}\n\n/**\n * Assign a single dynamically-keyed field on a record without an `as any`\n * escape hatch. The generic binds `K extends keyof T` and `value: T[K]`\n * together at the call site, so the write stays type-sound — TypeScript\n * just can't prove `record[field] = value` is safe at a *computed* index\n * without this indirection (a known inference gap for mapped-object writes,\n * not an unsoundness).\n */\nexport function assignField<T, K extends keyof T>(\n  record: T,\n  field: K,\n  value: T[K],\n): void {\n  record[field] = value;\n}\n\n/**\n * Read a single dynamically-keyed field off a record without an\n * `as unknown as Record<string, unknown>` whole-row cast. Same generic\n * bridging as `assignField`, for the read direction.\n */\nexport function readField<T, K extends keyof T>(record: T, field: K): T[K] {\n  return record[field];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBO,SAAS,mBAAoD;AAClE,SAAO,CAAC;AACV;AAEO,SAAS,SAA2B,OAAsB,OAAmB;AAClF,SAAO,MAAM,KAAK,MAAM;AAC1B;AAEO,SAAS,SAA2B,OAAsB,OAAgB;AAC/E,QAAM,KAAK,IAAI;AACjB;AAEO,SAAS,YAA8B,OAAsB,OAAgB;AAClF,SAAO,MAAM,KAAK;AACpB;AAEO,SAAS,eAAiC,OAA8B;AAC7E,SAAO,OAAO,KAAK,KAAK,EAAE;AAC5B;AAEO,SAAS,eAAiC,OAA2B;AAC1E,SAAO,OAAO,KAAK,KAAK;AAC1B;AAEO,SAAS,aACd,OACA,IACM;AACN,aAAW,OAAO,OAAO,KAAK,KAAK,GAAU;AAC3C,OAAG,GAAG;AAAA,EACR;AACF;AAUO,SAAS,YACd,QACA,OACA,OACM;AACN,SAAO,KAAK,IAAI;AAClB;AAOO,SAAS,UAAgC,QAAW,OAAgB;AACzE,SAAO,OAAO,KAAK;AACrB;","names":[]}