@ai-matrx/alchemy 0.9.1 → 0.11.0

package/dist/menu.d.cts

@@ -378,6 +378,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).
  *
@@ -409,6 +551,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> = {
@@ -446,6 +590,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).
@@ -465,7 +620,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 ───────────────────────────────────────────────────
  *
@@ -501,6 +656,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.
  */
@@ -654,13 +813,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;

package/dist/menu.d.ts

@@ -378,6 +378,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).
  *
@@ -409,6 +551,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> = {
@@ -446,6 +590,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).
@@ -465,7 +620,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 ───────────────────────────────────────────────────
  *
@@ -501,6 +656,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.
  */
@@ -654,13 +813,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;

package/dist/operate-server.d.cts

@@ -16,7 +16,7 @@
  *   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 ───────────────────────────────────────────────────
  *
@@ -52,6 +52,10 @@
  *   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.
  */

package/dist/operate-server.d.ts

@@ -16,7 +16,7 @@
  *   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 ───────────────────────────────────────────────────
  *
@@ -52,6 +52,10 @@
  *   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.
  */