@ai-matrx/alchemy 0.9.1 → 0.11.0

package/dist/ports.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ports.ts"],"sourcesContent":["/**\n * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).\n *\n * The app binds these ONCE, at its boundary (where the Alchemy host is\n * mounted). The package never imports the host.\n *\n * ── Ports arrive with the wave that needs them (chair ruling N8) ────────────\n *\n * This entry declares only the ports the current waves use:\n *\n *   ALC-13  `kinds` (content-ir's validator, injected), `diagnostics` (required)\n *   ALC-14  `identity`, `persistence`\n *   ALC-15  `store`, `notify`, `overlay`, `icons`, `knobs`, `i18n`, `auth`, `dialogs`\n *\n *   ALC-16  `transport`, `assets`, `server`\n *   PP-01a  `window` (host-rendered windows for a live preparation session)\n *   PP-13a  `transferKnobs` (organization default recipes)\n *\n * ALC-17 adds approvals/bodies/receipts.\n *\n * ── Absent-port semantics ───────────────────────────────────────────────────\n *\n * Every port except `diagnostics` is OPTIONAL. A port the host does not bind\n * means that capability is ABSENT: the actions, formats or writes that need\n * it are not offered at all. A missing port is never stubbed, never faked\n * with a default that pretends to work, and never shown as a dead control.\n *\n *   kinds        absent → kind validation is absent (no value can be checked,\n *                         so a kind-bearing write is not offered)\n *   diagnostics  REQUIRED → nothing fails silently; contract breaks land here\n *   identity     absent → organization-scoped declarations are absent\n *   persistence  absent → per-person settings are absent (organization and\n *                         platform defaults apply)\n *   store        absent → actions that read named host state or run named\n *                         host commands are absent\n *   notify       absent → outcomes are not announced (diagnostics still captures)\n *   overlay      absent → actions that open an overlay or navigate are absent\n *   icons        absent → rows render label-only (a key is never shown as text)\n *   knobs        absent → the platform default layout/density applies\n *   i18n         absent → labels as written\n *   auth         absent → a signed-out person does not see requiresAuth actions\n *                         (sign-in-then-resume is the capability that is missing)\n *   dialogs      absent → actions that need a host dialog are absent\n *   window       absent → the preparation workspace window is absent (its\n *                         Prepare entry is not offered; it never falls back\n *                         to an overlay carrying the session as data)\n *   transferKnobs absent → no organization default recipe; a person's own\n *                         default (persistence) or the package's Full applies\n *   serverActions absent → `runs: \"server\"` Actions refuse with \"not available here\"\n *   mandates     absent → `runs: \"mandate\"` Actions refuse the same way\n *   pageActions  absent → `runs: \"page\"` Actions refuse the same way\n *   approvals    absent → a policy \"ask\" Action started by an agent, applet or automation is refused\n *                         (\"needs a person's approval\"); a person's own click is the approval\n *                (`runs: \"navigate\"` goes through `overlay.navigate`; overlay absent → refused)\n *\n * Types only: this entry has no runtime code.\n */\n\n/** JSON as it crosses a port. */\nexport type Json =\n  | null\n  | boolean\n  | number\n  | string\n  | Json[]\n  | { [key: string]: Json };\n\n/**\n * content-ir's kind validator, injected so Alchemy validates without\n * importing the app or the kind catalog. The host builds it from\n * `@ai-matrx/content-ir`'s `createKindValidator` over its own\n * `SchemaSourcePort` (which content-ir defines and exports; Alchemy never\n * declares it).\n *\n * `unverifiable: true` marks a verdict where the kind could not be checked\n * (not registered, no schema, uncompilable schema, catalog unreachable) — a\n * skip, which is never a pass.\n */\nexport interface KindValidatorPort {\n  validate(\n    kindKey: string,\n    value: unknown,\n    signal: AbortSignal,\n  ): Promise<\n    | { ok: true }\n    | { ok: false; sentence: string; remedy: string; unverifiable?: true }\n  >;\n}\n\nimport type { ClickTarget } from \"./actions/click-target\";\nimport type {\n  ActionContext,\n  ActionResult,\n  MandateRunRequest,\n  ServerActionRunRequest,\n  ServerActionRunResponse,\n} from \"./actions/applet-types\";\n\n/** Where contract breaks are captured. Required: nothing fails silently. */\nexport interface DiagnosticsPort {\n  capture(\n    error: unknown,\n    context: {\n      area: \"declare\" | \"operate\" | \"write\" | \"actions\" | \"menu\";\n      detail: Json;\n    },\n  ): void;\n}\n\n/** Who is using the app right now, and in which organization. */\nexport interface IdentityPort {\n  /** `null` while the host has no resolved identity yet. */\n  current(): {\n    userId: string;\n    organizationId: string | null;\n    isAuthenticated: boolean;\n    isAdmin: boolean;\n  } | null;\n  /** Called whenever `current()` may answer differently; returns unsubscribe. */\n  onChange(listener: () => void): () => void;\n}\n\n/** Per-person settings (layout, density, transfer preferences), layered by the host's settings system. */\nexport interface PersistencePort {\n  readSetting<T extends Json>(key: string): Promise<T | null>;\n  writeSetting(key: string, value: Json): Promise<void>;\n}\n\n/** Neutral state access: named reads and named commands. No Redux type or dispatch crosses this line. */\nexport interface StorePort {\n  /** A named, typed read the host registered (\"activeConversationId\", \"organizationName\"). */\n  read<T extends Json>(key: string): T | null;\n  /** A named command the host registered (\"tasks.setPendingSource\"); resolves with its result. */\n  command(name: string, input: Json): Promise<Json | void>;\n  subscribe(key: string, listener: () => void): () => void;\n}\n\nexport interface NotifyPort {\n  success(sentence: string): void;\n  info(sentence: string): void;\n  /** Every failure names its remedy. */\n  error(sentence: string, remedy: string): void;\n}\n\n/** Overlays are dispatched through the host; the menu never renders a modal. */\nexport interface OverlayHostPort {\n  open(overlayId: string, data: Json, instanceId?: string): void;\n  close(overlayId: string, instanceId?: string): void;\n  navigate(href: string): void;\n}\n\n/** Icon key → the host's icon component. The model only ever holds keys. */\nexport interface IconResolverPort {\n  resolve(key: string): unknown /* host component */ | null;\n}\n\nexport type ContextArrangementKnob = \"classic\" | \"tiered\" | \"command\";\nexport type DensityKnob = \"comfortable\" | \"compact\";\n\n/** ORGANIZATION defaults only; every method takes the organization. */\nexport interface MenuKnobsPort {\n  /** Replaces the constant PLACEMENT_LABEL_OVERRIDE. */\n  placementLabel(placement: string, organizationId: string | null): string | null;\n  /** Replaces the constant DEFAULT_PLACEMENT_MODE. */\n  placementMode(placement: string, organizationId: string | null): \"show\" | \"hide\";\n  /** The organization's default layout and density (platform default when null: command / comfortable). */\n  layout(organizationId: string | null): { context: ContextArrangementKnob; density: DensityKnob } | null;\n}\n\n/** Label translation. Absent = labels as written. */\nexport interface I18nPort {\n  t(key: string, fallback: string): string;\n}\n\n/** Sign in, then resume the action the person picked. */\nexport interface AuthResumePort {\n  isSignedIn(): boolean;\n  /** Stash {actionId, target fingerprint} and open sign-in; after sign-in the next matching menu host resumes it. */\n  signInThenResume(pending: { actionId: string; contentFingerprint: string }): void;\n  takePending(contentFingerprint: string): { actionId: string } | null;\n}\n\n/** Per-instance host dialogs (today's RichDocumentActionContextCallbacks). */\nexport interface HostDialogsPort {\n  requestDelete?(target: ClickTarget): void;\n  requestConvert?(target: ClickTarget): void;\n  requestEditHistory?(target: ClickTarget): void;\n  requestFullPrint?(target: ClickTarget): void;\n  requestSaveTable?(table: { headers: string[]; rows: string[][] }): void;\n  requestFlashcard?(answer: string): void;\n}\n\n/** The ports a host binds. Optional = absent capability when unbound (see above). */\nexport interface AlchemyHostPorts {\n  // ALC-13\n  kinds?: KindValidatorPort;\n  /** REQUIRED from ALC-13 (the only non-optional port): contract breaks are captured here. */\n  diagnostics: DiagnosticsPort;\n  // ALC-14\n  identity?: IdentityPort;\n  persistence?: PersistencePort;\n  // ALC-15\n  store?: StorePort;\n  notify?: NotifyPort;\n  overlay?: OverlayHostPort;\n  icons?: IconResolverPort;\n  /** Organization defaults for menu knobs; a person's own choice is layered over them via persistence (N9). */\n  knobs?: MenuKnobsPort;\n  i18n?: I18nPort;\n  auth?: AuthResumePort;\n  dialogs?: HostDialogsPort;\n  // ALC-16\n  /** Clipboard and download for this runtime (the browser default ships in /operate). */\n  transport?: TransportPort;\n  /** Private or signed images → share-safe URLs before HTML is sealed. Absent = images keep their URL. */\n  assets?: AssetResolverPort;\n  /** Present when the host can reach aidream server operations; absent = server formats are not offered. */\n  server?: ServerPort;\n  // Preparation parity (PP-01a, PP-13a)\n  /** Host-rendered windows for a LIVE preparation session (functions, subscriptions, sealed artifacts). */\n  window?: WindowPort;\n  /** Organization default recipes, resolved by the host's Feature Knob ladder (platform → organization). */\n  transferKnobs?: TransferKnobsPort;\n  // Surface Actions (Applets CONTRACTS §6)\n  /** aidream `POST /actions/run`: a registered server action by name, as the caller, under the apply-policy cascade. */\n  serverActions?: ServerActionPort;\n  /** Runs a mandate by alias or key (the host binds `@ai-matrx/agents`; alchemy never imports it). */\n  mandates?: MandatePort;\n  /** The page's own handlers for `runs: \"page\"` Actions (in an applet frame: routed as `{ action, input, runId }`). */\n  pageActions?: PageActionPort;\n  /** Asks a person, in place, to approve an `ask` Action that an agent, applet or automation started. */\n  approvals?: ApprovalPort;\n}\n\n// ── Surface Actions (Applets CONTRACTS §6) ──────────────────────────────────\n\nexport interface ServerActionPort {\n  run(request: ServerActionRunRequest): Promise<ServerActionRunResponse>;\n}\nexport interface MandatePort {\n  /** Resolves with the run's result (a kind envelope or JSON); rejects with the system's sentence. */\n  run(request: MandateRunRequest): Promise<unknown>;\n}\nexport interface ApprovalRequest {\n  action: string;\n  label: string;\n  description: string;\n  input: Json;\n  by: \"agent\" | \"applet\" | \"automation\";\n  surfaceName: string;\n}\nexport interface ApprovalPort {\n  /** Resolves true when the person approves; false when they decline or dismiss. */\n  ask(request: ApprovalRequest): Promise<boolean>;\n}\nexport interface PageActionPort {\n  dispatch(name: string, input: unknown, context: ActionContext): Promise<ActionResult<unknown>>;\n}\n\n// ── PP-01a — WindowPort ─────────────────────────────────────────────────────\n\n/**\n * Why a port and not `OverlayHostPort`: an overlay's `data` is `Json`, and a live preparation\n * session is not — it holds functions, subscriptions and sealed-artifact handles. So the workspace\n * never travels as overlay data; the package hands the host a render function and the host draws it\n * inside its own window system, with the session still live in the closure.\n */\nexport interface WindowSize {\n  width: number;\n  height: number;\n}\nexport interface WindowOpenOptions {\n  /** The window's title, as a person reads it. */\n  title: string;\n  /** Preferred size; `\"full\"` = near-full-screen. The host clamps to the viewport. */\n  size?: WindowSize | \"full\";\n  /**\n   * Stable identity. Opening an id that is already open focuses that window and draws the new\n   * render in it instead of opening a second one.\n   */\n  instanceId?: string;\n  /** Called exactly once when the window closes, whoever closed it (the person, `close()`, the host). */\n  onClose?: () => void;\n}\nexport interface WindowHandle {\n  readonly instanceId: string;\n  /** Close the window; idempotent. */\n  close(): void;\n  /** Bring the window to the front; a no-op once closed. */\n  focus(): void;\n  isOpen(): boolean;\n}\nexport interface WindowPort {\n  /**\n   * What the host really draws. `\"window\"`: non-blocking, movable, resizable. `\"dialog\"`: a blocking\n   * full-screen dialog — a surface on a dialog host never says \"window\" and never offers a second one.\n   */\n  readonly presentation: \"window\" | \"dialog\";\n  /** True only when several windows can be open and usable at once. False = never offer \"open another\". */\n  readonly multiInstance: boolean;\n  /**\n   * Draw `render(handle)` inside a host window. `render` returns a host UI node (a React element in\n   * a React host) and is called by the host while the window is open.\n   */\n  open(render: (window: WindowHandle) => unknown, options: WindowOpenOptions): WindowHandle;\n}\n\n// ── PP-13a — TransferKnobsPort ──────────────────────────────────────────────\n\n/**\n * ORGANIZATION defaults for transfer, resolved by the host's Feature Knob ladder: the platform\n * default an admin sets, overridden by the organization. Never per-person — a person's own choice\n * lives only in `PersistencePort` and is layered over this by the package (`resolveDefaultRecipe`).\n */\nexport interface TransferKnobsPort {\n  /**\n   * The organization's default recipe for one source kind (the platform default when the\n   * organization set none), or null when neither names one. A read that fails rejects; it never\n   * answers null for \"could not ask\".\n   */\n  defaultRecipe(sourceKind: string, organizationId: string | null): Promise<Json | null>;\n}\n\n// ── ALC-16 ports (Operate) ──────────────────────────────────────────────────\n\n/** A transferable artifact as the transport sees it (structurally `@ai-matrx/alchemy/operate`'s Artifact). */\nexport interface TransportArtifact {\n  format: string;\n  plainText: string;\n  html?: string;\n  file?: { filename: string; mime: string; bytes: Uint8Array };\n}\nexport type TransportOutcome =\n  | { status: \"success\"; delivered: \"clipboard\" | \"download-started\"; mimeTypes: string[] }\n  | { status: \"degraded\"; delivered: \"plain-text\"; reason: string }\n  | { status: \"cancelled\" }\n  | { status: \"error\"; code: string; message: string; retryable: boolean };\n/** Clipboard and download for a non-browser runtime (MV3 service worker, Tauri — CONTRACT R8). */\nexport interface TransportPort {\n  copy(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;\n  download(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;\n}\nexport interface AssetResolverPort {\n  resolve(url: string, signal: AbortSignal): Promise<{ url: string } | null>;\n}\nexport type ServerResult =\n  | { status: \"bytes\"; filename: string; mime: string; bytes: Uint8Array; notices: readonly { code: string; sentence: string; remedy: string }[] }\n  | { status: \"receipt\"; receipt: { status: string; sentence: string; remedy?: string } };\nexport interface ServerPort {\n  call(operationId: string, input: Json, signal: AbortSignal): Promise<ServerResult>;\n}\n"],"mappings":"sjBAAA","names":[]}
+{"version":3,"sources":["../src/ports.ts"],"sourcesContent":["/**\n * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).\n *\n * The app binds these ONCE, at its boundary (where the Alchemy host is\n * mounted). The package never imports the host.\n *\n * ── Ports arrive with the wave that needs them (chair ruling N8) ────────────\n *\n * This entry declares only the ports the current waves use:\n *\n *   ALC-13  `kinds` (content-ir's validator, injected), `diagnostics` (required)\n *   ALC-14  `identity`, `persistence`\n *   ALC-15  `store`, `notify`, `overlay`, `icons`, `knobs`, `i18n`, `auth`, `dialogs`\n *\n *   ALC-16  `transport`, `assets`, `server`\n *   PP-01a  `window` (host-rendered windows for a live preparation session)\n *   PP-13a  `transferKnobs` (organization default recipes)\n *\n *   ALC-17  `door` (the one write door), `review` (queued writes)\n *\n * ── Absent-port semantics ───────────────────────────────────────────────────\n *\n * Every port except `diagnostics` is OPTIONAL. A port the host does not bind\n * means that capability is ABSENT: the actions, formats or writes that need\n * it are not offered at all. A missing port is never stubbed, never faked\n * with a default that pretends to work, and never shown as a dead control.\n *\n *   kinds        absent → kind validation is absent (no value can be checked,\n *                         so a kind-bearing write is not offered)\n *   diagnostics  REQUIRED → nothing fails silently; contract breaks land here\n *   identity     absent → organization-scoped declarations are absent\n *   persistence  absent → per-person settings are absent (organization and\n *                         platform defaults apply)\n *   store        absent → actions that read named host state or run named\n *                         host commands are absent\n *   notify       absent → outcomes are not announced (diagnostics still captures)\n *   overlay      absent → actions that open an overlay or navigate are absent\n *   icons        absent → rows render label-only (a key is never shown as text)\n *   knobs        absent → the platform default layout/density applies\n *   i18n         absent → labels as written\n *   auth         absent → a signed-out person does not see requiresAuth actions\n *                         (sign-in-then-resume is the capability that is missing)\n *   dialogs      absent → actions that need a host dialog are absent\n *   window       absent → the preparation workspace window is absent (its\n *                         Prepare entry is not offered; it never falls back\n *                         to an overlay carrying the session as data)\n *   transferKnobs absent → no organization default recipe; a person's own\n *                         default (persistence) or the package's Full applies\n *   serverActions absent → `runs: \"server\"` Actions refuse with \"not available here\"\n *   mandates     absent → `runs: \"mandate\"` Actions refuse the same way\n *   pageActions  absent → `runs: \"page\"` Actions refuse the same way\n *   approvals    absent → a policy \"ask\" Action started by an agent, applet or automation is refused\n *                         (\"needs a person's approval\"); a person's own click is the approval\n *                (`runs: \"navigate\"` goes through `overlay.navigate`; overlay absent → refused)\n *   door         absent → write-target Actions dispatch to `pageActions` as before, and\n *                         `Delivery.send` is refused with a remedy; bound → every such write goes\n *                         through it and returns its receipt\n *   review       absent → a write to a `queued` target is refused (\"review isn't available here\")\n *\n * Types only: this entry has no runtime code.\n */\n\n/** JSON as it crosses a port. */\nexport type Json =\n  | null\n  | boolean\n  | number\n  | string\n  | Json[]\n  | { [key: string]: Json };\n\n/**\n * content-ir's kind validator, injected so Alchemy validates without\n * importing the app or the kind catalog. The host builds it from\n * `@ai-matrx/content-ir`'s `createKindValidator` over its own\n * `SchemaSourcePort` (which content-ir defines and exports; Alchemy never\n * declares it).\n *\n * `unverifiable: true` marks a verdict where the kind could not be checked\n * (not registered, no schema, uncompilable schema, catalog unreachable) — a\n * skip, which is never a pass.\n */\nexport interface KindValidatorPort {\n  validate(\n    kindKey: string,\n    value: unknown,\n    signal: AbortSignal,\n  ): Promise<\n    | { ok: true }\n    | { ok: false; sentence: string; remedy: string; unverifiable?: true }\n  >;\n}\n\nimport type { ClickTarget } from \"./actions/click-target\";\nimport type { WriteDoor, WriteReviewPort } from \"./operate/door\";\nexport type { WriteDoor, WriteReviewPort } from \"./operate/door\";\nimport type {\n  ActionContext,\n  ActionResult,\n  MandateRunRef,\n  MandateRunRequest,\n  ServerActionRunRequest,\n  ServerActionRunResponse,\n} from \"./actions/applet-types\";\n\n/** Where contract breaks are captured. Required: nothing fails silently. */\nexport interface DiagnosticsPort {\n  capture(\n    error: unknown,\n    context: {\n      area: \"declare\" | \"operate\" | \"write\" | \"actions\" | \"menu\";\n      detail: Json;\n    },\n  ): void;\n}\n\n/** Who is using the app right now, and in which organization. */\nexport interface IdentityPort {\n  /** `null` while the host has no resolved identity yet. */\n  current(): {\n    userId: string;\n    organizationId: string | null;\n    isAuthenticated: boolean;\n    isAdmin: boolean;\n  } | null;\n  /** Called whenever `current()` may answer differently; returns unsubscribe. */\n  onChange(listener: () => void): () => void;\n}\n\n/** Per-person settings (layout, density, transfer preferences), layered by the host's settings system. */\nexport interface PersistencePort {\n  readSetting<T extends Json>(key: string): Promise<T | null>;\n  writeSetting(key: string, value: Json): Promise<void>;\n}\n\n/** Neutral state access: named reads and named commands. No Redux type or dispatch crosses this line. */\nexport interface StorePort {\n  /** A named, typed read the host registered (\"activeConversationId\", \"organizationName\"). */\n  read<T extends Json>(key: string): T | null;\n  /** A named command the host registered (\"tasks.setPendingSource\"); resolves with its result. */\n  command(name: string, input: Json): Promise<Json | void>;\n  subscribe(key: string, listener: () => void): () => void;\n}\n\nexport interface NotifyPort {\n  success(sentence: string): void;\n  info(sentence: string): void;\n  /** Every failure names its remedy. */\n  error(sentence: string, remedy: string): void;\n}\n\n/** Overlays are dispatched through the host; the menu never renders a modal. */\nexport interface OverlayHostPort {\n  open(overlayId: string, data: Json, instanceId?: string): void;\n  close(overlayId: string, instanceId?: string): void;\n  navigate(href: string): void;\n}\n\n/** Icon key → the host's icon component. The model only ever holds keys. */\nexport interface IconResolverPort {\n  resolve(key: string): unknown /* host component */ | null;\n}\n\nexport type ContextArrangementKnob = \"classic\" | \"tiered\" | \"command\";\nexport type DensityKnob = \"comfortable\" | \"compact\";\n\n/** ORGANIZATION defaults only; every method takes the organization. */\nexport interface MenuKnobsPort {\n  /** Replaces the constant PLACEMENT_LABEL_OVERRIDE. */\n  placementLabel(placement: string, organizationId: string | null): string | null;\n  /** Replaces the constant DEFAULT_PLACEMENT_MODE. */\n  placementMode(placement: string, organizationId: string | null): \"show\" | \"hide\";\n  /** The organization's default layout and density (platform default when null: command / comfortable). */\n  layout(organizationId: string | null): { context: ContextArrangementKnob; density: DensityKnob } | null;\n}\n\n/** Label translation. Absent = labels as written. */\nexport interface I18nPort {\n  t(key: string, fallback: string): string;\n}\n\n/** Sign in, then resume the action the person picked. */\nexport interface AuthResumePort {\n  isSignedIn(): boolean;\n  /** Stash {actionId, target fingerprint} and open sign-in; after sign-in the next matching menu host resumes it. */\n  signInThenResume(pending: { actionId: string; contentFingerprint: string }): void;\n  takePending(contentFingerprint: string): { actionId: string } | null;\n}\n\n/** Per-instance host dialogs (today's RichDocumentActionContextCallbacks). */\nexport interface HostDialogsPort {\n  requestDelete?(target: ClickTarget): void;\n  requestConvert?(target: ClickTarget): void;\n  requestEditHistory?(target: ClickTarget): void;\n  requestFullPrint?(target: ClickTarget): void;\n  requestSaveTable?(table: { headers: string[]; rows: string[][] }): void;\n  requestFlashcard?(answer: string): void;\n}\n\n/** The ports a host binds. Optional = absent capability when unbound (see above). */\nexport interface AlchemyHostPorts {\n  // ALC-13\n  kinds?: KindValidatorPort;\n  /** REQUIRED from ALC-13 (the only non-optional port): contract breaks are captured here. */\n  diagnostics: DiagnosticsPort;\n  // ALC-14\n  identity?: IdentityPort;\n  persistence?: PersistencePort;\n  // ALC-15\n  store?: StorePort;\n  notify?: NotifyPort;\n  overlay?: OverlayHostPort;\n  icons?: IconResolverPort;\n  /** Organization defaults for menu knobs; a person's own choice is layered over them via persistence (N9). */\n  knobs?: MenuKnobsPort;\n  i18n?: I18nPort;\n  auth?: AuthResumePort;\n  dialogs?: HostDialogsPort;\n  // ALC-16\n  /** Clipboard and download for this runtime (the browser default ships in /operate). */\n  transport?: TransportPort;\n  /** Private or signed images → share-safe URLs before HTML is sealed. Absent = images keep their URL. */\n  assets?: AssetResolverPort;\n  /** Present when the host can reach aidream server operations; absent = server formats are not offered. */\n  server?: ServerPort;\n  // Preparation parity (PP-01a, PP-13a)\n  /** Host-rendered windows for a LIVE preparation session (functions, subscriptions, sealed artifacts). */\n  window?: WindowPort;\n  /** Organization default recipes, resolved by the host's Feature Knob ladder (platform → organization). */\n  transferKnobs?: TransferKnobsPort;\n  // Surface Actions (Applets CONTRACTS §6)\n  /** aidream `POST /actions/run`: a registered server action by name, as the caller, under the apply-policy cascade. */\n  serverActions?: ServerActionPort;\n  /** Runs a mandate by alias or key (the host binds `@ai-matrx/agents`; alchemy never imports it). */\n  mandates?: MandatePort;\n  /** The page's own handlers for `runs: \"page\"` Actions (in an applet frame: routed as `{ action, input, runId }`). */\n  pageActions?: PageActionPort;\n  /** Asks a person, in place, to approve an `ask` Action that an agent, applet or automation started. */\n  approvals?: ApprovalPort;\n  // ALC-17 — the one write door\n  /** `createWriteDoor(...)`: every write to a declared target lands here and returns a receipt. */\n  door?: WriteDoor;\n  /** Files a write to a `queued` target for an organization's review. */\n  review?: WriteReviewPort;\n}\n\n// ── Surface Actions (Applets CONTRACTS §6) ──────────────────────────────────\n\nexport interface ServerActionPort {\n  run(request: ServerActionRunRequest): Promise<ServerActionRunResponse>;\n}\nexport interface MandatePort {\n  /**\n   * STARTS the run and resolves with its `RunRef` (CONTRACTS §3/§6) — never the run's result, which\n   * arrives later on `run:<requestId>` / `IntelligencePort.result(ref)`. Rejects with the system's sentence.\n   */\n  run(request: MandateRunRequest): Promise<MandateRunRef>;\n}\nexport interface ApprovalRequest {\n  action: string;\n  label: string;\n  description: string;\n  input: Json;\n  by: \"agent\" | \"applet\" | \"automation\";\n  surfaceName: string;\n}\nexport interface ApprovalPort {\n  /** Resolves true when the person approves; false when they decline or dismiss. */\n  ask(request: ApprovalRequest): Promise<boolean>;\n}\nexport interface PageActionPort {\n  dispatch(name: string, input: unknown, context: ActionContext): Promise<ActionResult<unknown>>;\n}\n\n// ── PP-01a — WindowPort ─────────────────────────────────────────────────────\n\n/**\n * Why a port and not `OverlayHostPort`: an overlay's `data` is `Json`, and a live preparation\n * session is not — it holds functions, subscriptions and sealed-artifact handles. So the workspace\n * never travels as overlay data; the package hands the host a render function and the host draws it\n * inside its own window system, with the session still live in the closure.\n */\nexport interface WindowSize {\n  width: number;\n  height: number;\n}\nexport interface WindowOpenOptions {\n  /** The window's title, as a person reads it. */\n  title: string;\n  /** Preferred size; `\"full\"` = near-full-screen. The host clamps to the viewport. */\n  size?: WindowSize | \"full\";\n  /**\n   * Stable identity. Opening an id that is already open focuses that window and draws the new\n   * render in it instead of opening a second one.\n   */\n  instanceId?: string;\n  /** Called exactly once when the window closes, whoever closed it (the person, `close()`, the host). */\n  onClose?: () => void;\n}\nexport interface WindowHandle {\n  readonly instanceId: string;\n  /** Close the window; idempotent. */\n  close(): void;\n  /** Bring the window to the front; a no-op once closed. */\n  focus(): void;\n  isOpen(): boolean;\n}\nexport interface WindowPort {\n  /**\n   * What the host really draws. `\"window\"`: non-blocking, movable, resizable. `\"dialog\"`: a blocking\n   * full-screen dialog — a surface on a dialog host never says \"window\" and never offers a second one.\n   */\n  readonly presentation: \"window\" | \"dialog\";\n  /** True only when several windows can be open and usable at once. False = never offer \"open another\". */\n  readonly multiInstance: boolean;\n  /**\n   * Draw `render(handle)` inside a host window. `render` returns a host UI node (a React element in\n   * a React host) and is called by the host while the window is open.\n   */\n  open(render: (window: WindowHandle) => unknown, options: WindowOpenOptions): WindowHandle;\n}\n\n// ── PP-13a — TransferKnobsPort ──────────────────────────────────────────────\n\n/**\n * ORGANIZATION defaults for transfer, resolved by the host's Feature Knob ladder: the platform\n * default an admin sets, overridden by the organization. Never per-person — a person's own choice\n * lives only in `PersistencePort` and is layered over this by the package (`resolveDefaultRecipe`).\n */\nexport interface TransferKnobsPort {\n  /**\n   * The organization's default recipe for one source kind (the platform default when the\n   * organization set none), or null when neither names one. A read that fails rejects; it never\n   * answers null for \"could not ask\".\n   */\n  defaultRecipe(sourceKind: string, organizationId: string | null): Promise<Json | null>;\n}\n\n// ── ALC-16 ports (Operate) ──────────────────────────────────────────────────\n\n/** A transferable artifact as the transport sees it (structurally `@ai-matrx/alchemy/operate`'s Artifact). */\nexport interface TransportArtifact {\n  format: string;\n  plainText: string;\n  html?: string;\n  file?: { filename: string; mime: string; bytes: Uint8Array };\n}\nexport type TransportOutcome =\n  | { status: \"success\"; delivered: \"clipboard\" | \"download-started\"; mimeTypes: string[] }\n  | { status: \"degraded\"; delivered: \"plain-text\"; reason: string }\n  | { status: \"cancelled\" }\n  | { status: \"error\"; code: string; message: string; retryable: boolean };\n/** Clipboard and download for a non-browser runtime (MV3 service worker, Tauri — CONTRACT R8). */\nexport interface TransportPort {\n  copy(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;\n  download(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;\n}\nexport interface AssetResolverPort {\n  resolve(url: string, signal: AbortSignal): Promise<{ url: string } | null>;\n}\nexport type ServerResult =\n  | { status: \"bytes\"; filename: string; mime: string; bytes: Uint8Array; notices: readonly { code: string; sentence: string; remedy: string }[] }\n  | { status: \"receipt\"; receipt: { status: string; sentence: string; remedy?: string } };\nexport interface ServerPort {\n  call(operationId: string, input: Json, signal: AbortSignal): Promise<ServerResult>;\n}\n"],"mappings":"sjBAAA","names":[]}

package/dist/ports.d.cts

@@ -214,6 +214,148 @@ interface ClickTarget {
     host?: unknown;
 }
 
+/**
+ * Operate — the format and delivery contract (Matrx Alchemy CONTRACT §2.3, ALC-16).
+ *
+ * A format is an ADAPTER: `supports` is synchronous and loads nothing; `load` dynamically
+ * imports the engine the first time the format is chosen (print for rich-html/html/pdf/docx/
+ * epub, SheetJS for xlsx). Delivery accepts only a SEALED artifact, so the bytes previewed are
+ * the bytes copied, downloaded or sent.
+ */
+
+/** A reference to a declared write target (resolved by the one write door, ALC-17). */
+interface WriteTargetRef {
+    surfaceName?: string;
+    target: string;
+    item?: {
+        itemType: string;
+        identity: Record<string, string>;
+    };
+}
+/**
+ * Every write returns one (CONTRACT §2.3; the door is `createWriteDoor`, ALC-17). An applied
+ * receipt may carry a `warning` with its `fix` (rule 10: a person's kind mismatch warns, never refuses).
+ * A refusal's `reason` is a `WriteRefusalReason` (`./door`).
+ */
+type Receipt = {
+    status: "applied";
+    to: WriteTargetRef;
+    sentence: string;
+    warning?: string;
+    fix?: string;
+} | {
+    status: "queued";
+    to: WriteTargetRef;
+    sentence: string;
+    remedy: string;
+} | {
+    status: "refused";
+    to: WriteTargetRef;
+    reason: string;
+    sentence: string;
+    remedy: string;
+};
+
+/**
+ * THE ONE WRITE DOOR (Matrx Alchemy ALC-17; Applets CONTRACTS §6 "receipts through the one write door").
+ *
+ * Every write — a person's edit, a menu row, a destination send, an agent, an applet, an automation,
+ * an Action projected from a write target — lands through `door.write`. The door:
+ *
+ *   1. resolves the DECLARED write target (the surface's own, then its ancestors'); an undeclared
+ *      target is refused by name;
+ *   2. enforces the mode: `stream` takes ops from the target's `streamOps`; ops on any other target
+ *      need `patchable` (+ `updatesValue`); a value on a `stream` target is refused;
+ *   3. checks the kind (rule 10): a person's mismatch WARNS (the receipt is still applied, with a
+ *      `warning` and a `fix`); an agent's, applet's or automation's malformed write is REFUSED;
+ *   4. applies the policy: manual → a person only; ask → a person's own act is the approval, anyone
+ *      else asks through `approvals`; queued → filed through `review`; auto → applies;
+ *   5. applies through the handler: the mounted page's LIVE handler wins over the HEADLESS one;
+ *      neither → refused `unapplicable` ("open <surface> to apply it");
+ *   6. turns stale / missing record / broken protected span into "cannot apply" with a one-click
+ *      remedy (rule 11).
+ *
+ * Every outcome is a `Receipt` carrying the system's own sentence. `write` never throws.
+ *
+ * Who counts as a person: `person`, `menu` and `destination` (a destination send is a person's own
+ * click on "Send to …"). `agent`, `applet` and `automation` are not.
+ *
+ * Open-risk ruling — stream ops into an entity target: an entity write is ONE atomic save. Ops reach
+ * an entity target only when it is declared `patchable` (the ops are handed to the handler in one
+ * call and commit as one save); a non-patchable entity target refuses ops with the remedy "stream
+ * into the editor, then save". Op-by-op persistence into a record does not exist.
+ */
+
+/** Who is writing. `menu` and `destination` are a person's own act. */
+type WriteCaller = "person" | "agent" | "applet" | "automation" | "destination" | "menu";
+/** One text op for a `stream` (or `patchable`) target — the WidgetHandle op set. */
+interface WriteOp {
+    op: StreamOp;
+    /** The text the op inserts or replaces with. */
+    text?: string;
+    /** What `replace` / `insert_before` / `insert_after` / `patch` anchor on. */
+    find?: string;
+}
+interface WriteRequest {
+    surfaceName: string;
+    /** A write target name; `"<itemType>.<name>"` names an item's target. */
+    target: string;
+    itemType?: string;
+    /** Which item, by its declared identity values. Required for an item target. */
+    itemIdentity?: Record<string, string>;
+    /** A whole value. Exactly one of `value` / `ops`. */
+    value?: unknown;
+    /** Text ops (stream / patchable targets). */
+    ops?: readonly WriteOp[];
+    by: WriteCaller;
+    runId?: string;
+}
+/** What a handler receives: the request plus the declared target it resolved to. */
+interface WriteApplyRequest {
+    surfaceName: string;
+    /** The surface that declares the target (an ancestor when inherited). */
+    declaredOn: string;
+    target: WriteTarget;
+    item?: {
+        itemType: string;
+        identity: Record<string, string>;
+    };
+    value?: unknown;
+    ops?: readonly WriteOp[];
+    by: WriteCaller;
+    runId?: string;
+}
+/** Rule 11: the three "cannot apply" signals. */
+type CannotApply = "stale" | "missing-record" | "broken-span";
+/**
+ * A handler applies the write. Return nothing (or `{ status: "applied" }`) when it landed, or a
+ * `cannotApply` signal; THROWING an error whose `code` is a `CannotApply` signal means the same.
+ */
+type WriteHandlerResult = void | {
+    status: "applied";
+    sentence?: string;
+} | {
+    status: "cannot-apply";
+    cannotApply: CannotApply;
+    sentence?: string;
+    remedy?: string;
+};
+type WriteHandler = (request: WriteApplyRequest, signal: AbortSignal) => WriteHandlerResult | Promise<WriteHandlerResult>;
+/** Files a `queued` write for an organization's review. */
+interface WriteReviewPort {
+    file(request: WriteApplyRequest): Promise<{
+        sentence?: string;
+        remedy?: string;
+    } | void>;
+}
+interface WriteDoor {
+    write(request: WriteRequest, signal?: AbortSignal): Promise<Receipt>;
+    /** A feature's write handler that works with no page mounted. Refuses a second one for the same target. */
+    registerHeadless(surfaceName: string, targetName: string, handler: WriteHandler): () => void;
+    /** A mounted page's handler; wins over the headless one while registered. Returns unregister. */
+    registerLive(surfaceName: string, targetName: string, handler: WriteHandler): () => void;
+}
+
 /**
  * Surface Actions — the shapes (Applets CONTRACTS §6, FROZEN; exported here as a superset).
  *
@@ -245,6 +387,8 @@ interface ActionError {
     message: string;
     retryable: boolean;
     diagnostic?: string;
+    /** Superset: the one-click remedy a write door refusal names. */
+    remedy?: string;
 }
 /** CONTRACTS §0 `Result<T>`. */
 type ActionResult<T = unknown> = {
@@ -282,6 +426,17 @@ type MandateRunRequest = ({
     by: ActionCaller;
     policy: ActionPolicy;
 };
+/**
+ * CONTRACTS §0/§3 `RunRef` — the serializable identity of a started mandate run. A mandate
+ * Action answers with THIS, not the run's result: the result arrives later on the event stream
+ * `run:<requestId>` (or `IntelligencePort.result(ref)`). Same fields as `@ai-matrx/agents`'s
+ * `RunRef`, declared here because alchemy sits below agents and never imports it.
+ */
+interface MandateRunRef {
+    requestId: string;
+    conversationId: string;
+    mandateKey: string;
+}
 
 /**
  * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
@@ -301,7 +456,7 @@ type MandateRunRequest = ({
  *   PP-01a  `window` (host-rendered windows for a live preparation session)
  *   PP-13a  `transferKnobs` (organization default recipes)
  *
- * ALC-17 adds approvals/bodies/receipts.
+ *   ALC-17  `door` (the one write door), `review` (queued writes)
  *
  * ── Absent-port semantics ───────────────────────────────────────────────────
  *
@@ -337,6 +492,10 @@ type MandateRunRequest = ({
  *   approvals    absent → a policy "ask" Action started by an agent, applet or automation is refused
  *                         ("needs a person's approval"); a person's own click is the approval
  *                (`runs: "navigate"` goes through `overlay.navigate`; overlay absent → refused)
+ *   door         absent → write-target Actions dispatch to `pageActions` as before, and
+ *                         `Delivery.send` is refused with a remedy; bound → every such write goes
+ *                         through it and returns its receipt
+ *   review       absent → a write to a `queued` target is refused ("review isn't available here")
  *
  * Types only: this entry has no runtime code.
  */
@@ -490,13 +649,20 @@ interface AlchemyHostPorts {
     pageActions?: PageActionPort;
     /** Asks a person, in place, to approve an `ask` Action that an agent, applet or automation started. */
     approvals?: ApprovalPort;
+    /** `createWriteDoor(...)`: every write to a declared target lands here and returns a receipt. */
+    door?: WriteDoor;
+    /** Files a write to a `queued` target for an organization's review. */
+    review?: WriteReviewPort;
 }
 interface ServerActionPort {
     run(request: ServerActionRunRequest): Promise<ServerActionRunResponse>;
 }
 interface MandatePort {
-    /** Resolves with the run's result (a kind envelope or JSON); rejects with the system's sentence. */
-    run(request: MandateRunRequest): Promise<unknown>;
+    /**
+     * STARTS the run and resolves with its `RunRef` (CONTRACTS §3/§6) — never the run's result, which
+     * arrives later on `run:<requestId>` / `IntelligencePort.result(ref)`. Rejects with the system's sentence.
+     */
+    run(request: MandateRunRequest): Promise<MandateRunRef>;
 }
 interface ApprovalRequest {
     action: string;
@@ -630,4 +796,4 @@ interface ServerPort {
     call(operationId: string, input: Json, signal: AbortSignal): Promise<ServerResult>;
 }
 
-export type { AlchemyHostPorts, ApprovalPort, ApprovalRequest, AssetResolverPort, AuthResumePort, ContextArrangementKnob, DensityKnob, DiagnosticsPort, HostDialogsPort, I18nPort, IconResolverPort, IdentityPort, Json, KindValidatorPort, MandatePort, MenuKnobsPort, NotifyPort, OverlayHostPort, PageActionPort, PersistencePort, ServerActionPort, ServerPort, ServerResult, StorePort, TransferKnobsPort, TransportArtifact, TransportOutcome, TransportPort, WindowHandle, WindowOpenOptions, WindowPort, WindowSize };
+export type { AlchemyHostPorts, ApprovalPort, ApprovalRequest, AssetResolverPort, AuthResumePort, ContextArrangementKnob, DensityKnob, DiagnosticsPort, HostDialogsPort, I18nPort, IconResolverPort, IdentityPort, Json, KindValidatorPort, MandatePort, MenuKnobsPort, NotifyPort, OverlayHostPort, PageActionPort, PersistencePort, ServerActionPort, ServerPort, ServerResult, StorePort, TransferKnobsPort, TransportArtifact, TransportOutcome, TransportPort, WindowHandle, WindowOpenOptions, WindowPort, WindowSize, WriteDoor, WriteReviewPort };

package/dist/ports.d.ts

@@ -214,6 +214,148 @@ interface ClickTarget {
     host?: unknown;
 }
 
+/**
+ * Operate — the format and delivery contract (Matrx Alchemy CONTRACT §2.3, ALC-16).
+ *
+ * A format is an ADAPTER: `supports` is synchronous and loads nothing; `load` dynamically
+ * imports the engine the first time the format is chosen (print for rich-html/html/pdf/docx/
+ * epub, SheetJS for xlsx). Delivery accepts only a SEALED artifact, so the bytes previewed are
+ * the bytes copied, downloaded or sent.
+ */
+
+/** A reference to a declared write target (resolved by the one write door, ALC-17). */
+interface WriteTargetRef {
+    surfaceName?: string;
+    target: string;
+    item?: {
+        itemType: string;
+        identity: Record<string, string>;
+    };
+}
+/**
+ * Every write returns one (CONTRACT §2.3; the door is `createWriteDoor`, ALC-17). An applied
+ * receipt may carry a `warning` with its `fix` (rule 10: a person's kind mismatch warns, never refuses).
+ * A refusal's `reason` is a `WriteRefusalReason` (`./door`).
+ */
+type Receipt = {
+    status: "applied";
+    to: WriteTargetRef;
+    sentence: string;
+    warning?: string;
+    fix?: string;
+} | {
+    status: "queued";
+    to: WriteTargetRef;
+    sentence: string;
+    remedy: string;
+} | {
+    status: "refused";
+    to: WriteTargetRef;
+    reason: string;
+    sentence: string;
+    remedy: string;
+};
+
+/**
+ * THE ONE WRITE DOOR (Matrx Alchemy ALC-17; Applets CONTRACTS §6 "receipts through the one write door").
+ *
+ * Every write — a person's edit, a menu row, a destination send, an agent, an applet, an automation,
+ * an Action projected from a write target — lands through `door.write`. The door:
+ *
+ *   1. resolves the DECLARED write target (the surface's own, then its ancestors'); an undeclared
+ *      target is refused by name;
+ *   2. enforces the mode: `stream` takes ops from the target's `streamOps`; ops on any other target
+ *      need `patchable` (+ `updatesValue`); a value on a `stream` target is refused;
+ *   3. checks the kind (rule 10): a person's mismatch WARNS (the receipt is still applied, with a
+ *      `warning` and a `fix`); an agent's, applet's or automation's malformed write is REFUSED;
+ *   4. applies the policy: manual → a person only; ask → a person's own act is the approval, anyone
+ *      else asks through `approvals`; queued → filed through `review`; auto → applies;
+ *   5. applies through the handler: the mounted page's LIVE handler wins over the HEADLESS one;
+ *      neither → refused `unapplicable` ("open <surface> to apply it");
+ *   6. turns stale / missing record / broken protected span into "cannot apply" with a one-click
+ *      remedy (rule 11).
+ *
+ * Every outcome is a `Receipt` carrying the system's own sentence. `write` never throws.
+ *
+ * Who counts as a person: `person`, `menu` and `destination` (a destination send is a person's own
+ * click on "Send to …"). `agent`, `applet` and `automation` are not.
+ *
+ * Open-risk ruling — stream ops into an entity target: an entity write is ONE atomic save. Ops reach
+ * an entity target only when it is declared `patchable` (the ops are handed to the handler in one
+ * call and commit as one save); a non-patchable entity target refuses ops with the remedy "stream
+ * into the editor, then save". Op-by-op persistence into a record does not exist.
+ */
+
+/** Who is writing. `menu` and `destination` are a person's own act. */
+type WriteCaller = "person" | "agent" | "applet" | "automation" | "destination" | "menu";
+/** One text op for a `stream` (or `patchable`) target — the WidgetHandle op set. */
+interface WriteOp {
+    op: StreamOp;
+    /** The text the op inserts or replaces with. */
+    text?: string;
+    /** What `replace` / `insert_before` / `insert_after` / `patch` anchor on. */
+    find?: string;
+}
+interface WriteRequest {
+    surfaceName: string;
+    /** A write target name; `"<itemType>.<name>"` names an item's target. */
+    target: string;
+    itemType?: string;
+    /** Which item, by its declared identity values. Required for an item target. */
+    itemIdentity?: Record<string, string>;
+    /** A whole value. Exactly one of `value` / `ops`. */
+    value?: unknown;
+    /** Text ops (stream / patchable targets). */
+    ops?: readonly WriteOp[];
+    by: WriteCaller;
+    runId?: string;
+}
+/** What a handler receives: the request plus the declared target it resolved to. */
+interface WriteApplyRequest {
+    surfaceName: string;
+    /** The surface that declares the target (an ancestor when inherited). */
+    declaredOn: string;
+    target: WriteTarget;
+    item?: {
+        itemType: string;
+        identity: Record<string, string>;
+    };
+    value?: unknown;
+    ops?: readonly WriteOp[];
+    by: WriteCaller;
+    runId?: string;
+}
+/** Rule 11: the three "cannot apply" signals. */
+type CannotApply = "stale" | "missing-record" | "broken-span";
+/**
+ * A handler applies the write. Return nothing (or `{ status: "applied" }`) when it landed, or a
+ * `cannotApply` signal; THROWING an error whose `code` is a `CannotApply` signal means the same.
+ */
+type WriteHandlerResult = void | {
+    status: "applied";
+    sentence?: string;
+} | {
+    status: "cannot-apply";
+    cannotApply: CannotApply;
+    sentence?: string;
+    remedy?: string;
+};
+type WriteHandler = (request: WriteApplyRequest, signal: AbortSignal) => WriteHandlerResult | Promise<WriteHandlerResult>;
+/** Files a `queued` write for an organization's review. */
+interface WriteReviewPort {
+    file(request: WriteApplyRequest): Promise<{
+        sentence?: string;
+        remedy?: string;
+    } | void>;
+}
+interface WriteDoor {
+    write(request: WriteRequest, signal?: AbortSignal): Promise<Receipt>;
+    /** A feature's write handler that works with no page mounted. Refuses a second one for the same target. */
+    registerHeadless(surfaceName: string, targetName: string, handler: WriteHandler): () => void;
+    /** A mounted page's handler; wins over the headless one while registered. Returns unregister. */
+    registerLive(surfaceName: string, targetName: string, handler: WriteHandler): () => void;
+}
+
 /**
  * Surface Actions — the shapes (Applets CONTRACTS §6, FROZEN; exported here as a superset).
  *
@@ -245,6 +387,8 @@ interface ActionError {
     message: string;
     retryable: boolean;
     diagnostic?: string;
+    /** Superset: the one-click remedy a write door refusal names. */
+    remedy?: string;
 }
 /** CONTRACTS §0 `Result<T>`. */
 type ActionResult<T = unknown> = {
@@ -282,6 +426,17 @@ type MandateRunRequest = ({
     by: ActionCaller;
     policy: ActionPolicy;
 };
+/**
+ * CONTRACTS §0/§3 `RunRef` — the serializable identity of a started mandate run. A mandate
+ * Action answers with THIS, not the run's result: the result arrives later on the event stream
+ * `run:<requestId>` (or `IntelligencePort.result(ref)`). Same fields as `@ai-matrx/agents`'s
+ * `RunRef`, declared here because alchemy sits below agents and never imports it.
+ */
+interface MandateRunRef {
+    requestId: string;
+    conversationId: string;
+    mandateKey: string;
+}
 
 /**
  * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
@@ -301,7 +456,7 @@ type MandateRunRequest = ({
  *   PP-01a  `window` (host-rendered windows for a live preparation session)
  *   PP-13a  `transferKnobs` (organization default recipes)
  *
- * ALC-17 adds approvals/bodies/receipts.
+ *   ALC-17  `door` (the one write door), `review` (queued writes)
  *
  * ── Absent-port semantics ───────────────────────────────────────────────────
  *
@@ -337,6 +492,10 @@ type MandateRunRequest = ({
  *   approvals    absent → a policy "ask" Action started by an agent, applet or automation is refused
  *                         ("needs a person's approval"); a person's own click is the approval
  *                (`runs: "navigate"` goes through `overlay.navigate`; overlay absent → refused)
+ *   door         absent → write-target Actions dispatch to `pageActions` as before, and
+ *                         `Delivery.send` is refused with a remedy; bound → every such write goes
+ *                         through it and returns its receipt
+ *   review       absent → a write to a `queued` target is refused ("review isn't available here")
  *
  * Types only: this entry has no runtime code.
  */
@@ -490,13 +649,20 @@ interface AlchemyHostPorts {
     pageActions?: PageActionPort;
     /** Asks a person, in place, to approve an `ask` Action that an agent, applet or automation started. */
     approvals?: ApprovalPort;
+    /** `createWriteDoor(...)`: every write to a declared target lands here and returns a receipt. */
+    door?: WriteDoor;
+    /** Files a write to a `queued` target for an organization's review. */
+    review?: WriteReviewPort;
 }
 interface ServerActionPort {
     run(request: ServerActionRunRequest): Promise<ServerActionRunResponse>;
 }
 interface MandatePort {
-    /** Resolves with the run's result (a kind envelope or JSON); rejects with the system's sentence. */
-    run(request: MandateRunRequest): Promise<unknown>;
+    /**
+     * STARTS the run and resolves with its `RunRef` (CONTRACTS §3/§6) — never the run's result, which
+     * arrives later on `run:<requestId>` / `IntelligencePort.result(ref)`. Rejects with the system's sentence.
+     */
+    run(request: MandateRunRequest): Promise<MandateRunRef>;
 }
 interface ApprovalRequest {
     action: string;
@@ -630,4 +796,4 @@ interface ServerPort {
     call(operationId: string, input: Json, signal: AbortSignal): Promise<ServerResult>;
 }
 
-export type { AlchemyHostPorts, ApprovalPort, ApprovalRequest, AssetResolverPort, AuthResumePort, ContextArrangementKnob, DensityKnob, DiagnosticsPort, HostDialogsPort, I18nPort, IconResolverPort, IdentityPort, Json, KindValidatorPort, MandatePort, MenuKnobsPort, NotifyPort, OverlayHostPort, PageActionPort, PersistencePort, ServerActionPort, ServerPort, ServerResult, StorePort, TransferKnobsPort, TransportArtifact, TransportOutcome, TransportPort, WindowHandle, WindowOpenOptions, WindowPort, WindowSize };
+export type { AlchemyHostPorts, ApprovalPort, ApprovalRequest, AssetResolverPort, AuthResumePort, ContextArrangementKnob, DensityKnob, DiagnosticsPort, HostDialogsPort, I18nPort, IconResolverPort, IdentityPort, Json, KindValidatorPort, MandatePort, MenuKnobsPort, NotifyPort, OverlayHostPort, PageActionPort, PersistencePort, ServerActionPort, ServerPort, ServerResult, StorePort, TransferKnobsPort, TransportArtifact, TransportOutcome, TransportPort, WindowHandle, WindowOpenOptions, WindowPort, WindowSize, WriteDoor, WriteReviewPort };