@ai-matrx/alchemy 0.8.60 → 0.9.1

package/dist/actions.d.cts

@@ -250,6 +250,162 @@ interface ClickTarget {
     host?: unknown;
 }
 
+/**
+ * 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;
+}
+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;
+}
+/** 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).
  *
@@ -298,6 +454,12 @@ 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)
  *
  * Types only: this entry has no runtime code.
  */
@@ -443,6 +605,36 @@ 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;
+}
+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 +788,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 +1065,107 @@ 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).
+ *
+ * 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">;
+interface RunSurfaceActionOptions {
+    runId?: string;
+    viewerId?: string | null;
+    signal?: AbortSignal;
+}
+/** 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 };

package/dist/actions.d.ts

@@ -250,6 +250,162 @@ interface ClickTarget {
     host?: unknown;
 }
 
+/**
+ * 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;
+}
+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;
+}
+/** 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).
  *
@@ -298,6 +454,12 @@ 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)
  *
  * Types only: this entry has no runtime code.
  */
@@ -443,6 +605,36 @@ 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;
+}
+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 +788,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 +1065,107 @@ 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).
+ *
+ * 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">;
+interface RunSurfaceActionOptions {
+    runId?: string;
+    viewerId?: string | null;
+    signal?: AbortSignal;
+}
+/** 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 };