@ai-matrx/alchemy 0.9.1 → 0.11.0

package/dist/index.d.cts

@@ -649,6 +649,125 @@ interface ClickTarget {
     host?: unknown;
 }
 
+/**
+ * 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>;
+}
+/** Why a write was refused. */
+type WriteRefusalReason = "undeclared" | "needs_item" | "malformed" | "declaration_broken" | "manual_only" | "needs_approval" | "declined" | "no_review" | "unapplicable" | "cannot_apply" | "cancelled" | "failed";
+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;
+}
+/** The declarations the door reads: a `DeclarationRegistry` satisfies it. */
+interface WriteDoorDeclarations {
+    get(surfaceName: string): {
+        writeTargets?: readonly WriteTarget[];
+        itemTypes?: readonly ItemType[];
+    } | undefined;
+    /** Parent chain, root first (the registry's `ancestry`). Absent = no inheritance. */
+    ancestry?(surfaceName: string): string[];
+}
+type WriteDoorPorts = Pick<AlchemyHostPorts, "diagnostics" | "kinds" | "approvals" | "review">;
+declare class DuplicateWriteHandlerError extends Error {
+    constructor(surfaceName: string, targetName: string);
+}
+declare function createWriteDoor(options: {
+    ports: WriteDoorPorts;
+    declarations: WriteDoorDeclarations;
+}): WriteDoor;
+
 /**
  * Surface Actions — the shapes (Applets CONTRACTS §6, FROZEN; exported here as a superset).
  *
@@ -680,6 +799,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> = {
@@ -717,6 +838,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).
@@ -736,7 +868,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 ───────────────────────────────────────────────────
  *
@@ -772,6 +904,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.
  */
@@ -925,13 +1061,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;
@@ -1079,7 +1222,7 @@ type Notice = {
     sentence: string;
     remedy: string;
 };
-/** A reference to a declared write target (the write door arrives in ALC-17). */
+/** A reference to a declared write target (resolved by the one write door, ALC-17). */
 interface WriteTargetRef {
     surfaceName?: string;
     target: string;
@@ -1154,11 +1297,17 @@ declare const sealed: unique symbol;
 type SealedArtifact = Artifact & {
     readonly [sealed]: true;
 };
-/** Every send returns one (the write door's receipt shape, CONTRACT §2.3; the door itself is ALC-17). */
+/**
+ * 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;
@@ -1182,7 +1331,7 @@ interface Delivery {
         html?: boolean;
     }): Promise<DeliveryOutcome>;
     download(artifact: SealedArtifact, signal: AbortSignal): Promise<DeliveryOutcome>;
-    /** Sends the sealed bytes through the write door (ALC-17). Without a door: refused, with a remedy. */
+    /** Sends the sealed bytes through the write door (`by: "destination"`). Without a door: refused, with a remedy. */
     send(artifact: SealedArtifact, to: WriteTargetRef, via: "destination"): Promise<Receipt>;
 }
 
@@ -1245,19 +1394,13 @@ declare function openPreparation(source: Source | Payload, scope: TransferScope,
 declare function sealDraft(draft: Draft, format: string, options: FormatOptions, signal: AbortSignal, formats?: readonly FormatAdapter[]): Promise<SealedArtifact>;
 /**
  * The one delivery. `transport` defaults to the browser (clipboard + download link); a non-browser
- * host binds its own (`TransportPort`). `send` needs the write door (ALC-17): without one it is
+ * host binds its own (`TransportPort`). `send` goes through the one write door (ALC-17): without one it is
  * refused with a remedy, never faked.
  */
 declare function createDelivery(ports?: {
     transport?: Transport;
-    door?: {
-        apply(request: {
-            to: WriteTargetRef;
-            value: unknown;
-            origin: "user";
-            via: "destination";
-        }): Promise<Receipt>;
-    };
+    /** The one write door (`createWriteDoor`). Absent → `send` is refused with a remedy. */
+    door?: Pick<WriteDoor, "write">;
 }): Delivery;
 
 /**
@@ -1436,4 +1579,4 @@ declare function setPersonDefaultRecipe(ports: Pick<AlchemyHostPorts, "persisten
     [key: string]: Json;
 } | null): Promise<void>;
 
-export { type AgentPayloadEnvironment, type AgentPayloadInput, type AiPreparation, type Artifact, type BoundAllMatching, type BuiltInFormatId, type CapturedAllMatching, type CapturedSource, type Column, ContentTransferError, type Coverage, type Delivery, type DeliveryOutcome, type Draft, EMPTY_STRUCTURE, type ExportPage, type ExportProjection, FORMAT_ADAPTERS, type FormatAdapter, type FormatEngine, type FormatOptions, type Json$2 as Json, type NodeLimit, type NormalizeTransferJsonOptions, type Notice, type Omission, type OutputSpan, type PageAction, type Payload, type PreparationOptions, type PreparationSession, type QuerySnapshot, type RawSnapshot, type Receipt, type RecipeOrigin, type ResolvedRecipe, type SealedArtifact, type Section, type SectionLayout, type ServerOperation, type Snapshot, type Source, type SpanMap, type StructureRecipe, type SurfaceHandle, TRANSFER_DEFAULT_RECIPE_SETTING, type TransferLimits, type TransferOperation, type TransferOutcome, type TransferPreferenceOverrides, type TransferPreferences, type TransferScope, type TransferSurfaceDeclaration, type TransferTarget, type Transform, type Transport, type WriteTargetRef, agentPayloadWithSpans, applyJsonStructure, applySectionSelection, applySectionStructure, applyStructureToJson, applyTransferLimits, assembleAgentPayload, buildAgentPayload, capture, collectAllMatching, concretePointers, createBrowserTransport, createDelivery, createDraft, createSurfaceTransferHandle, deriveDraft, directSource, displayPath, editDraft, eligibleFormats, exportedColumns, extensionForLanguage, fenceJsonBlock, formatAdapter, isProseSection, isSealed, joinPointer, jsonSize, jsonTextSpans, nodeChars, normalizeTransferJson, offsetSpans, openPreparation, outputPointer, patternBelow, patternCovers, patternMatches, pointerSegments, projectSnapshot, readTransferCell, recipeKey, reduceJson, refreshDraft, resetDraft, resolveDefaultRecipe, resolveTransferPreferences, resolveTransferRegistry, sealArtifact, sealDraft, sealTransferArtifact, sectionLayout, serialize, setPersonDefaultRecipe, sourceChanged, spanMap, stubText, transformRows, undoDraft };
+export { type AgentPayloadEnvironment, type AgentPayloadInput, type AiPreparation, type Artifact, type BoundAllMatching, type BuiltInFormatId, type CannotApply, type CapturedAllMatching, type CapturedSource, type Column, ContentTransferError, type Coverage, type Delivery, type DeliveryOutcome, type Draft, DuplicateWriteHandlerError, EMPTY_STRUCTURE, type ExportPage, type ExportProjection, FORMAT_ADAPTERS, type FormatAdapter, type FormatEngine, type FormatOptions, type Json$2 as Json, type NodeLimit, type NormalizeTransferJsonOptions, type Notice, type Omission, type OutputSpan, type PageAction, type Payload, type PreparationOptions, type PreparationSession, type QuerySnapshot, type RawSnapshot, type Receipt, type RecipeOrigin, type ResolvedRecipe, type SealedArtifact, type Section, type SectionLayout, type ServerOperation, type Snapshot, type Source, type SpanMap, type StructureRecipe, type SurfaceHandle, TRANSFER_DEFAULT_RECIPE_SETTING, type TransferLimits, type TransferOperation, type TransferOutcome, type TransferPreferenceOverrides, type TransferPreferences, type TransferScope, type TransferSurfaceDeclaration, type TransferTarget, type Transform, type Transport, type WriteApplyRequest, type WriteCaller, type WriteDoor, type WriteDoorDeclarations, type WriteDoorPorts, type WriteHandler, type WriteHandlerResult, type WriteOp, type WriteRefusalReason, type WriteRequest, type WriteReviewPort, type WriteTargetRef, agentPayloadWithSpans, applyJsonStructure, applySectionSelection, applySectionStructure, applyStructureToJson, applyTransferLimits, assembleAgentPayload, buildAgentPayload, capture, collectAllMatching, concretePointers, createBrowserTransport, createDelivery, createDraft, createSurfaceTransferHandle, createWriteDoor, deriveDraft, directSource, displayPath, editDraft, eligibleFormats, exportedColumns, extensionForLanguage, fenceJsonBlock, formatAdapter, isProseSection, isSealed, joinPointer, jsonSize, jsonTextSpans, nodeChars, normalizeTransferJson, offsetSpans, openPreparation, outputPointer, patternBelow, patternCovers, patternMatches, pointerSegments, projectSnapshot, readTransferCell, recipeKey, reduceJson, refreshDraft, resetDraft, resolveDefaultRecipe, resolveTransferPreferences, resolveTransferRegistry, sealArtifact, sealDraft, sealTransferArtifact, sectionLayout, serialize, setPersonDefaultRecipe, sourceChanged, spanMap, stubText, transformRows, undoDraft };

package/dist/index.d.ts

@@ -649,6 +649,125 @@ interface ClickTarget {
     host?: unknown;
 }
 
+/**
+ * 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>;
+}
+/** Why a write was refused. */
+type WriteRefusalReason = "undeclared" | "needs_item" | "malformed" | "declaration_broken" | "manual_only" | "needs_approval" | "declined" | "no_review" | "unapplicable" | "cannot_apply" | "cancelled" | "failed";
+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;
+}
+/** The declarations the door reads: a `DeclarationRegistry` satisfies it. */
+interface WriteDoorDeclarations {
+    get(surfaceName: string): {
+        writeTargets?: readonly WriteTarget[];
+        itemTypes?: readonly ItemType[];
+    } | undefined;
+    /** Parent chain, root first (the registry's `ancestry`). Absent = no inheritance. */
+    ancestry?(surfaceName: string): string[];
+}
+type WriteDoorPorts = Pick<AlchemyHostPorts, "diagnostics" | "kinds" | "approvals" | "review">;
+declare class DuplicateWriteHandlerError extends Error {
+    constructor(surfaceName: string, targetName: string);
+}
+declare function createWriteDoor(options: {
+    ports: WriteDoorPorts;
+    declarations: WriteDoorDeclarations;
+}): WriteDoor;
+
 /**
  * Surface Actions — the shapes (Applets CONTRACTS §6, FROZEN; exported here as a superset).
  *
@@ -680,6 +799,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> = {
@@ -717,6 +838,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).
@@ -736,7 +868,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 ───────────────────────────────────────────────────
  *
@@ -772,6 +904,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.
  */
@@ -925,13 +1061,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;
@@ -1079,7 +1222,7 @@ type Notice = {
     sentence: string;
     remedy: string;
 };
-/** A reference to a declared write target (the write door arrives in ALC-17). */
+/** A reference to a declared write target (resolved by the one write door, ALC-17). */
 interface WriteTargetRef {
     surfaceName?: string;
     target: string;
@@ -1154,11 +1297,17 @@ declare const sealed: unique symbol;
 type SealedArtifact = Artifact & {
     readonly [sealed]: true;
 };
-/** Every send returns one (the write door's receipt shape, CONTRACT §2.3; the door itself is ALC-17). */
+/**
+ * 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;
@@ -1182,7 +1331,7 @@ interface Delivery {
         html?: boolean;
     }): Promise<DeliveryOutcome>;
     download(artifact: SealedArtifact, signal: AbortSignal): Promise<DeliveryOutcome>;
-    /** Sends the sealed bytes through the write door (ALC-17). Without a door: refused, with a remedy. */
+    /** Sends the sealed bytes through the write door (`by: "destination"`). Without a door: refused, with a remedy. */
     send(artifact: SealedArtifact, to: WriteTargetRef, via: "destination"): Promise<Receipt>;
 }
 
@@ -1245,19 +1394,13 @@ declare function openPreparation(source: Source | Payload, scope: TransferScope,
 declare function sealDraft(draft: Draft, format: string, options: FormatOptions, signal: AbortSignal, formats?: readonly FormatAdapter[]): Promise<SealedArtifact>;
 /**
  * The one delivery. `transport` defaults to the browser (clipboard + download link); a non-browser
- * host binds its own (`TransportPort`). `send` needs the write door (ALC-17): without one it is
+ * host binds its own (`TransportPort`). `send` goes through the one write door (ALC-17): without one it is
  * refused with a remedy, never faked.
  */
 declare function createDelivery(ports?: {
     transport?: Transport;
-    door?: {
-        apply(request: {
-            to: WriteTargetRef;
-            value: unknown;
-            origin: "user";
-            via: "destination";
-        }): Promise<Receipt>;
-    };
+    /** The one write door (`createWriteDoor`). Absent → `send` is refused with a remedy. */
+    door?: Pick<WriteDoor, "write">;
 }): Delivery;
 
 /**
@@ -1436,4 +1579,4 @@ declare function setPersonDefaultRecipe(ports: Pick<AlchemyHostPorts, "persisten
     [key: string]: Json;
 } | null): Promise<void>;
 
-export { type AgentPayloadEnvironment, type AgentPayloadInput, type AiPreparation, type Artifact, type BoundAllMatching, type BuiltInFormatId, type CapturedAllMatching, type CapturedSource, type Column, ContentTransferError, type Coverage, type Delivery, type DeliveryOutcome, type Draft, EMPTY_STRUCTURE, type ExportPage, type ExportProjection, FORMAT_ADAPTERS, type FormatAdapter, type FormatEngine, type FormatOptions, type Json$2 as Json, type NodeLimit, type NormalizeTransferJsonOptions, type Notice, type Omission, type OutputSpan, type PageAction, type Payload, type PreparationOptions, type PreparationSession, type QuerySnapshot, type RawSnapshot, type Receipt, type RecipeOrigin, type ResolvedRecipe, type SealedArtifact, type Section, type SectionLayout, type ServerOperation, type Snapshot, type Source, type SpanMap, type StructureRecipe, type SurfaceHandle, TRANSFER_DEFAULT_RECIPE_SETTING, type TransferLimits, type TransferOperation, type TransferOutcome, type TransferPreferenceOverrides, type TransferPreferences, type TransferScope, type TransferSurfaceDeclaration, type TransferTarget, type Transform, type Transport, type WriteTargetRef, agentPayloadWithSpans, applyJsonStructure, applySectionSelection, applySectionStructure, applyStructureToJson, applyTransferLimits, assembleAgentPayload, buildAgentPayload, capture, collectAllMatching, concretePointers, createBrowserTransport, createDelivery, createDraft, createSurfaceTransferHandle, deriveDraft, directSource, displayPath, editDraft, eligibleFormats, exportedColumns, extensionForLanguage, fenceJsonBlock, formatAdapter, isProseSection, isSealed, joinPointer, jsonSize, jsonTextSpans, nodeChars, normalizeTransferJson, offsetSpans, openPreparation, outputPointer, patternBelow, patternCovers, patternMatches, pointerSegments, projectSnapshot, readTransferCell, recipeKey, reduceJson, refreshDraft, resetDraft, resolveDefaultRecipe, resolveTransferPreferences, resolveTransferRegistry, sealArtifact, sealDraft, sealTransferArtifact, sectionLayout, serialize, setPersonDefaultRecipe, sourceChanged, spanMap, stubText, transformRows, undoDraft };
+export { type AgentPayloadEnvironment, type AgentPayloadInput, type AiPreparation, type Artifact, type BoundAllMatching, type BuiltInFormatId, type CannotApply, type CapturedAllMatching, type CapturedSource, type Column, ContentTransferError, type Coverage, type Delivery, type DeliveryOutcome, type Draft, DuplicateWriteHandlerError, EMPTY_STRUCTURE, type ExportPage, type ExportProjection, FORMAT_ADAPTERS, type FormatAdapter, type FormatEngine, type FormatOptions, type Json$2 as Json, type NodeLimit, type NormalizeTransferJsonOptions, type Notice, type Omission, type OutputSpan, type PageAction, type Payload, type PreparationOptions, type PreparationSession, type QuerySnapshot, type RawSnapshot, type Receipt, type RecipeOrigin, type ResolvedRecipe, type SealedArtifact, type Section, type SectionLayout, type ServerOperation, type Snapshot, type Source, type SpanMap, type StructureRecipe, type SurfaceHandle, TRANSFER_DEFAULT_RECIPE_SETTING, type TransferLimits, type TransferOperation, type TransferOutcome, type TransferPreferenceOverrides, type TransferPreferences, type TransferScope, type TransferSurfaceDeclaration, type TransferTarget, type Transform, type Transport, type WriteApplyRequest, type WriteCaller, type WriteDoor, type WriteDoorDeclarations, type WriteDoorPorts, type WriteHandler, type WriteHandlerResult, type WriteOp, type WriteRefusalReason, type WriteRequest, type WriteReviewPort, type WriteTargetRef, agentPayloadWithSpans, applyJsonStructure, applySectionSelection, applySectionStructure, applyStructureToJson, applyTransferLimits, assembleAgentPayload, buildAgentPayload, capture, collectAllMatching, concretePointers, createBrowserTransport, createDelivery, createDraft, createSurfaceTransferHandle, createWriteDoor, deriveDraft, directSource, displayPath, editDraft, eligibleFormats, exportedColumns, extensionForLanguage, fenceJsonBlock, formatAdapter, isProseSection, isSealed, joinPointer, jsonSize, jsonTextSpans, nodeChars, normalizeTransferJson, offsetSpans, openPreparation, outputPointer, patternBelow, patternCovers, patternMatches, pointerSegments, projectSnapshot, readTransferCell, recipeKey, reduceJson, refreshDraft, resetDraft, resolveDefaultRecipe, resolveTransferPreferences, resolveTransferRegistry, sealArtifact, sealDraft, sealTransferArtifact, sectionLayout, serialize, setPersonDefaultRecipe, sourceChanged, spanMap, stubText, transformRows, undoDraft };