@ai-matrx/alchemy 0.9.1 → 0.11.0

package/dist/actions.d.cts

@@ -250,6 +250,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).
  *
@@ -288,6 +430,8 @@ interface ActionOrigin {
     declaredBy?: ActionDeclaredBy;
     /** `ui.ui_surface_action.code_ref`: the code item a database Action names. */
     codeRef?: string;
+    /** The source row's organization (an organization extension applies only to its members). */
+    organizationId?: string;
 }
 interface ActionDeclaration {
     /** The Action's unique id within its chain (alchemy's `Action.id`). */
@@ -336,6 +480,8 @@ interface ActionInfo {
     target?: string;
     updatesValue?: string;
     itemType?: string;
+    /** Where it came from. "write-target" Actions go through the write door when one is bound (ALC-17). */
+    source?: ActionOrigin["source"];
 }
 interface ActionContext {
     runId: string;
@@ -350,6 +496,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> = {
@@ -387,6 +535,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;
+}
 /**
  * CONTRACTS §6 `SurfacePort` — the surface runtime as the frame sees it. Types
  * only here; the in-page host is AP-0's.
@@ -424,7 +583,7 @@ interface SurfacePort {
  *   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 ───────────────────────────────────────────────────
  *
@@ -460,6 +619,10 @@ interface SurfacePort {
  *   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.
  */
@@ -613,13 +776,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;
@@ -1105,6 +1275,11 @@ interface SurfaceActionRow {
     code_ref: string | null;
     declared_by: ActionDeclaredBy;
     sort_order: number;
+    /**
+     * The row's organization. A `declared_by='database'` row on a surface outside `applets/` is that
+     * organization's EXTENSION and applies only to its members (`readSurfaceChain`, aidream `visible_actions`).
+     */
+    organization_id?: string | null;
 }
 /** A declared write target → an Action that runs on the page. */
 declare function writeTargetToAction(target: WriteTarget): ActionDeclaration;
@@ -1140,21 +1315,32 @@ declare function resolveActionChain(chain: readonly ActionChainLink[], options?:
  *
  * Dispatch by `runs`:
  *   "server"   → `ports.serverActions.run({ name: target, input, by, surface_name, policy })`
- *   "mandate"  → `ports.mandates.run({ alias: target, variables, by, policy })`
+ *   "mandate"  → `ports.mandates.run({ alias: target, variables, by, policy })` — answers with the
+ *                started run's `MandateRunRef`; the result streams later on `run:<requestId>`
  *   "navigate" → `ports.overlay.navigate(target)` with `{param}` filled from the input
  *   "page"     → `ports.pageActions.dispatch(name, input, context)`
  * A port the host did not bind means that capability is ABSENT: the run is
  * refused with a sentence, never stubbed (ports rule).
  *
+ * Write targets (ALC-17): an Action projected from a declared write target (`source: "write-target"`)
+ * goes through `ports.door.write` when a door is bound — the door applies the target's own policy
+ * (manual / ask / queued / auto) and its receipt becomes the result (`applied` / `queued` → ok with
+ * the receipt; refused → an error whose code is the refusal reason and whose `remedy` is the door's).
+ * Without a door it dispatches to `pageActions` as before.
+ *
  * Never throws: every outcome is a `Result` whose error message is the
  * system's own sentence.
  */
 
-type SurfaceActionPorts = Pick<AlchemyHostPorts, "diagnostics" | "serverActions" | "mandates" | "pageActions" | "overlay" | "approvals">;
+type SurfaceActionPorts = Pick<AlchemyHostPorts, "diagnostics" | "serverActions" | "mandates" | "pageActions" | "overlay" | "approvals" | "door">;
 interface RunSurfaceActionOptions {
     runId?: string;
     viewerId?: string | null;
     signal?: AbortSignal;
+    /** Which item a write-target Action writes into (by its declared identity values). */
+    itemIdentity?: Record<string, string>;
+    /** Text edits for a stream or patchable write target, instead of the input as the whole value. */
+    ops?: readonly WriteOp[];
 }
 /** Fill `{param}` placeholders from the input object. Returns the names it could not fill. */
 declare function fillActionTarget(template: string, input: unknown): {
@@ -1168,4 +1354,4 @@ declare function fillActionTarget(template: string, input: unknown): {
 declare function refuseCaller(info: Pick<ActionInfo, "name" | "label" | "policy" | "triggeredBy">, by: ActionCaller): ActionError | null;
 declare function runSurfaceAction(info: ActionInfo, input: unknown, by: ActionCaller, ports: SurfaceActionPorts, options?: RunSurfaceActionOptions): Promise<ActionResult<unknown>>;
 
-export { ACTION_CALLERS, ACTION_CATEGORIES, ACTION_POLICIES, ACTION_RUNS, APPLET_CATEGORY, type Action, type ActionCaller, type ActionCategory, type ActionChainLink, type ActionContext, type ActionDeclaration, type ActionDeclaredBy, type ActionError, type ActionInfo, type ActionInput, type ActionOrigin, type ActionPolicy, type ActionProvider, type ActionRegistry, type ActionRegistryOptions, type ActionResult, type ActionRunContext, type ActionRuns, type ActionSection, type ActionWriteMode, type ClickTarget, type ClickTargetInput, type ClientToolRow, DEFAULT_TRIGGERED_BY, DuplicateActionError, DuplicateProviderError, type Eligibility, type MandateRunRequest, type ProjectedReads, type ProjectionSource, type ReadOmission, type ResolveRestriction, type ResolvedAction, type RunActionOptions, type RunResult, type RunSurfaceActionOptions, type ServerActionRunRequest, type ServerActionRunResponse, type SurfaceActionPorts, type SurfaceActionRow, type SurfacePort, UNIVERSAL_VERBS, type UniversalVerb, alwaysEligible, clientToolToAction, computeEligibility, createActionRegistry, createClickTarget, createProjectedReads, fillActionTarget, projectValues, refuseCaller, resolveActionChain, runAction, runSurfaceAction, staticActionProvider, surfaceActionRowToAction, toActionInfo, writeTargetToAction };
+export { ACTION_CALLERS, ACTION_CATEGORIES, ACTION_POLICIES, ACTION_RUNS, APPLET_CATEGORY, type Action, type ActionCaller, type ActionCategory, type ActionChainLink, type ActionContext, type ActionDeclaration, type ActionDeclaredBy, type ActionError, type ActionInfo, type ActionInput, type ActionOrigin, type ActionPolicy, type ActionProvider, type ActionRegistry, type ActionRegistryOptions, type ActionResult, type ActionRunContext, type ActionRuns, type ActionSection, type ActionWriteMode, type ClickTarget, type ClickTargetInput, type ClientToolRow, DEFAULT_TRIGGERED_BY, DuplicateActionError, DuplicateProviderError, type Eligibility, type MandateRunRef, type MandateRunRequest, type ProjectedReads, type ProjectionSource, type ReadOmission, type ResolveRestriction, type ResolvedAction, type RunActionOptions, type RunResult, type RunSurfaceActionOptions, type ServerActionRunRequest, type ServerActionRunResponse, type SurfaceActionPorts, type SurfaceActionRow, type SurfacePort, UNIVERSAL_VERBS, type UniversalVerb, alwaysEligible, clientToolToAction, computeEligibility, createActionRegistry, createClickTarget, createProjectedReads, fillActionTarget, projectValues, refuseCaller, resolveActionChain, runAction, runSurfaceAction, staticActionProvider, surfaceActionRowToAction, toActionInfo, writeTargetToAction };

package/dist/actions.d.ts

@@ -250,6 +250,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).
  *
@@ -288,6 +430,8 @@ interface ActionOrigin {
     declaredBy?: ActionDeclaredBy;
     /** `ui.ui_surface_action.code_ref`: the code item a database Action names. */
     codeRef?: string;
+    /** The source row's organization (an organization extension applies only to its members). */
+    organizationId?: string;
 }
 interface ActionDeclaration {
     /** The Action's unique id within its chain (alchemy's `Action.id`). */
@@ -336,6 +480,8 @@ interface ActionInfo {
     target?: string;
     updatesValue?: string;
     itemType?: string;
+    /** Where it came from. "write-target" Actions go through the write door when one is bound (ALC-17). */
+    source?: ActionOrigin["source"];
 }
 interface ActionContext {
     runId: string;
@@ -350,6 +496,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> = {
@@ -387,6 +535,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;
+}
 /**
  * CONTRACTS §6 `SurfacePort` — the surface runtime as the frame sees it. Types
  * only here; the in-page host is AP-0's.
@@ -424,7 +583,7 @@ interface SurfacePort {
  *   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 ───────────────────────────────────────────────────
  *
@@ -460,6 +619,10 @@ interface SurfacePort {
  *   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.
  */
@@ -613,13 +776,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;
@@ -1105,6 +1275,11 @@ interface SurfaceActionRow {
     code_ref: string | null;
     declared_by: ActionDeclaredBy;
     sort_order: number;
+    /**
+     * The row's organization. A `declared_by='database'` row on a surface outside `applets/` is that
+     * organization's EXTENSION and applies only to its members (`readSurfaceChain`, aidream `visible_actions`).
+     */
+    organization_id?: string | null;
 }
 /** A declared write target → an Action that runs on the page. */
 declare function writeTargetToAction(target: WriteTarget): ActionDeclaration;
@@ -1140,21 +1315,32 @@ declare function resolveActionChain(chain: readonly ActionChainLink[], options?:
  *
  * Dispatch by `runs`:
  *   "server"   → `ports.serverActions.run({ name: target, input, by, surface_name, policy })`
- *   "mandate"  → `ports.mandates.run({ alias: target, variables, by, policy })`
+ *   "mandate"  → `ports.mandates.run({ alias: target, variables, by, policy })` — answers with the
+ *                started run's `MandateRunRef`; the result streams later on `run:<requestId>`
  *   "navigate" → `ports.overlay.navigate(target)` with `{param}` filled from the input
  *   "page"     → `ports.pageActions.dispatch(name, input, context)`
  * A port the host did not bind means that capability is ABSENT: the run is
  * refused with a sentence, never stubbed (ports rule).
  *
+ * Write targets (ALC-17): an Action projected from a declared write target (`source: "write-target"`)
+ * goes through `ports.door.write` when a door is bound — the door applies the target's own policy
+ * (manual / ask / queued / auto) and its receipt becomes the result (`applied` / `queued` → ok with
+ * the receipt; refused → an error whose code is the refusal reason and whose `remedy` is the door's).
+ * Without a door it dispatches to `pageActions` as before.
+ *
  * Never throws: every outcome is a `Result` whose error message is the
  * system's own sentence.
  */
 
-type SurfaceActionPorts = Pick<AlchemyHostPorts, "diagnostics" | "serverActions" | "mandates" | "pageActions" | "overlay" | "approvals">;
+type SurfaceActionPorts = Pick<AlchemyHostPorts, "diagnostics" | "serverActions" | "mandates" | "pageActions" | "overlay" | "approvals" | "door">;
 interface RunSurfaceActionOptions {
     runId?: string;
     viewerId?: string | null;
     signal?: AbortSignal;
+    /** Which item a write-target Action writes into (by its declared identity values). */
+    itemIdentity?: Record<string, string>;
+    /** Text edits for a stream or patchable write target, instead of the input as the whole value. */
+    ops?: readonly WriteOp[];
 }
 /** Fill `{param}` placeholders from the input object. Returns the names it could not fill. */
 declare function fillActionTarget(template: string, input: unknown): {
@@ -1168,4 +1354,4 @@ declare function fillActionTarget(template: string, input: unknown): {
 declare function refuseCaller(info: Pick<ActionInfo, "name" | "label" | "policy" | "triggeredBy">, by: ActionCaller): ActionError | null;
 declare function runSurfaceAction(info: ActionInfo, input: unknown, by: ActionCaller, ports: SurfaceActionPorts, options?: RunSurfaceActionOptions): Promise<ActionResult<unknown>>;
 
-export { ACTION_CALLERS, ACTION_CATEGORIES, ACTION_POLICIES, ACTION_RUNS, APPLET_CATEGORY, type Action, type ActionCaller, type ActionCategory, type ActionChainLink, type ActionContext, type ActionDeclaration, type ActionDeclaredBy, type ActionError, type ActionInfo, type ActionInput, type ActionOrigin, type ActionPolicy, type ActionProvider, type ActionRegistry, type ActionRegistryOptions, type ActionResult, type ActionRunContext, type ActionRuns, type ActionSection, type ActionWriteMode, type ClickTarget, type ClickTargetInput, type ClientToolRow, DEFAULT_TRIGGERED_BY, DuplicateActionError, DuplicateProviderError, type Eligibility, type MandateRunRequest, type ProjectedReads, type ProjectionSource, type ReadOmission, type ResolveRestriction, type ResolvedAction, type RunActionOptions, type RunResult, type RunSurfaceActionOptions, type ServerActionRunRequest, type ServerActionRunResponse, type SurfaceActionPorts, type SurfaceActionRow, type SurfacePort, UNIVERSAL_VERBS, type UniversalVerb, alwaysEligible, clientToolToAction, computeEligibility, createActionRegistry, createClickTarget, createProjectedReads, fillActionTarget, projectValues, refuseCaller, resolveActionChain, runAction, runSurfaceAction, staticActionProvider, surfaceActionRowToAction, toActionInfo, writeTargetToAction };
+export { ACTION_CALLERS, ACTION_CATEGORIES, ACTION_POLICIES, ACTION_RUNS, APPLET_CATEGORY, type Action, type ActionCaller, type ActionCategory, type ActionChainLink, type ActionContext, type ActionDeclaration, type ActionDeclaredBy, type ActionError, type ActionInfo, type ActionInput, type ActionOrigin, type ActionPolicy, type ActionProvider, type ActionRegistry, type ActionRegistryOptions, type ActionResult, type ActionRunContext, type ActionRuns, type ActionSection, type ActionWriteMode, type ClickTarget, type ClickTargetInput, type ClientToolRow, DEFAULT_TRIGGERED_BY, DuplicateActionError, DuplicateProviderError, type Eligibility, type MandateRunRef, type MandateRunRequest, type ProjectedReads, type ProjectionSource, type ReadOmission, type ResolveRestriction, type ResolvedAction, type RunActionOptions, type RunResult, type RunSurfaceActionOptions, type ServerActionRunRequest, type ServerActionRunResponse, type SurfaceActionPorts, type SurfaceActionRow, type SurfacePort, UNIVERSAL_VERBS, type UniversalVerb, alwaysEligible, clientToolToAction, computeEligibility, createActionRegistry, createClickTarget, createProjectedReads, fillActionTarget, projectValues, refuseCaller, resolveActionChain, runAction, runSurfaceAction, staticActionProvider, surfaceActionRowToAction, toActionInfo, writeTargetToAction };