@ai-matrx/alchemy 0.6.2 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.8.1
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/alchemy/v0.6.2..npm/alchemy/v0.8.1 -- apps/shared/alchemy`).
+No source changes intended and no consumer action required.
+
+## 0.8.0 — 2026-09-26
+
+ALC-16: Operate — one engine per format (CONTRACT §1.9 / §2.3).
+
+- `/operate` — THE transfer core, moved here from `@ai-matrx/kit/content-transfer` (capture, projection, drafts, limits, preferences, all-matching, `serialize`, `createBrowserTransport`, the AI envelope). A text payload may carry `language` (Markdown fences it; the download takes its extension). New: `FORMAT_ADAPTERS` / `eligibleFormats` / `formatAdapter` (stable ids, synchronous eligibility, lazy engines), `openPreparation` (capture → draft edits → `seal`, built once per revision/format/options), `sealArtifact` / `isSealed` / `sealDraft`, and `createDelivery` (`copy`, `copyPending` for Safari's promise ClipboardItem, `download`, `send` — each accepts ONLY a sealed artifact; `send` without the write door is refused with a remedy).
+- `/operate/formats/rich-html` — "Copy formatted": print's one Markdown→HTML engine with the inline skin; Google Docs and Word are one action (profiles byte-identical, proven). Plain text of Markdown comes from the same parse (tables as TSV, TeX kept).
+- `/operate/formats/document` — the HTML page (print `documentToHtml`, body allow-listed) and PDF / DOCX / EPUB (print `/document`), loaded lazily.
+- `/operate/formats/xlsx` — the workbook from `rows` (SheetJS, lazy; values never formulas; secret/hidden columns dropped by the engine itself).
+- `/operate/server` — `ServerOperation` registry (`registerServerOperation`, `eligibleServerOperations`); `office.generate` registered, offered only when a `ServerPort` is bound.
+- `/ports` adds the ALC-16 ports `transport`, `assets`, `server`.
+- The package root and `/core` re-export `/operate` instead of kit.
+- New dependencies: `@ai-matrx/print` (lazy), `xlsx` (lazy). `scripts/check-operate-sizes.mjs` enforces gzip limits and that print/SheetJS are never statically bundled.
+
+### Consumer action
+
+None for existing imports (`/core` keeps every function it had; the pre-contract `FormatAdapter` type and the deprecated `renderMarkdownHtml` / `serializeMarkdownRich` remain on `@ai-matrx/kit/content-transfer` until the frontend repoint). New code imports `@ai-matrx/alchemy/operate`.
+
+## 0.7.0 — 2026-09-26
+
+ALC-15: Actions and the one menu engine (CONTRACT §2.4–2.5).
+
+- `/actions` — `createActionRegistry` (duplicate provider or action ids are REFUSED with `DuplicateProviderError` / `DuplicateActionError` naming both providers; a duplicate that only appears at resolve time is dropped and captured, never overwritten), `computeEligibility` (R1: an action that does not apply is absent; only the six universal verbs, category `clipboard`, may answer `unavailable-verb` with a sentence — anything else asking to grey is absent and captured; `writes` absent on read-only targets or targets that do not declare the write target; `requiresAuth` reaches a signed-out person only when the `auth` port can sign in and resume), `createClickTarget` (value keys, writable targets and restriction from the declaration), `createProjectedReads` / `projectValues` (secret, credential, non-exportable and undeclared values never reach a provider; each removal is an omission) and `runAction` (the one run path: sign-in-then-resume, projection, failure capture + a sentence with a remedy).
+- `/menu` — `buildMenuModel` (icon KEYS, translated labels, the category → group table, primary sections first, universal verbs addressed by role), the pure layouts `bar`, `overflow`, `context` (classic · tiered · command), `selectionToolbar`, `sheet`, `palette` + `filterPalette`, `leafIds` (the Lossless-Law proof: every layout's leaf set equals the model's), `withExpandedChildren` for lazy submenus, and `resolveMenuLayout` (person → organization → platform default command/comfortable).
+- A named `section` is one block across categories (it sits in its first action's group and keeps its own row order); `overflow` and the bar's ⋯ fold a long named section under its OWN name ("Save as ▸"), never a coined heading.
+- `/ports` adds the ALC-15 ports: `store`, `notify`, `overlay`, `icons`, `knobs`, `i18n`, `auth`, `dialogs` (all optional; absent = that capability absent).
+- Per-layout React subpaths, each size-limited (`scripts/check-subpath-sizes.mjs`, gzip): `/react/host` (T0: `AlchemyActionsProvider`, `useRegisterActionProvider`, `ActionMenuTrigger` — right-click / long-press; loads `/react/menu` or `/react/sheet` by dynamic import on first open and bundles no model or renderer), `/react/bar` (`ActionBar`), `/react/overflow` (`OverflowMenu`), `/react/menu` (`ContextMenuPanel`), `/react/selection` (`SelectionToolbar`), `/react/sheet` (`ActionSheet`), `/react/palette` (`ActionPalette`).
+
+### Consumer action
+
+None for existing imports. To adopt: mount `AlchemyActionsProvider` once with the host ports (bind `icons` to the host icon resolver), register each action provider with `useRegisterActionProvider`, and render a layout. Tailwind hosts add `@source "../node_modules/@ai-matrx/alchemy/dist"` so the renderers' utility classes are generated.
+
+## 0.6.3 — 2026-09-26
+
+`/checks` adds `findStaleRows(plan, table, existing)` and `mirrorRowKey(row, columns)`: stale mirror rows are judged by the table's full key, so a screen value and an item value that share a name are distinct rows. `SurfaceSyncPlan.keys` names the key of every mirror table the plan owns, including tables it emits no rows for; a `DeclarationExtension` may declare `mirror: { table, conflict }` so its table is keyed even when no declaration contributes a row.
+
+### Consumer action
+
+A host that deletes stale mirror rows should call `findStaleRows` and delete each row filtered by every column of `plan.keys[table]`, instead of keying on `(surface_name, name)`.
+
 ## 0.6.2 — 2026-09-26
 
 `/checks` adds the declaration half of the route check: `findDeadUrlPatterns(declarations, liveRoutes)`, `urlPatternMatchesRoute` and `routeSegments` (a literal pattern segment is never satisfied by a dynamic route segment; a trailing `*` is a prefix). The host supplies its route list.
@@ -177,3 +222,4 @@ Initial `@ai-matrx/alchemy` distribution package. It exports the existing kit co
 
 Wait for the initial npm publish and the required sibling package releases. Then install `@ai-matrx/alchemy` and replace multiple Alchemy package imports with the matching distribution subpath.
 
+

package/dist/actions.cjs

@@ -0,0 +1,374 @@
+"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);
+
+// src/actions.ts
+var actions_exports = {};
+__export(actions_exports, {
+  ACTION_CATEGORIES: () => ACTION_CATEGORIES,
+  DuplicateActionError: () => DuplicateActionError,
+  DuplicateProviderError: () => DuplicateProviderError,
+  UNIVERSAL_VERBS: () => UNIVERSAL_VERBS,
+  alwaysEligible: () => alwaysEligible,
+  computeEligibility: () => computeEligibility,
+  createActionRegistry: () => createActionRegistry,
+  createClickTarget: () => createClickTarget,
+  createProjectedReads: () => createProjectedReads,
+  projectValues: () => projectValues,
+  runAction: () => runAction,
+  staticActionProvider: () => staticActionProvider
+});
+module.exports = __toCommonJS(actions_exports);
+
+// src/actions/click-target.ts
+var UNIVERSAL_VERBS = ["copy", "cut", "paste", "undo", "redo", "find"];
+
+// src/actions/types.ts
+var ACTION_CATEGORIES = [
+  "feedback",
+  "copy",
+  "export",
+  "save",
+  "edit",
+  "share",
+  "creator",
+  "app",
+  "listen",
+  "study",
+  "ask",
+  "ai",
+  "admin",
+  "clipboard",
+  "history",
+  "surface-info"
+];
+
+// src/actions/registry.ts
+var DuplicateActionError = class extends Error {
+  actionId;
+  providers;
+  constructor(actionId, first, second) {
+    super(
+      first === second ? `Action "${actionId}" is yielded twice by provider "${first}". Ids are unique; the second was refused.` : `Action "${actionId}" is registered by provider "${first}" and again by "${second}". Ids are unique; "${second}"'s copy was refused.`
+    );
+    this.name = "DuplicateActionError";
+    this.actionId = actionId;
+    this.providers = [first, second];
+  }
+};
+var DuplicateProviderError = class extends Error {
+  providerId;
+  constructor(providerId) {
+    super(`Action provider "${providerId}" is already registered. Unregister it first; nothing was overwritten.`);
+    this.name = "DuplicateProviderError";
+    this.providerId = providerId;
+  }
+};
+var VERBS = new Set(UNIVERSAL_VERBS);
+function capture(ports, error, detail) {
+  try {
+    ports.diagnostics.capture(error, { area: "actions", detail });
+  } catch {
+  }
+}
+function computeEligibility(action, target, options) {
+  const restrict = options.restrict;
+  if (target.excludedActionIds.has(action.id)) return { status: "absent" };
+  if (restrict?.exclude?.includes(action.id)) return { status: "absent" };
+  if (restrict?.categories && !restrict.categories.includes(action.category)) return { status: "absent" };
+  if (action.writes && action.writes.length > 0) {
+    if (target.readOnly) return { status: "absent" };
+    const writable = new Set(target.writable.map((w) => w.name));
+    if (!action.writes.some((name) => writable.has(name))) return { status: "absent" };
+  }
+  if (action.requiresAuth && !target.auth.authenticated && !options.authResumable) {
+    return { status: "absent" };
+  }
+  const own = action.eligible(target);
+  if (own.status !== "unavailable-verb") return own;
+  if (action.category !== "clipboard" || !VERBS.has(own.verb)) {
+    return {
+      status: "contract-break",
+      reason: `Action "${action.id}" answered unavailable-verb but only the six universal verbs (category "clipboard") may grey; it is absent instead.`
+    };
+  }
+  if (!own.sentence.trim()) {
+    return {
+      status: "contract-break",
+      reason: `Universal verb "${action.id}" greyed without a sentence; a greyed verb must say why.`
+    };
+  }
+  return own;
+}
+function createActionRegistry(options) {
+  const ports = options.ports;
+  const entries = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => {
+    for (const l of [...listeners]) l();
+  };
+  return {
+    register(provider) {
+      if (entries.has(provider.id)) throw new DuplicateProviderError(provider.id);
+      const declared = provider.declaredIds?.() ?? [];
+      const own = /* @__PURE__ */ new Set();
+      for (const id of declared) {
+        if (own.has(id)) throw new DuplicateActionError(id, provider.id, provider.id);
+        own.add(id);
+        for (const [otherId, other] of entries) {
+          if (other.declared.includes(id)) throw new DuplicateActionError(id, otherId, provider.id);
+        }
+      }
+      const entry = { provider, declared };
+      entries.set(provider.id, entry);
+      notify();
+      return () => {
+        if (entries.get(provider.id) === entry) {
+          entries.delete(provider.id);
+          notify();
+        }
+      };
+    },
+    async resolve(target, restrict) {
+      const authResumable = Boolean(ports.auth);
+      const seen = /* @__PURE__ */ new Map();
+      const out = [];
+      for (const [providerId, { provider }] of [...entries]) {
+        let actions;
+        try {
+          actions = await provider.actions(target);
+        } catch (error) {
+          capture(ports, error, { providerId, stage: "actions" });
+          continue;
+        }
+        for (const raw of actions) {
+          const first = seen.get(raw.id);
+          if (first !== void 0) {
+            capture(ports, new DuplicateActionError(raw.id, first, providerId), { actionId: raw.id });
+            continue;
+          }
+          seen.set(raw.id, providerId);
+          const action = raw.provider === providerId ? raw : { ...raw, provider: providerId };
+          let eligibility;
+          try {
+            eligibility = computeEligibility(action, target, { restrict: restrict ?? {}, authResumable });
+          } catch (error) {
+            capture(ports, error, { actionId: action.id, stage: "eligible" });
+            continue;
+          }
+          if (eligibility.status === "contract-break") {
+            capture(ports, new Error(eligibility.reason), { actionId: action.id, stage: "eligible" });
+            continue;
+          }
+          if (eligibility.status === "absent") continue;
+          out.push({ action, eligibility });
+        }
+      }
+      return out;
+    },
+    providers() {
+      return [...entries.keys()];
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+function staticActionProvider(id, actions, tier = "T0") {
+  const list = actions.map((a) => a.provider === id ? a : { ...a, provider: id });
+  return {
+    id,
+    tier,
+    declaredIds: () => list.map((a) => a.id),
+    actions: () => list
+  };
+}
+var alwaysEligible = () => ({ status: "available" });
+
+// src/declare/sensitivity.ts
+var DEFAULT_SENSITIVITY = Object.freeze({
+  exportable: true,
+  classification: "ordinary",
+  includedByDefault: true
+});
+function resolveSensitivity(value) {
+  return {
+    exportable: value.sensitivity?.exportable ?? DEFAULT_SENSITIVITY.exportable,
+    classification: value.sensitivity?.classification ?? DEFAULT_SENSITIVITY.classification,
+    includedByDefault: value.sensitivity?.includedByDefault ?? DEFAULT_SENSITIVITY.includedByDefault
+  };
+}
+
+// src/actions/projection.ts
+function toJson(value) {
+  if (value === void 0 || typeof value === "function" || typeof value === "symbol") return void 0;
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) return value.map((v) => toJson(v) ?? null);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      const j = toJson(v);
+      if (j !== void 0) out[k] = j;
+    }
+    return out;
+  }
+  return void 0;
+}
+function projectValues(raw, declared, pathPrefix = "") {
+  const byName = new Map(declared.map((d) => [d.name, d]));
+  const values = {};
+  const omissions = [];
+  for (const [name, value] of Object.entries(raw)) {
+    const path = pathPrefix ? `${pathPrefix}.${name}` : name;
+    const decl = byName.get(name);
+    if (!decl) {
+      omissions.push({ path, reason: "filtered" });
+      continue;
+    }
+    const sensitivity = resolveSensitivity(decl);
+    if (sensitivity.classification !== "ordinary") {
+      omissions.push({ path, reason: "excluded", classification: sensitivity.classification });
+      continue;
+    }
+    if (!sensitivity.exportable) {
+      omissions.push({ path, reason: "excluded" });
+      continue;
+    }
+    const json = toJson(value);
+    if (json === void 0) continue;
+    values[name] = json;
+  }
+  return { values, omissions };
+}
+function createProjectedReads(source) {
+  return {
+    async values(signal) {
+      if (!source.surface || !source.declaration) return { values: {}, omissions: [] };
+      const raw = await source.surface.readValues(signal);
+      const screenValues = source.declaration.values;
+      return projectValues(raw, screenValues);
+    },
+    async item(signal) {
+      const item = source.item;
+      if (!item || !source.declaration) return null;
+      const type = source.declaration.itemTypes?.find((t) => t.name === item.itemType);
+      if (!type) return { values: {}, omissions: [{ path: item.itemType, reason: "filtered" }] };
+      const raw = await item.readValues(signal);
+      return projectValues(raw, type.values, item.itemType);
+    },
+    async live(signal) {
+      if (!source.surface?.readLive) return {};
+      return source.surface.readLive(signal);
+    }
+  };
+}
+
+// src/declare/keys.ts
+function qualifyValueKey(itemType, name) {
+  return itemType ? `${itemType}.${name}` : name;
+}
+
+// src/actions/target.ts
+function domainOf(surfaceName) {
+  const slash = surfaceName.indexOf("/");
+  return slash > 0 ? surfaceName.slice(0, slash) : surfaceName;
+}
+function createClickTarget(input = {}) {
+  const declaration = input.declaration ?? null;
+  const item = input.item ?? null;
+  const valueKeys = /* @__PURE__ */ new Set();
+  let restricted = false;
+  const writable = [];
+  if (declaration) {
+    for (const value of declaration.values) {
+      valueKeys.add(value.name);
+      const s = resolveSensitivity(value);
+      if (s.classification !== "ordinary" || !s.exportable) restricted = true;
+    }
+    const itemType = item ? declaration.itemTypes?.find((t) => t.name === item.itemType) : void 0;
+    if (itemType) {
+      for (const value of itemType.values) {
+        valueKeys.add(qualifyValueKey(itemType.name, value.name));
+        const s = resolveSensitivity(value);
+        if (s.classification !== "ordinary" || !s.exportable) restricted = true;
+      }
+      for (const t of itemType.writeTargets ?? []) writable.push(t);
+    }
+    for (const t of declaration.writeTargets ?? []) {
+      if (!t.itemType || t.itemType === item?.itemType) writable.push(t);
+    }
+  }
+  const readOnly = input.readOnly ?? item?.readOnly ?? false;
+  const surfaceName = input.surface?.surfaceName ?? declaration?.surfaceName ?? null;
+  const scopeChain = input.scopeChain ?? (surfaceName ? ["global", domainOf(surfaceName), surfaceName] : ["global"]);
+  return {
+    surface: input.surface ?? null,
+    declaration,
+    valueKeys,
+    scopeChain,
+    excludedActionIds: new Set(input.excludedActionIds ?? []),
+    item,
+    level: input.level ?? item?.level ?? null,
+    selection: input.selection ?? null,
+    payloadKinds: input.payloadKinds ?? [],
+    writable: readOnly ? [] : input.writable ?? writable,
+    readOnly,
+    restricted,
+    organizationId: input.organizationId ?? null,
+    auth: {
+      authenticated: input.auth?.authenticated ?? false,
+      admin: input.auth?.admin ?? false,
+      creator: input.auth?.creator ?? false
+    },
+    host: input.host
+  };
+}
+
+// src/actions/run.ts
+async function runAction(action, target, options) {
+  const { ports } = options;
+  if (action.requiresAuth && !target.auth.authenticated) {
+    if (!ports.auth) {
+      ports.diagnostics.capture(new Error(`requiresAuth action "${action.id}" ran signed out with no auth port`), {
+        area: "actions",
+        detail: { actionId: action.id }
+      });
+      return { status: "failed", error: new Error("sign-in unavailable") };
+    }
+    ports.auth.signInThenResume({ actionId: action.id, contentFingerprint: options.contentFingerprint ?? action.id });
+    return { status: "auth-pending" };
+  }
+  const reads = createProjectedReads(options.source ?? { surface: null, declaration: target.declaration, item: null });
+  const signal = options.signal ?? new AbortController().signal;
+  try {
+    const outcome = await action.run(target, { reads, ports, signal });
+    return { status: "ran", outcome };
+  } catch (error) {
+    ports.diagnostics.capture(error, { area: "actions", detail: { actionId: action.id, stage: "run" } });
+    const label = typeof action.label === "string" ? action.label : action.id;
+    ports.notify?.error(`${label} did not finish.`, "Try again; if it keeps failing, report it from the feedback button.");
+    return { status: "failed", error };
+  }
+}
+//# sourceMappingURL=actions.cjs.map

package/dist/actions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/actions.ts","../src/actions/click-target.ts","../src/actions/types.ts","../src/actions/registry.ts","../src/declare/sensitivity.ts","../src/actions/projection.ts","../src/declare/keys.ts","../src/actions/target.ts","../src/actions/run.ts"],"sourcesContent":["/**\n * `@ai-matrx/alchemy/actions` — the one action registry (Matrx Alchemy CONTRACT §2.4).\n * Framework-neutral: zero React, zero `@ai-matrx/agents`.\n */\nexport {\n  ACTION_CATEGORIES,\n  UNIVERSAL_VERBS,\n  type Action,\n  type ActionCategory,\n  type ActionProvider,\n  type ActionRegistry,\n  type ActionRunContext,\n  type ActionSection,\n  type ClickTarget,\n  type Eligibility,\n  type ProjectedReads,\n  type ReadOmission,\n  type ResolveRestriction,\n  type ResolvedAction,\n  type UniversalVerb,\n} from \"./actions/types\";\nexport {\n  DuplicateActionError,\n  DuplicateProviderError,\n  alwaysEligible,\n  computeEligibility,\n  createActionRegistry,\n  staticActionProvider,\n  type ActionRegistryOptions,\n} from \"./actions/registry\";\nexport { createProjectedReads, projectValues, type ProjectionSource } from \"./actions/projection\";\nexport { createClickTarget, type ClickTargetInput } from \"./actions/target\";\nexport { runAction, type RunActionOptions, type RunResult } from \"./actions/run\";\n","/**\n * The click target (CONTRACT §2.4) in its own module: `/ports` references it,\n * and `/ports` must stay free of every other package (types only).\n */\nimport type { QualifiedValueKey, ResolvedItem, ResolvedSurfaceDeclaration, WriteTarget } from \"../declare/types\";\n\n/** The six universal verbs — the ONLY rows that may grey (R1 c). */\nexport const UNIVERSAL_VERBS = [\"copy\", \"cut\", \"paste\", \"undo\", \"redo\", \"find\"] as const;\nexport type UniversalVerb = (typeof UNIVERSAL_VERBS)[number];\n\n/** The transfer Payload's kinds (`actions/types.ts` asserts equality at compile time). */\nexport type PayloadKind = \"text\" | \"markdown\" | \"json\" | \"rows\" | \"registered\";\n\n/** What eligibility is computed from: everything declared at the click target. */\nexport interface ClickTarget {\n  surface: { instanceId: string; surfaceName: string } | null;\n  /** The resolved declaration (inheritance applied). Eligibility decides by KEY existence over it. */\n  declaration: ResolvedSurfaceDeclaration | null;\n  /** Declared value keys with a read path here (screen names + qualified item keys). Key existence, not population. */\n  valueKeys: ReadonlySet<QualifiedValueKey>;\n  /** Scope chain, most general first: [\"global\", \"<domain>\", \"<surfaceName>\"]. */\n  scopeChain: readonly string[];\n  /** The surface's explicit exclusions (the one override). */\n  excludedActionIds: ReadonlySet<string>;\n  item: ResolvedItem | null;\n  level: string | null;\n  /** Offsets + the live range handle, editable or not. */\n  selection: {\n    text: string;\n    type: \"editable\" | \"non-editable\";\n    start: number;\n    end: number;\n    /** Opaque host handle (DOM Range / element) used to restore or stream into the selection. */\n    handle?: unknown;\n  } | null;\n  /** Payload kinds a capture of this target would produce (from declared value types/kinds). */\n  payloadKinds: readonly PayloadKind[];\n  /** Declared targets writable on this target right now. */\n  writable: readonly WriteTarget[];\n  readOnly: boolean;\n  /** True when any declared value here is secret/credential or non-exportable. */\n  restricted: boolean;\n  organizationId: string | null;\n  auth: { authenticated: boolean; admin: boolean; creator: boolean };\n  /**\n   * Host-owned context a provider reads to act (the rich-document source, the\n   * editable field's callbacks). Opaque to the package; never crosses into the\n   * model. Providers that need it narrow it themselves.\n   */\n  host?: unknown;\n}\n\n","/**\n * Matrx Alchemy — Actions types (CONTRACT §2.4).\n *\n * One registry of everything a person can do to a thing. Providers plug in;\n * eligibility is computed from what is declared at the click target; duplicate\n * ids are refused; an action that does not apply is ABSENT (chair ruling R1).\n *\n * Framework-neutral: zero React, zero `@ai-matrx/agents`. Icons are string KEYS\n * resolved by the host's `IconResolverPort`; labels go through `I18nPort`.\n */\nimport type { Payload, TransferOutcome } from \"@ai-matrx/kit/content-transfer\";\nimport type { Json, LiveValues } from \"../declare/types\";\nimport type { AlchemyHostPorts } from \"../ports\";\nimport type { ClickTarget, PayloadKind } from \"./click-target\";\n\nexport type { ClickTarget, PayloadKind } from \"./click-target\";\n\n/** PayloadKind is the transfer Payload's kind union, kept equal at compile time. */\ntype Equal<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;\nconst payloadKindsAgree: Equal<PayloadKind, Payload[\"kind\"]> = true;\nvoid payloadKindsAgree;\n\nexport { UNIVERSAL_VERBS, type UniversalVerb } from \"./click-target\";\nimport type { UniversalVerb } from \"./click-target\";\n\n/**\n * Chair ruling R1: an action that does not apply or cannot run now is ABSENT.\n * Only the six universal verbs may answer \"unavailable-verb\": greyed in the\n * strip/bar, the sentence as tooltip. `requiresAuth` is NOT unavailability.\n */\nexport type Eligibility =\n  | { status: \"absent\" }\n  | { status: \"available\" }\n  | { status: \"unavailable-verb\"; verb: UniversalVerb; sentence: string };\n\n/** rich-document's ActionCategory, unchanged, plus the three the context menu groups by. */\nexport type ActionCategory =\n  | \"feedback\"\n  | \"copy\"\n  | \"export\"\n  | \"save\"\n  | \"edit\"\n  | \"share\"\n  | \"creator\"\n  | \"app\"\n  | \"listen\"\n  | \"study\"\n  | \"ask\"\n  | \"ai\"\n  | \"admin\"\n  | \"clipboard\"\n  | \"history\"\n  | \"surface-info\";\n\nexport const ACTION_CATEGORIES: readonly ActionCategory[] = [\n  \"feedback\",\n  \"copy\",\n  \"export\",\n  \"save\",\n  \"edit\",\n  \"share\",\n  \"creator\",\n  \"app\",\n  \"listen\",\n  \"study\",\n  \"ask\",\n  \"ai\",\n  \"admin\",\n  \"clipboard\",\n  \"history\",\n  \"surface-info\",\n];\n\n/**\n * An optional named section inside the action's group (a grid's cell / row /\n * column). `primary` marks the thing the person clicked: every layout renders\n * it first, inline, heading kept (context-menu-v3's primary section law).\n */\nexport interface ActionSection {\n  id: string;\n  label: string;\n  labelKey?: string;\n  icon?: string;\n  primary?: boolean;\n}\n\nexport interface Action {\n  /** Globally unique. A duplicate is refused (never overwritten). */\n  id: string;\n  /** The provider that registered it — filled by the registry. */\n  provider?: string;\n  /** Resolved through I18nPort.t(labelKey ?? id, label). */\n  label: string | ((target: ClickTarget) => string);\n  labelKey?: string;\n  /** Icon KEY resolved by IconResolverPort — the model stays framework-neutral. */\n  icon?: string;\n  /** Host styling hint for the glyph (rich-document iconColor). Renderers may ignore it. */\n  iconTone?: string;\n  /** Replaces `icon` while a state holds (a spinner while speaking). */\n  stateIcon?(target: ClickTarget): { icon: string; spin?: boolean } | null;\n  hint?: string;\n  hintKey?: string;\n  description?: string;\n  category: ActionCategory;\n  /** Which universal verb this clipboard action is (addressed by role in every layout). */\n  verb?: UniversalVerb;\n  order?: number;\n  /** Bar layout slot. Default \"overflow\". */\n  placement?: \"primary\" | \"overflow\" | \"both\";\n  section?: ActionSection;\n  /** A signed-out person still sees it; running goes through AuthResumePort (sign in, then resume). */\n  requiresAuth?: boolean;\n  /** Declared write targets this action lands through. Absent on a read-only target. */\n  writes?: readonly string[];\n  destructive?: boolean;\n  preserveSelection?: boolean;\n  /** Link rows navigate instead of running. */\n  href?: string | ((target: ClickTarget) => string);\n  eligible(target: ClickTarget): Eligibility;\n  /** Toggle/pressed state: a pressed button or a checked row. */\n  pressed?(target: ClickTarget): boolean;\n  /** Present = the row is a checkbox (pressed is its state). */\n  toggle?: boolean;\n  subscribe?(onChange: () => void, target: ClickTarget): () => void;\n  /** Submenus whose rows load on open (agent lists). */\n  expand?(target: ClickTarget, signal: AbortSignal): Promise<readonly Action[]>;\n  /** Shown centred when `expand` resolves empty. */\n  emptyLabel?: string;\n  run(target: ClickTarget, context: ActionRunContext): Promise<TransferOutcome | void> | TransferOutcome | void;\n}\n\n/** One removed read, recorded (kit content-transfer's omission shape). */\nexport interface ReadOmission {\n  path: string;\n  reason: \"excluded\" | \"filtered\";\n  classification?: \"secret\" | \"credential\";\n}\n\n/**\n * PROJECTION BEFORE PROVIDERS. Providers never receive a raw read. Every read\n * they can make is projected first: secret and credential values, values\n * declared `exportable: false`, and values nobody declared are removed, with an\n * omission recorded. Raw reads never leave the package.\n */\nexport interface ProjectedReads {\n  values(signal: AbortSignal): Promise<{ values: Record<string, Json>; omissions: readonly ReadOmission[] }>;\n  item(signal: AbortSignal): Promise<{ values: Record<string, Json>; omissions: readonly ReadOmission[] } | null>;\n  live(signal: AbortSignal): Promise<LiveValues>;\n}\n\n/**\n * What a running action receives. `door` (ALC-17) and `operate` (ALC-16) join\n * with their waves; until then those capabilities are absent (N8).\n */\nexport interface ActionRunContext {\n  reads: ProjectedReads;\n  ports: AlchemyHostPorts;\n  signal: AbortSignal;\n}\n\nexport interface ActionProvider {\n  id: string;\n  /** T0 providers are known at mount; T1 providers load with the menu on first open. */\n  tier: \"T0\" | \"T1\";\n  /**\n   * The ids this provider can ever yield, when known up front. Lets the\n   * registry refuse a duplicate at registration instead of at first open.\n   */\n  declaredIds?(): readonly string[];\n  actions(target: ClickTarget): readonly Action[] | Promise<readonly Action[]>;\n}\n\nexport interface ResolvedAction {\n  action: Action;\n  eligibility: Exclude<Eligibility, { status: \"absent\" }>;\n}\n\nexport interface ResolveRestriction {\n  exclude?: readonly string[];\n  categories?: readonly ActionCategory[];\n}\n\nexport interface ActionRegistry {\n  /** Throws DuplicateActionError naming both providers; nothing is overwritten. */\n  register(provider: ActionProvider): () => void;\n  /** restrict: a host may remove ids or categories, never add ineligible ones. */\n  resolve(target: ClickTarget, restrict?: ResolveRestriction): Promise<readonly ResolvedAction[]>;\n  /** Registered provider ids, in registration order. */\n  providers(): readonly string[];\n  /** Change notification (a provider registered or unregistered). */\n  subscribe(listener: () => void): () => void;\n}\n","/**\n * The one action registry (CONTRACT §2.4).\n *\n * - Duplicate ids are REFUSED, never overwritten (rich-document's registry\n *   silently overwrote — R12). A duplicate known at registration throws; one\n *   that only appears when a provider yields it is dropped and captured.\n * - Eligibility is one pure pass over the resolved click target, under\n *   \"restrict, never relax\": a host may remove ids or categories, never add.\n * - R1: an action that does not apply is ABSENT. Only the six universal verbs\n *   (category \"clipboard\") may answer `unavailable-verb`, with a sentence; any\n *   other action answering it is a contract break → absent + diagnostics.\n */\nimport type { AlchemyHostPorts, Json } from \"../ports\";\nimport {\n  UNIVERSAL_VERBS,\n  type Action,\n  type ActionProvider,\n  type ActionRegistry,\n  type ClickTarget,\n  type Eligibility,\n  type ResolveRestriction,\n  type ResolvedAction,\n} from \"./types\";\n\nexport class DuplicateActionError extends Error {\n  readonly actionId: string;\n  readonly providers: readonly [string, string];\n  constructor(actionId: string, first: string, second: string) {\n    super(\n      first === second\n        ? `Action \"${actionId}\" is yielded twice by provider \"${first}\". Ids are unique; the second was refused.`\n        : `Action \"${actionId}\" is registered by provider \"${first}\" and again by \"${second}\". Ids are unique; \"${second}\"'s copy was refused.`,\n    );\n    this.name = \"DuplicateActionError\";\n    this.actionId = actionId;\n    this.providers = [first, second];\n  }\n}\n\nexport class DuplicateProviderError extends Error {\n  readonly providerId: string;\n  constructor(providerId: string) {\n    super(`Action provider \"${providerId}\" is already registered. Unregister it first; nothing was overwritten.`);\n    this.name = \"DuplicateProviderError\";\n    this.providerId = providerId;\n  }\n}\n\nexport interface ActionRegistryOptions {\n  /** `diagnostics` is required (nothing fails silently); `auth` decides whether requiresAuth actions reach a signed-out person. */\n  ports: Pick<AlchemyHostPorts, \"diagnostics\" | \"auth\">;\n}\n\nconst VERBS = new Set<string>(UNIVERSAL_VERBS);\n\nfunction capture(ports: ActionRegistryOptions[\"ports\"], error: unknown, detail: Json): void {\n  try {\n    ports.diagnostics.capture(error, { area: \"actions\", detail });\n  } catch {\n    // A broken diagnostics port must never take the menu down with it.\n  }\n}\n\n/**\n * Eligibility of one action at one target — the ONE pure pass (CONTRACT §1.6).\n * Exported for providers' tests; hosts call `registry.resolve`.\n */\nexport function computeEligibility(\n  action: Action,\n  target: ClickTarget,\n  options: { restrict?: ResolveRestriction; authResumable: boolean },\n): Eligibility | { status: \"contract-break\"; reason: string } {\n  const restrict = options.restrict;\n  if (target.excludedActionIds.has(action.id)) return { status: \"absent\" };\n  if (restrict?.exclude?.includes(action.id)) return { status: \"absent\" };\n  if (restrict?.categories && !restrict.categories.includes(action.category)) return { status: \"absent\" };\n  if (action.writes && action.writes.length > 0) {\n    // A read-only target offers nothing that would change the record.\n    if (target.readOnly) return { status: \"absent\" };\n    const writable = new Set(target.writable.map((w) => w.name));\n    if (!action.writes.some((name) => writable.has(name))) return { status: \"absent\" };\n  }\n  if (action.requiresAuth && !target.auth.authenticated && !options.authResumable) {\n    // Sign-in-then-resume is the capability; without the auth port it is absent (N8).\n    return { status: \"absent\" };\n  }\n  const own = action.eligible(target);\n  if (own.status !== \"unavailable-verb\") return own;\n  if (action.category !== \"clipboard\" || !VERBS.has(own.verb)) {\n    return {\n      status: \"contract-break\",\n      reason: `Action \"${action.id}\" answered unavailable-verb but only the six universal verbs (category \"clipboard\") may grey; it is absent instead.`,\n    };\n  }\n  if (!own.sentence.trim()) {\n    return {\n      status: \"contract-break\",\n      reason: `Universal verb \"${action.id}\" greyed without a sentence; a greyed verb must say why.`,\n    };\n  }\n  return own;\n}\n\ninterface Entry {\n  provider: ActionProvider;\n  declared: readonly string[];\n}\n\nexport function createActionRegistry(options: ActionRegistryOptions): ActionRegistry {\n  const ports = options.ports;\n  const entries = new Map<string, Entry>();\n  const listeners = new Set<() => void>();\n  const notify = () => {\n    for (const l of [...listeners]) l();\n  };\n\n  return {\n    register(provider) {\n      if (entries.has(provider.id)) throw new DuplicateProviderError(provider.id);\n      const declared = provider.declaredIds?.() ?? [];\n      const own = new Set<string>();\n      for (const id of declared) {\n        if (own.has(id)) throw new DuplicateActionError(id, provider.id, provider.id);\n        own.add(id);\n        for (const [otherId, other] of entries) {\n          if (other.declared.includes(id)) throw new DuplicateActionError(id, otherId, provider.id);\n        }\n      }\n      const entry: Entry = { provider, declared };\n      entries.set(provider.id, entry);\n      notify();\n      return () => {\n        if (entries.get(provider.id) === entry) {\n          entries.delete(provider.id);\n          notify();\n        }\n      };\n    },\n\n    async resolve(target, restrict) {\n      const authResumable = Boolean(ports.auth);\n      const seen = new Map<string, string>();\n      const out: ResolvedAction[] = [];\n      for (const [providerId, { provider }] of [...entries]) {\n        let actions: readonly Action[];\n        try {\n          actions = await provider.actions(target);\n        } catch (error) {\n          capture(ports, error, { providerId, stage: \"actions\" });\n          continue;\n        }\n        for (const raw of actions) {\n          const first = seen.get(raw.id);\n          if (first !== undefined) {\n            capture(ports, new DuplicateActionError(raw.id, first, providerId), { actionId: raw.id });\n            continue;\n          }\n          seen.set(raw.id, providerId);\n          const action: Action = raw.provider === providerId ? raw : { ...raw, provider: providerId };\n          let eligibility: ReturnType<typeof computeEligibility>;\n          try {\n            eligibility = computeEligibility(action, target, { restrict: restrict ?? {}, authResumable });\n          } catch (error) {\n            capture(ports, error, { actionId: action.id, stage: \"eligible\" });\n            continue;\n          }\n          if (eligibility.status === \"contract-break\") {\n            capture(ports, new Error(eligibility.reason), { actionId: action.id, stage: \"eligible\" });\n            continue;\n          }\n          if (eligibility.status === \"absent\") continue;\n          out.push({ action, eligibility });\n        }\n      }\n      return out;\n    },\n\n    providers() {\n      return [...entries.keys()];\n    },\n\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n  };\n}\n\n/** A provider over a fixed list; its ids are declared up front so duplicates fail at registration. */\nexport function staticActionProvider(\n  id: string,\n  actions: readonly Action[],\n  tier: ActionProvider[\"tier\"] = \"T0\",\n): ActionProvider {\n  const list = actions.map((a) => (a.provider === id ? a : { ...a, provider: id }));\n  return {\n    id,\n    tier,\n    declaredIds: () => list.map((a) => a.id),\n    actions: () => list,\n  };\n}\n\n/** Always-available eligibility, for actions with no rule of their own. */\nexport const alwaysEligible = (): Eligibility => ({ status: \"available\" });\n","/**\n * Sensitivity defaults and resolution (CONTRACT §2.1). Its own module so the\n * lightweight entries (`/actions`, the T0 React host) can project without\n * pulling the declaration registry.\n */\nimport type { DeclaredValue, Sensitivity } from \"./types\";\n\nexport const DEFAULT_SENSITIVITY: Sensitivity = Object.freeze({\n  exportable: true,\n  classification: \"ordinary\",\n  includedByDefault: true,\n});\n\nexport function resolveSensitivity(value: Pick<DeclaredValue, \"sensitivity\">): Sensitivity {\n  return {\n    exportable: value.sensitivity?.exportable ?? DEFAULT_SENSITIVITY.exportable,\n    classification: value.sensitivity?.classification ?? DEFAULT_SENSITIVITY.classification,\n    includedByDefault: value.sensitivity?.includedByDefault ?? DEFAULT_SENSITIVITY.includedByDefault,\n  };\n}\n","/**\n * PROJECTION BEFORE PROVIDERS (CONTRACT §2.4).\n *\n * The only place a raw read (`MountedSurface.readValues`,\n * `InternalResolvedItem.readValues`) is consumed on behalf of an action.\n * What leaves is projected: a value is kept only when it is DECLARED, its\n * classification is \"ordinary\" and it is exportable. Everything removed is\n * recorded as an omission, so the person and the agent can see what was held\n * back. No caller can relax this.\n */\nimport { resolveSensitivity } from \"../declare/sensitivity\";\nimport type { InternalResolvedItem, MountedSurface } from \"../declare/host\";\nimport type { DeclaredValue, Json, LiveValues, ResolvedSurfaceDeclaration } from \"../declare/types\";\nimport type { ProjectedReads, ReadOmission } from \"./types\";\n\nexport interface ProjectionSource {\n  surface: MountedSurface | null;\n  declaration: ResolvedSurfaceDeclaration | null;\n  item: InternalResolvedItem | null;\n}\n\nfunction toJson(value: unknown): Json | undefined {\n  if (value === undefined || typeof value === \"function\" || typeof value === \"symbol\") return undefined;\n  if (value === null || typeof value === \"string\" || typeof value === \"boolean\") return value;\n  if (typeof value === \"number\") return Number.isFinite(value) ? value : null;\n  if (typeof value === \"bigint\") return value.toString();\n  if (value instanceof Date) return value.toISOString();\n  if (Array.isArray(value)) return value.map((v) => toJson(v) ?? null);\n  if (typeof value === \"object\") {\n    const out: { [key: string]: Json } = {};\n    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n      const j = toJson(v);\n      if (j !== undefined) out[k] = j;\n    }\n    return out;\n  }\n  return undefined;\n}\n\n/** Keep declared, ordinary, exportable values; record every removal. */\nexport function projectValues(\n  raw: Record<string, unknown>,\n  declared: readonly Pick<DeclaredValue, \"name\" | \"sensitivity\">[],\n  pathPrefix = \"\",\n): { values: Record<string, Json>; omissions: ReadOmission[] } {\n  const byName = new Map(declared.map((d) => [d.name, d]));\n  const values: Record<string, Json> = {};\n  const omissions: ReadOmission[] = [];\n  for (const [name, value] of Object.entries(raw)) {\n    const path = pathPrefix ? `${pathPrefix}.${name}` : name;\n    const decl = byName.get(name);\n    if (!decl) {\n      omissions.push({ path, reason: \"filtered\" });\n      continue;\n    }\n    const sensitivity = resolveSensitivity(decl);\n    if (sensitivity.classification !== \"ordinary\") {\n      omissions.push({ path, reason: \"excluded\", classification: sensitivity.classification });\n      continue;\n    }\n    if (!sensitivity.exportable) {\n      omissions.push({ path, reason: \"excluded\" });\n      continue;\n    }\n    const json = toJson(value);\n    if (json === undefined) continue;\n    values[name] = json;\n  }\n  return { values, omissions };\n}\n\nexport function createProjectedReads(source: ProjectionSource): ProjectedReads {\n  return {\n    async values(signal) {\n      if (!source.surface || !source.declaration) return { values: {}, omissions: [] };\n      const raw = await source.surface.readValues(signal);\n      const screenValues = source.declaration.values;\n      return projectValues(raw, screenValues);\n    },\n    async item(signal) {\n      const item = source.item;\n      if (!item || !source.declaration) return null;\n      const type = source.declaration.itemTypes?.find((t) => t.name === item.itemType);\n      if (!type) return { values: {}, omissions: [{ path: item.itemType, reason: \"filtered\" }] };\n      const raw = await item.readValues(signal);\n      return projectValues(raw, type.values, item.itemType);\n    },\n    async live(signal): Promise<LiveValues> {\n      if (!source.surface?.readLive) return {};\n      return source.surface.readLive(signal);\n    },\n  };\n}\n","import type { QualifiedValueKey } from \"./types\";\n\n/** Every value, write-target, item-type and group name (the DB CHECK rule). */\nexport const DECLARATION_NAME_RE = /^[a-z][a-z0-9_]*$/;\n\n/** \"<client>/<local>\" — the surface naming convention. */\nexport const SURFACE_NAME_RE = /^[a-z][a-z0-9-]*\\/[a-z0-9-/]+$/;\n\n/** A bare screen value (`status`) or an item value (`table_row.status`). */\nexport const QUALIFIED_VALUE_KEY_RE = /^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)?$/;\n\nexport interface ParsedValueKey {\n  /** \"\" for a screen-level value. */\n  itemType: string;\n  name: string;\n}\n\n/** Split a qualified key; null when it is not a valid bare or qualified key. */\nexport function parseQualifiedValueKey(key: string): ParsedValueKey | null {\n  if (!QUALIFIED_VALUE_KEY_RE.test(key)) return null;\n  const dot = key.indexOf(\".\");\n  if (dot === -1) return { itemType: \"\", name: key };\n  return { itemType: key.slice(0, dot), name: key.slice(dot + 1) };\n}\n\nexport function qualifyValueKey(itemType: string, name: string): QualifiedValueKey {\n  return itemType ? `${itemType}.${name}` : name;\n}\n\n/** The client that owns a surface: its name prefix. */\nexport function surfaceClientOf(surfaceName: string): string {\n  return surfaceName.split(\"/\")[0] ?? \"\";\n}\n","/**\n * Building a ClickTarget from what is declared at the click (CONTRACT §2.4).\n * Key existence, never value population: a value key is present when the\n * declaration gives it a read path here.\n */\nimport { resolveSensitivity } from \"../declare/sensitivity\";\nimport { qualifyValueKey } from \"../declare/keys\";\nimport type { ResolvedItem, ResolvedSurfaceDeclaration, WriteTarget } from \"../declare/types\";\nimport type { ClickTarget } from \"./types\";\n\nexport interface ClickTargetInput {\n  surface?: ClickTarget[\"surface\"];\n  declaration?: ResolvedSurfaceDeclaration | null;\n  item?: ResolvedItem | null;\n  level?: string | null;\n  selection?: ClickTarget[\"selection\"];\n  payloadKinds?: ClickTarget[\"payloadKinds\"];\n  /** Defaults to the item's readOnly (or false). */\n  readOnly?: boolean;\n  /** Extra exclusions on top of the declaration's own. */\n  excludedActionIds?: Iterable<string>;\n  scopeChain?: readonly string[];\n  organizationId?: string | null;\n  auth?: Partial<ClickTarget[\"auth\"]>;\n  /** Write targets the host can serve right now; defaults to every declared target for the screen/item. */\n  writable?: readonly WriteTarget[];\n  host?: unknown;\n}\n\nfunction domainOf(surfaceName: string): string {\n  const slash = surfaceName.indexOf(\"/\");\n  return slash > 0 ? surfaceName.slice(0, slash) : surfaceName;\n}\n\nexport function createClickTarget(input: ClickTargetInput = {}): ClickTarget {\n  const declaration = input.declaration ?? null;\n  const item = input.item ?? null;\n  const valueKeys = new Set<string>();\n  let restricted = false;\n  const writable: WriteTarget[] = [];\n  if (declaration) {\n    for (const value of declaration.values) {\n      valueKeys.add(value.name);\n      const s = resolveSensitivity(value);\n      if (s.classification !== \"ordinary\" || !s.exportable) restricted = true;\n    }\n    const itemType = item ? declaration.itemTypes?.find((t) => t.name === item.itemType) : undefined;\n    if (itemType) {\n      for (const value of itemType.values) {\n        valueKeys.add(qualifyValueKey(itemType.name, value.name));\n        const s = resolveSensitivity(value);\n        if (s.classification !== \"ordinary\" || !s.exportable) restricted = true;\n      }\n      for (const t of itemType.writeTargets ?? []) writable.push(t);\n    }\n    for (const t of declaration.writeTargets ?? []) {\n      if (!t.itemType || t.itemType === item?.itemType) writable.push(t);\n    }\n  }\n  const readOnly = input.readOnly ?? item?.readOnly ?? false;\n  const surfaceName = input.surface?.surfaceName ?? declaration?.surfaceName ?? null;\n  const scopeChain = input.scopeChain ?? (surfaceName ? [\"global\", domainOf(surfaceName), surfaceName] : [\"global\"]);\n  return {\n    surface: input.surface ?? null,\n    declaration,\n    valueKeys,\n    scopeChain,\n    excludedActionIds: new Set(input.excludedActionIds ?? []),\n    item,\n    level: input.level ?? item?.level ?? null,\n    selection: input.selection ?? null,\n    payloadKinds: input.payloadKinds ?? [],\n    writable: readOnly ? [] : (input.writable ?? writable),\n    readOnly,\n    restricted,\n    organizationId: input.organizationId ?? null,\n    auth: {\n      authenticated: input.auth?.authenticated ?? false,\n      admin: input.auth?.admin ?? false,\n      creator: input.auth?.creator ?? false,\n    },\n    host: input.host,\n  };\n}\n","/**\n * The one run path (T1e). Every layout runs an action through here, so the\n * sign-in-then-resume rule, projection and failure capture live once.\n */\nimport type { TransferOutcome } from \"@ai-matrx/kit/content-transfer\";\nimport type { AlchemyHostPorts } from \"../ports\";\nimport { createProjectedReads, type ProjectionSource } from \"./projection\";\nimport type { Action, ClickTarget } from \"./types\";\n\nexport interface RunActionOptions {\n  ports: AlchemyHostPorts;\n  /** Raw sources; projected before the action sees them. */\n  source?: ProjectionSource;\n  /** Stable fingerprint of the content, for sign-in-then-resume. */\n  contentFingerprint?: string;\n  signal?: AbortSignal;\n}\n\nexport type RunResult =\n  | { status: \"ran\"; outcome: TransferOutcome | void }\n  | { status: \"auth-pending\" }\n  | { status: \"failed\"; error: unknown };\n\nexport async function runAction(action: Action, target: ClickTarget, options: RunActionOptions): Promise<RunResult> {\n  const { ports } = options;\n  if (action.requiresAuth && !target.auth.authenticated) {\n    if (!ports.auth) {\n      // Unreachable through resolve (the action is absent without the port); guard direct callers.\n      ports.diagnostics.capture(new Error(`requiresAuth action \"${action.id}\" ran signed out with no auth port`), {\n        area: \"actions\",\n        detail: { actionId: action.id },\n      });\n      return { status: \"failed\", error: new Error(\"sign-in unavailable\") };\n    }\n    ports.auth.signInThenResume({ actionId: action.id, contentFingerprint: options.contentFingerprint ?? action.id });\n    return { status: \"auth-pending\" };\n  }\n  const reads = createProjectedReads(options.source ?? { surface: null, declaration: target.declaration, item: null });\n  const signal = options.signal ?? new AbortController().signal;\n  try {\n    const outcome = await action.run(target, { reads, ports, signal });\n    return { status: \"ran\", outcome };\n  } catch (error) {\n    ports.diagnostics.capture(error, { area: \"actions\", detail: { actionId: action.id, stage: \"run\" } });\n    const label = typeof action.label === \"string\" ? action.label : action.id;\n    ports.notify?.error(`${label} did not finish.`, \"Try again; if it keeps failing, report it from the feedback button.\");\n    return { status: \"failed\", error };\n  }\n}\n"],"mappings":"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","names":[]}