@ai-matrx/alchemy 0.8.60 → 0.10.1

package/dist/actions.d.cts

@@ -250,6 +250,308 @@ 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).
+ *
+ * An Action is one thing a surface can have done to it, by a person, an agent,
+ * an applet or an automation: a write target, a client tool, a Kind Action or a
+ * row in `ui.ui_surface_action`. All of them project onto `ActionDeclaration`
+ * (`./declarations.ts`) and run through ONE runner (`./surface-run.ts`). There is
+ * never a second registry: `name` IS the alchemy action id, and `category`
+ * defaults to "applet" in alchemy's closed `ActionCategory` union.
+ *
+ * Types only — no runtime code, no React, no `@ai-matrx/agents`. `/ports`
+ * imports from here, so this file imports nothing but local types.
+ */
+
+/** Who started a run. */
+type ActionCaller = "person" | "agent" | "applet" | "automation";
+/** Where a run goes: the page's own handler, an aidream server action, a mandate, or a route. */
+type ActionRuns = "page" | "server" | "mandate" | "navigate";
+/** Who may run it without a click: "manual" = only a person; "ask" = proposed first; "auto" = runs. */
+type ActionPolicy = "ask" | "auto" | "manual";
+/** A registered kind slug (`KindRef`, content-ir) or an inline JSON Schema. */
+type ActionInput = string | {
+    jsonSchema: object;
+};
+/** Who authored the row (`ui.ui_surface*.declared_by`). Code sync touches only "code". */
+type ActionDeclaredBy = "code" | "database";
+/** The write-target modes (WriteMode), kept losslessly. CONTRACTS §6 names three; "stream" is the superset. */
+type ActionWriteMode = "ui" | "draft" | "entity" | "stream";
+/** Where the Action came from — superset field so a projection loses nothing. */
+interface ActionOrigin {
+    source: "write-target" | "client-tool" | "surface-action";
+    surfaceName?: string;
+    surfaceId?: string;
+    /** The source row's id, when it came from a row. */
+    id?: string;
+    declaredBy?: ActionDeclaredBy;
+    /** `ui.ui_surface_action.code_ref`: the code item a database Action names. */
+    codeRef?: string;
+}
+interface ActionDeclaration {
+    /** The Action's unique id within its chain (alchemy's `Action.id`). */
+    name: string;
+    /** Defaults to "applet". A value of alchemy's `ActionCategory` union. */
+    category?: string;
+    label: string;
+    description: string;
+    input?: ActionInput;
+    /** KindRef of what the run returns. */
+    output?: string;
+    runs: ActionRuns;
+    /** Server action name | mandate alias | route. `{param}` placeholders are filled from the input. */
+    target?: string;
+    triggeredBy: ActionCaller[];
+    policy: ActionPolicy;
+    updatesValue?: string;
+    mode?: ActionWriteMode;
+    patchable?: boolean;
+    approvalComparison?: string;
+    streamOps?: string[];
+    /** CONTRACTS §6 types it `string`; a write target's is a boolean flag. */
+    destination?: string | boolean;
+    groupKey?: string;
+    itemType?: string;
+    /** The write target's own apply policy, kept when it differs from `policy` ("queued" → policy "ask"). */
+    applyPolicy?: "manual" | "ask" | "auto" | "queued";
+    valueType?: string;
+    valueKind?: string;
+    sortOrder?: number;
+    origin?: ActionOrigin;
+}
+/** JSON only: what a lister (an agent, the menu, an applet) sees. */
+interface ActionInfo {
+    name: string;
+    category: string;
+    label: string;
+    description: string;
+    runs: ActionRuns;
+    policy: ActionPolicy;
+    triggeredBy: ActionCaller[];
+    input?: ActionInput;
+    output?: string;
+    /** The surface that declared it (a child's override names the child). */
+    declaredOn: string;
+    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;
+    by: ActionCaller;
+    viewerId: string | null;
+    surfaceName?: string;
+    policy?: ActionPolicy;
+}
+/** The system's own sentence, never thrown into a UI. Superset of RecordsError (CONTRACTS §0 `AppletError`). */
+interface ActionError {
+    code: string;
+    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> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: ActionError;
+};
+/** `POST /actions/run` (aidream) — the request. */
+interface ServerActionRunRequest {
+    name: string;
+    input: Json$1;
+    by: ActionCaller;
+    surface_name?: string;
+    policy?: ActionPolicy;
+}
+/** `POST /actions/run` (aidream) — the response. */
+interface ServerActionRunResponse {
+    status: "applied" | "proposed" | "refused";
+    message: string;
+    receipts: Json$1[];
+    proposal?: Json$1;
+}
+/** A mandate run request: by alias (an Action's `target`) or by key. */
+type MandateRunRequest = ({
+    alias: string;
+    key?: never;
+} | {
+    key: string;
+    alias?: never;
+}) & {
+    variables: Record<string, Json$1>;
+    userInput?: string;
+    by: ActionCaller;
+    policy: ActionPolicy;
+};
+/**
+ * CONTRACTS §6 `SurfacePort` — the surface runtime as the frame sees it. Types
+ * only here; the in-page host is AP-0's.
+ */
+interface SurfacePort {
+    /** Joins the runtime chain. */
+    mount(name: string, parent: string | null): Promise<ActionResult<{
+        mountId: string;
+    }>>;
+    unmount(mountId: string): Promise<void>;
+    getValue(name: string): Promise<unknown>;
+    setValue(name: string, v: unknown): Promise<void>;
+    /** This mount's own Actions plus inherited ones. */
+    listActions(): Promise<ActionInfo[]>;
+    runAction(name: string, input: unknown, by: ActionCaller): Promise<ActionResult<unknown>>;
+    /** A "page" Action is routed to the frame as `{ action, input, runId }`; the frame answers here. */
+    completeAction(runId: string, result: ActionResult<unknown>): Promise<void>;
+}
+
 /**
  * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
  *
@@ -268,7 +570,7 @@ interface ClickTarget {
  *   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 ───────────────────────────────────────────────────
  *
@@ -298,6 +600,16 @@ interface ClickTarget {
  *                         to an overlay carrying the session as data)
  *   transferKnobs absent → no organization default recipe; a person's own
  *                         default (persistence) or the package's Full applies
+ *   serverActions absent → `runs: "server"` Actions refuse with "not available here"
+ *   mandates     absent → `runs: "mandate"` Actions refuse the same way
+ *   pageActions  absent → `runs: "page"` Actions refuse the same way
+ *   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.
  */
@@ -443,6 +755,40 @@ interface AlchemyHostPorts {
     window?: WindowPort;
     /** Organization default recipes, resolved by the host's Feature Knob ladder (platform → organization). */
     transferKnobs?: TransferKnobsPort;
+    /** aidream `POST /actions/run`: a registered server action by name, as the caller, under the apply-policy cascade. */
+    serverActions?: ServerActionPort;
+    /** Runs a mandate by alias or key (the host binds `@ai-matrx/agents`; alchemy never imports it). */
+    mandates?: MandatePort;
+    /** The page's own handlers for `runs: "page"` Actions (in an applet frame: routed as `{ action, input, runId }`). */
+    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>;
+}
+interface ApprovalRequest {
+    action: string;
+    label: string;
+    description: string;
+    input: Json;
+    by: "agent" | "applet" | "automation";
+    surfaceName: string;
+}
+interface ApprovalPort {
+    /** Resolves true when the person approves; false when they decline or dismiss. */
+    ask(request: ApprovalRequest): Promise<boolean>;
+}
+interface PageActionPort {
+    dispatch(name: string, input: unknown, context: ActionContext): Promise<ActionResult<unknown>>;
 }
 /**
  * Why a port and not `OverlayHostPort`: an overlay's `data` is `Json`, and a live preparation
@@ -596,8 +942,10 @@ type Eligibility = {
     status: "unavailable";
     sentence: string;
 };
-/** rich-document's ActionCategory, unchanged, plus the three the context menu groups by. */
-type ActionCategory = "feedback" | "copy" | "export" | "save" | "edit" | "share" | "creator" | "app" | "listen" | "study" | "ask" | "ai" | "admin" | "clipboard" | "history" | "surface-info";
+/** rich-document's ActionCategory, unchanged, plus the three the context menu groups by, plus "applet" (surface Actions). */
+type ActionCategory = "feedback" | "copy" | "export" | "save" | "edit" | "share" | "creator" | "app" | "listen" | "study" | "ask" | "ai" | "admin" | "clipboard" | "history" | "surface-info"
+/** Surface Actions (Applets CONTRACTS §6): the default category of an `ActionDeclaration`. */
+ | "applet";
 declare const ACTION_CATEGORIES: readonly ActionCategory[];
 /**
  * An optional named section inside the action's group (a grid's cell / row /
@@ -871,4 +1219,117 @@ type RunResult = {
 };
 declare function runAction(action: Action, target: ClickTarget, options: RunActionOptions): Promise<RunResult>;
 
-export { ACTION_CATEGORIES, type Action, type ActionCategory, type ActionProvider, type ActionRegistry, type ActionRegistryOptions, type ActionRunContext, type ActionSection, type ClickTarget, type ClickTargetInput, DuplicateActionError, DuplicateProviderError, type Eligibility, type ProjectedReads, type ProjectionSource, type ReadOmission, type ResolveRestriction, type ResolvedAction, type RunActionOptions, type RunResult, UNIVERSAL_VERBS, type UniversalVerb, alwaysEligible, computeEligibility, createActionRegistry, createClickTarget, createProjectedReads, projectValues, runAction, staticActionProvider };
+/** Default `category` of an Action that names none. */
+declare const APPLET_CATEGORY = "applet";
+/** The DB default of `ui.ui_surface_action.triggered_by`, used where a source carries no list. */
+declare const DEFAULT_TRIGGERED_BY: readonly ActionCaller[];
+declare const ACTION_CALLERS: readonly ActionCaller[];
+declare const ACTION_RUNS: readonly ActionRuns[];
+declare const ACTION_POLICIES: readonly ActionPolicy[];
+/** A `ui.ui_surface_client_tool` row (live columns that carry meaning). */
+interface ClientToolRow {
+    id?: string;
+    surface_name: string;
+    name: string;
+    label: string;
+    description: string;
+    input_schema: Json$1;
+    /** Live values: "ui" (applied directly) | "draft" (proposed for review). */
+    mode: "ui" | "draft";
+    declared_by?: ActionDeclaredBy;
+}
+/** A `ui.ui_surface_action` row. */
+interface SurfaceActionRow {
+    id?: string;
+    surface_id: string;
+    surface_name: string;
+    /** '' = the screen itself. */
+    item_type: string;
+    name: string;
+    category: string;
+    label: string;
+    description: string;
+    input: ActionInput | null;
+    output: string | null;
+    runs: ActionRuns;
+    target: string | null;
+    triggered_by: ActionCaller[];
+    policy: ActionPolicy;
+    updates_value: string | null;
+    code_ref: string | null;
+    declared_by: ActionDeclaredBy;
+    sort_order: number;
+}
+/** A declared write target → an Action that runs on the page. */
+declare function writeTargetToAction(target: WriteTarget): ActionDeclaration;
+/** A client tool row → an Action an agent runs on the page ("draft" tools are proposed first). */
+declare function clientToolToAction(row: ClientToolRow): ActionDeclaration;
+/** A `ui.ui_surface_action` row → its Action. */
+declare function surfaceActionRowToAction(row: SurfaceActionRow): ActionDeclaration;
+/** JSON-only view of an Action as declared on `declaredOn`. */
+declare function toActionInfo(declaration: ActionDeclaration, declaredOn: string): ActionInfo;
+interface ActionChainLink {
+    surfaceName: string;
+    actions: readonly ActionDeclaration[];
+}
+/**
+ * The Actions a mount sees: its own plus every ancestor's, a child winning by
+ * name. `chain` runs MOST GENERAL FIRST (root parent … the mounted surface),
+ * as `DeclarationRegistry` resolves inheritance. Guards are loud, like the
+ * declaration registry's: a surface twice in the chain is a cycle, more
+ * ancestors than `maxDepth` throws, and one surface naming an Action twice throws.
+ */
+declare function resolveActionChain(chain: readonly ActionChainLink[], options?: {
+    maxDepth?: number;
+}): ActionInfo[];
+
+/**
+ * THE ONE RUNNER for surface Actions (Applets CONTRACTS §6). Every caller — a
+ * person's click, an agent, an applet, an automation — runs an Action through
+ * here, so policy and caller rules live once.
+ *
+ * Policy "ask": a person's own click is the approval. Started by an agent, applet or automation,
+ * a "server" run carries the policy to aidream (which answers with a proposal); every other run
+ * asks the person through `ports.approvals` first, and is refused by name without that port.
+ *
+ * Dispatch by `runs`:
+ *   "server"   → `ports.serverActions.run({ name: target, input, by, surface_name, policy })`
+ *   "mandate"  → `ports.mandates.run({ alias: target, variables, by, policy })`
+ *   "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" | "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): {
+    value: string;
+    missing: string[];
+};
+/**
+ * Who may run this Action, under its policy. Returns the refusal, or null.
+ * "manual" = a person only. `triggeredBy` lists every caller allowed at all.
+ */
+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 };