@ai-matrx/alchemy 0.8.60 → 0.9.1

package/dist/operate.d.cts

@@ -2,8 +2,8 @@
  * Framework-neutral transfer contracts (Alchemy Operate, CONTRACT §2.3). All data crossing this boundary is JSON.
  * Moved from `@ai-matrx/kit/content-transfer` in ALC-16; the format-adapter contract lives in `./contract`.
  */
-type Json$1 = null | boolean | number | string | Json$1[] | {
-    [key: string]: Json$1;
+type Json$2 = null | boolean | number | string | Json$2[] | {
+    [key: string]: Json$2;
 };
 type Payload = 
 /** A text payload may name its language (code blocks): downloads take its extension, Markdown fences it. */
@@ -16,15 +16,15 @@ type Payload =
     text: string;
 } | {
     kind: "json";
-    value: Json$1;
+    value: Json$2;
 } | {
     kind: "rows";
-    rows: Record<string, Json$1>[];
+    rows: Record<string, Json$2>[];
     columns: Column[];
 } | {
     kind: "registered";
     format: string;
-    value: Json$1;
+    value: Json$2;
 };
 type Column = {
     id: string;
@@ -38,9 +38,9 @@ type Column = {
         dataType?: string;
         order?: number;
         required?: boolean;
-        defaultValue?: Json$1;
-        validation?: Json$1;
-        metadata?: Json$1;
+        defaultValue?: Json$2;
+        validation?: Json$2;
+        metadata?: Json$2;
     };
 };
 type ExportProjection = {
@@ -93,21 +93,21 @@ type Snapshot = RawSnapshot & {
 type QuerySnapshot = {
     sourceId: string;
     revision: string;
-    query: Json$1;
+    query: Json$2;
     order: {
         field: string;
         direction: "asc" | "desc";
     }[];
 };
 type ExportPage = {
-    rows: Record<string, Json$1>[];
+    rows: Record<string, Json$2>[];
     nextCursor: string | null;
     coverage: Coverage;
     consistencyToken: string | null;
 };
 type CapturedAllMatching = {
     query: QuerySnapshot;
-    getRowId(row: Record<string, Json$1>): string;
+    getRowId(row: Record<string, Json$2>): string;
     page(request: {
         query: QuerySnapshot;
         cursor: string | null;
@@ -147,7 +147,7 @@ type Draft = {
 };
 type Transform = {
     id: string;
-    apply(draft: Draft, options: Json$1, signal: AbortSignal): Promise<Draft>;
+    apply(draft: Draft, options: Json$2, signal: AbortSignal): Promise<Draft>;
 };
 type Artifact = {
     snapshotId: string;
@@ -338,9 +338,9 @@ type BoundAllMatching = {
 type NormalizeTransferJsonOptions = {
     omitUndefinedObjectProperties?: boolean;
 };
-declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json$1;
+declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json$2;
 /** Column ids are identities, never an alternative data address. */
-declare function readTransferCell(row: Record<string, Json$1>, column: Column): Json$1 | undefined;
+declare function readTransferCell(row: Record<string, Json$2>, column: Column): Json$2 | undefined;
 declare function projectSnapshot(raw: RawSnapshot, projection: ExportProjection): Snapshot;
 declare function directSource(payload: Payload, options?: Partial<Pick<RawSnapshot, "id" | "sourceId" | "revision" | "label" | "coverage" | "unsavedChanges" | "sections" | "limits"> & {
     projection: ExportProjection;
@@ -385,7 +385,7 @@ declare function reduceJson(draft: Draft, options: {
     maxArrayItems?: number | null;
 }): Draft;
 declare function collectAllMatching(c: BoundAllMatching, signal: AbortSignal): Promise<{
-    rows: Record<string, Json$1>[];
+    rows: Record<string, Json$2>[];
     coverage: RawSnapshot["coverage"];
     omissions: Omission[];
     error?: ContentTransferError;
@@ -433,6 +433,16 @@ declare function createSurfaceTransferHandle(options: {
 /** Applies explicit preparation/source limits with exact omissions; token target is advisory. */
 declare function applyTransferLimits(draft: Draft, limits: Partial<TransferLimits>): Draft;
 
+/**
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
+ *
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
+ */
+type Json$1 = null | boolean | number | string | Json$1[] | {
+    [key: string]: Json$1;
+};
 /** Unchanged from `ui_surface_value_type_chk`. */
 type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
 type Classification = "ordinary" | "secret" | "credential";
@@ -639,6 +649,75 @@ 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";
+/** Who may run it without a click: "manual" = only a person; "ask" = proposed first; "auto" = runs. */
+type ActionPolicy = "ask" | "auto" | "manual";
+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;
+};
+
 /**
  * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
  *
@@ -687,6 +766,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.
  */
@@ -832,6 +917,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
@@ -983,7 +1098,7 @@ type TransferOperation = {
 } | {
     kind: "transform";
     transform: string;
-    options?: Json$1;
+    options?: Json$2;
 } | {
     kind: "prepare-for-ai";
     instruction?: string;
@@ -1028,7 +1143,7 @@ interface ServerOperation {
     statement: string;
     supports(payload: Payload): boolean;
     /** Projected draft only; sensitivity already applied. */
-    toInput(draft: Draft): Json$1;
+    toInput(draft: Draft): Json$2;
 }
 /** Delivery results: `copy` and `download` only ever deliver, degrade, cancel or fail (CONTRACT R16). */
 type DeliveryOutcome = Extract<TransferOutcome, {
@@ -1110,7 +1225,7 @@ interface PreparationSession {
     readonly snapshot: Snapshot;
     readonly draft: Draft;
     /** Deterministic transform, AI preparation or any registered transform — bumps draft.revision. */
-    transform(id: string, options: Json$1, signal: AbortSignal): Promise<Draft>;
+    transform(id: string, options: Json$2, signal: AbortSignal): Promise<Draft>;
     /** A manual edit. */
     edit(payload: Payload): Draft;
     /** Keep only these sections (ids from the snapshot). */
@@ -1228,19 +1343,19 @@ declare function patternBelow(pattern: string, pointer: string): boolean;
 /** The path a person reads and copies: `/messages/*\/metadata` → `data.messages[*].metadata`. */
 declare function displayPath(pointer: string, root?: string): string;
 /** Exactly `JSON.stringify(value).length`, computed once per object (large sources stay cheap). */
-declare function jsonSize(value: Json$1): number;
+declare function jsonSize(value: Json$2): number;
 /** The size a person expects for a node: a string's own length, else its JSON. */
-declare function nodeChars(value: Json$1): number;
+declare function nodeChars(value: Json$2): number;
 /**
  * The one-line stub that stands in for a node: its header (a string's first line, an object's
  * short scalar members) and its original size.
  */
-declare function stubText(value: Json$1): string;
+declare function stubText(value: Json$2): string;
 /** Every concrete pointer in `value` a pattern names (for counts, diffs and highlights). */
-declare function concretePointers(value: Json$1, pattern: string): string[];
+declare function concretePointers(value: Json$2, pattern: string): string[];
 /** Apply exclusions and per-node limits to a JSON value; returns the new value and what changed. */
-declare function applyStructureToJson(value: Json$1, recipe: StructureRecipe, labels?: Readonly<Record<string, string>>): {
-    value: Json$1;
+declare function applyStructureToJson(value: Json$2, recipe: StructureRecipe, labels?: Readonly<Record<string, string>>): {
+    value: Json$2;
     omissions: Omission[];
 };
 /** A JSON (or registered) draft with the person's structure choices applied. */
@@ -1250,7 +1365,7 @@ declare function applyJsonStructure(draft: Draft, recipe: StructureRecipe, label
  * earlier sibling is excluded). Null when the node is excluded or cut; a stubbed ancestor answers
  * with the stub's own pointer.
  */
-declare function outputPointer(value: Json$1, recipe: StructureRecipe, pointer: string): string | null;
+declare function outputPointer(value: Json$2, recipe: StructureRecipe, pointer: string): string | null;
 declare function isProseSection(section: Section): boolean;
 interface SectionLayout {
     text: string;
@@ -1321,4 +1436,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$1 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 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 };

package/dist/operate.d.ts

@@ -2,8 +2,8 @@
  * Framework-neutral transfer contracts (Alchemy Operate, CONTRACT §2.3). All data crossing this boundary is JSON.
  * Moved from `@ai-matrx/kit/content-transfer` in ALC-16; the format-adapter contract lives in `./contract`.
  */
-type Json$1 = null | boolean | number | string | Json$1[] | {
-    [key: string]: Json$1;
+type Json$2 = null | boolean | number | string | Json$2[] | {
+    [key: string]: Json$2;
 };
 type Payload = 
 /** A text payload may name its language (code blocks): downloads take its extension, Markdown fences it. */
@@ -16,15 +16,15 @@ type Payload =
     text: string;
 } | {
     kind: "json";
-    value: Json$1;
+    value: Json$2;
 } | {
     kind: "rows";
-    rows: Record<string, Json$1>[];
+    rows: Record<string, Json$2>[];
     columns: Column[];
 } | {
     kind: "registered";
     format: string;
-    value: Json$1;
+    value: Json$2;
 };
 type Column = {
     id: string;
@@ -38,9 +38,9 @@ type Column = {
         dataType?: string;
         order?: number;
         required?: boolean;
-        defaultValue?: Json$1;
-        validation?: Json$1;
-        metadata?: Json$1;
+        defaultValue?: Json$2;
+        validation?: Json$2;
+        metadata?: Json$2;
     };
 };
 type ExportProjection = {
@@ -93,21 +93,21 @@ type Snapshot = RawSnapshot & {
 type QuerySnapshot = {
     sourceId: string;
     revision: string;
-    query: Json$1;
+    query: Json$2;
     order: {
         field: string;
         direction: "asc" | "desc";
     }[];
 };
 type ExportPage = {
-    rows: Record<string, Json$1>[];
+    rows: Record<string, Json$2>[];
     nextCursor: string | null;
     coverage: Coverage;
     consistencyToken: string | null;
 };
 type CapturedAllMatching = {
     query: QuerySnapshot;
-    getRowId(row: Record<string, Json$1>): string;
+    getRowId(row: Record<string, Json$2>): string;
     page(request: {
         query: QuerySnapshot;
         cursor: string | null;
@@ -147,7 +147,7 @@ type Draft = {
 };
 type Transform = {
     id: string;
-    apply(draft: Draft, options: Json$1, signal: AbortSignal): Promise<Draft>;
+    apply(draft: Draft, options: Json$2, signal: AbortSignal): Promise<Draft>;
 };
 type Artifact = {
     snapshotId: string;
@@ -338,9 +338,9 @@ type BoundAllMatching = {
 type NormalizeTransferJsonOptions = {
     omitUndefinedObjectProperties?: boolean;
 };
-declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json$1;
+declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json$2;
 /** Column ids are identities, never an alternative data address. */
-declare function readTransferCell(row: Record<string, Json$1>, column: Column): Json$1 | undefined;
+declare function readTransferCell(row: Record<string, Json$2>, column: Column): Json$2 | undefined;
 declare function projectSnapshot(raw: RawSnapshot, projection: ExportProjection): Snapshot;
 declare function directSource(payload: Payload, options?: Partial<Pick<RawSnapshot, "id" | "sourceId" | "revision" | "label" | "coverage" | "unsavedChanges" | "sections" | "limits"> & {
     projection: ExportProjection;
@@ -385,7 +385,7 @@ declare function reduceJson(draft: Draft, options: {
     maxArrayItems?: number | null;
 }): Draft;
 declare function collectAllMatching(c: BoundAllMatching, signal: AbortSignal): Promise<{
-    rows: Record<string, Json$1>[];
+    rows: Record<string, Json$2>[];
     coverage: RawSnapshot["coverage"];
     omissions: Omission[];
     error?: ContentTransferError;
@@ -433,6 +433,16 @@ declare function createSurfaceTransferHandle(options: {
 /** Applies explicit preparation/source limits with exact omissions; token target is advisory. */
 declare function applyTransferLimits(draft: Draft, limits: Partial<TransferLimits>): Draft;
 
+/**
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
+ *
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
+ */
+type Json$1 = null | boolean | number | string | Json$1[] | {
+    [key: string]: Json$1;
+};
 /** Unchanged from `ui_surface_value_type_chk`. */
 type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
 type Classification = "ordinary" | "secret" | "credential";
@@ -639,6 +649,75 @@ 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";
+/** Who may run it without a click: "manual" = only a person; "ask" = proposed first; "auto" = runs. */
+type ActionPolicy = "ask" | "auto" | "manual";
+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;
+};
+
 /**
  * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
  *
@@ -687,6 +766,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.
  */
@@ -832,6 +917,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
@@ -983,7 +1098,7 @@ type TransferOperation = {
 } | {
     kind: "transform";
     transform: string;
-    options?: Json$1;
+    options?: Json$2;
 } | {
     kind: "prepare-for-ai";
     instruction?: string;
@@ -1028,7 +1143,7 @@ interface ServerOperation {
     statement: string;
     supports(payload: Payload): boolean;
     /** Projected draft only; sensitivity already applied. */
-    toInput(draft: Draft): Json$1;
+    toInput(draft: Draft): Json$2;
 }
 /** Delivery results: `copy` and `download` only ever deliver, degrade, cancel or fail (CONTRACT R16). */
 type DeliveryOutcome = Extract<TransferOutcome, {
@@ -1110,7 +1225,7 @@ interface PreparationSession {
     readonly snapshot: Snapshot;
     readonly draft: Draft;
     /** Deterministic transform, AI preparation or any registered transform — bumps draft.revision. */
-    transform(id: string, options: Json$1, signal: AbortSignal): Promise<Draft>;
+    transform(id: string, options: Json$2, signal: AbortSignal): Promise<Draft>;
     /** A manual edit. */
     edit(payload: Payload): Draft;
     /** Keep only these sections (ids from the snapshot). */
@@ -1228,19 +1343,19 @@ declare function patternBelow(pattern: string, pointer: string): boolean;
 /** The path a person reads and copies: `/messages/*\/metadata` → `data.messages[*].metadata`. */
 declare function displayPath(pointer: string, root?: string): string;
 /** Exactly `JSON.stringify(value).length`, computed once per object (large sources stay cheap). */
-declare function jsonSize(value: Json$1): number;
+declare function jsonSize(value: Json$2): number;
 /** The size a person expects for a node: a string's own length, else its JSON. */
-declare function nodeChars(value: Json$1): number;
+declare function nodeChars(value: Json$2): number;
 /**
  * The one-line stub that stands in for a node: its header (a string's first line, an object's
  * short scalar members) and its original size.
  */
-declare function stubText(value: Json$1): string;
+declare function stubText(value: Json$2): string;
 /** Every concrete pointer in `value` a pattern names (for counts, diffs and highlights). */
-declare function concretePointers(value: Json$1, pattern: string): string[];
+declare function concretePointers(value: Json$2, pattern: string): string[];
 /** Apply exclusions and per-node limits to a JSON value; returns the new value and what changed. */
-declare function applyStructureToJson(value: Json$1, recipe: StructureRecipe, labels?: Readonly<Record<string, string>>): {
-    value: Json$1;
+declare function applyStructureToJson(value: Json$2, recipe: StructureRecipe, labels?: Readonly<Record<string, string>>): {
+    value: Json$2;
     omissions: Omission[];
 };
 /** A JSON (or registered) draft with the person's structure choices applied. */
@@ -1250,7 +1365,7 @@ declare function applyJsonStructure(draft: Draft, recipe: StructureRecipe, label
  * earlier sibling is excluded). Null when the node is excluded or cut; a stubbed ancestor answers
  * with the stub's own pointer.
  */
-declare function outputPointer(value: Json$1, recipe: StructureRecipe, pointer: string): string | null;
+declare function outputPointer(value: Json$2, recipe: StructureRecipe, pointer: string): string | null;
 declare function isProseSection(section: Section): boolean;
 interface SectionLayout {
     text: string;
@@ -1321,4 +1436,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$1 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 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 };