@ai-matrx/alchemy 0.9.1 → 0.11.0

package/dist/surface.d.cts

@@ -0,0 +1,1045 @@
+/**
+ * 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";
+/** Persisted (CONTRACT §2.7). Projection enforces it before any value leaves. */
+interface Sensitivity {
+    /** false = never leaves through Operate. Default true. */
+    exportable: boolean;
+    /** secret/credential are always excluded; no caller can relax this. Default "ordinary". */
+    classification: Classification;
+    /** Pre-checked in the preparation workspace. Default true. */
+    includedByDefault: boolean;
+}
+interface ValueGroup {
+    key: string;
+    label: string;
+    sortOrder: number;
+    description?: string;
+}
+/** The four runtime slots a capture fills (absorbs page-capture). */
+type LiveSlot = "selection" | "on-demand" | "errors" | "requests";
+interface DeclaredValue {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    /** Registered content-ir kind key (DB: kind_key). */
+    valueKind?: string;
+    alwaysAvailable: boolean;
+    typicalCharCount: number;
+    autoContext?: boolean;
+    group?: string;
+    sortOrder?: number;
+    sensitivity?: Partial<Sensitivity>;
+    /** Filled at capture time from a live slot instead of the scope. */
+    liveSlot?: LiveSlot;
+    /** "request" values drop out of "Only the data". Default "data". */
+    role?: "data" | "request";
+}
+/** Where a write lands. "stream" = applied live, op by op, into an editable text. */
+type WriteMode = "draft" | "entity" | "ui" | "stream";
+/** Who may apply WITHOUT a click. "queued" = filed for an organization's review. */
+type ApplyPolicy = "manual" | "ask" | "auto" | "queued";
+/** The WidgetHandle text op set, unchanged in meaning. */
+type StreamOp = "replace" | "insert_before" | "insert_after" | "prepend" | "append" | "patch";
+interface WriteTarget {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    valueKind?: string;
+    /** Read twin (evidence loop). Required when patchable or mode === "stream". */
+    updatesValue?: string;
+    patchable?: boolean;
+    approvalComparison?: "text-replacement";
+    mode: WriteMode;
+    /** Required iff mode === "stream". */
+    streamOps?: readonly StreamOp[];
+    /** Default "manual". Binding overrides may only tighten. */
+    applyPolicy?: ApplyPolicy;
+    destination?: boolean;
+    /** Present when the target writes into an item rather than the screen. */
+    itemType?: string;
+    group?: string;
+    sortOrder?: number;
+}
+/** One kind of thing inside a screen (a row, a message, a code block, a card). */
+interface ItemType {
+    name: string;
+    label: string;
+    description: string;
+    /** Value names that together identify one item. */
+    identity: readonly string[];
+    levels?: readonly string[];
+    entityType?: string;
+    values: readonly DeclaredValue[];
+    writeTargets?: readonly WriteTarget[];
+}
+type Readiness = "verified" | "partial" | "stub";
+/** `ui_surface_execution_mode_check`, unchanged. */
+type ExecutionMode = "python-stream" | "nextjs-stream" | "browser-realtime" | "local-runtime";
+interface ConfigNamespaceDeclaration {
+    namespace: string;
+    label: string;
+    description: string;
+}
+interface EvidenceSourceDeclaration {
+    kind: "processed_document";
+    idValue: string;
+    fileIdValue?: string;
+    labelValue?: string;
+    representation?: "clean" | "raw";
+}
+/**
+ * One screen's declaration. Owning packages add fields (agent roles, client
+ * tools) as EXTENSION SLOTS — by interface extension or declaration merging —
+ * and register a `DeclarationExtension` so validation and the sync cover them.
+ */
+interface SurfaceDeclaration {
+    surfaceName: string;
+    /** REQUIRED. `ui_surface.client_name`; must equal the surfaceName prefix. */
+    client: string;
+    /** REQUIRED. `ui_surface.execution_mode`. */
+    executionMode: ExecutionMode;
+    /** REQUIRED. `ui_surface.description` ("" only where the live row is empty). */
+    description: string;
+    label: string;
+    readiness: Readiness;
+    readinessNote?: string;
+    urlPattern?: string;
+    inheritsFrom?: string;
+    intro?: string;
+    overlayId?: string;
+    values: readonly DeclaredValue[];
+    groups?: readonly ValueGroup[];
+    writeTargets?: readonly WriteTarget[];
+    itemTypes?: readonly ItemType[];
+    liveSlots?: readonly LiveSlot[];
+    configNamespaces?: readonly ConfigNamespaceDeclaration[];
+    evidenceSources?: readonly EvidenceSourceDeclaration[];
+    skipBaselineValues?: boolean;
+}
+type ValueProvenance = {
+    kind: "own";
+} | {
+    kind: "inherited";
+    from: string;
+} | {
+    kind: "baseline";
+};
+type ResolvedValue = DeclaredValue & {
+    provenance: ValueProvenance;
+    groupKey: string;
+    /** Defaults filled. */
+    resolvedSensitivity: Sensitivity;
+};
+interface ResolvedSurfaceDeclaration extends SurfaceDeclaration {
+    contentHash: string;
+    values: readonly ResolvedValue[];
+    groups: readonly ValueGroup[];
+}
+/**
+ * ITEM KEYS. A value or write target is identified by (surfaceName, itemType ?? "", name).
+ * The qualified key "<itemType>.<name>" names an item value; a bare name is a screen value.
+ */
+type QualifiedValueKey = string;
+/** RAW-FREE. What leaves the package about a clicked item. */
+interface ResolvedItem {
+    itemType: string;
+    identity: Record<string, string>;
+    level?: string;
+    readOnly: boolean;
+}
+
+/**
+ * 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";
+/** 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;
+    /** The source row's organization (an organization extension applies only to its members). */
+    organizationId?: string;
+}
+/** 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 §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;
+}
+/**
+ * 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>;
+}
+
+/** 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;
+    /**
+     * The row's organization. A `declared_by='database'` row on a surface outside `applets/` is that
+     * organization's EXTENSION and applies only to its members (`readSurfaceChain`, aidream `visible_actions`).
+     */
+    organization_id?: string | null;
+}
+
+/** Surfaces under this prefix belong to one Applet; their database rows are never "extensions". */
+declare const APPLET_SURFACE_PREFIX = "applets/";
+interface ReadSurfaceChainOptions {
+    /** Most ancestors a surface may have (alchemy's declaration default when absent). */
+    maxDepth?: number;
+    /** ALL of the viewer's organization memberships. Absent = organization extensions are dropped. */
+    organizationIds?: readonly string[];
+}
+/** Whether a row applies to a viewer with these memberships (aidream `visible_actions`). */
+declare function surfaceActionVisible(row: Pick<SurfaceActionRow, "declared_by" | "surface_name" | "organization_id">, organizationIds: readonly string[] | undefined): boolean;
+declare function readSurfaceChain(client: object, surfaceName: string, options?: ReadSurfaceChainOptions): Promise<ActionResult<ActionInfo[]>>;
+
+/**
+ * The click target (CONTRACT §2.4) in its own module: `/ports` references it,
+ * and `/ports` must stay free of every other package (types only).
+ */
+
+/** The transfer Payload's kinds (`actions/types.ts` asserts equality at compile time). */
+type PayloadKind = "text" | "markdown" | "json" | "rows" | "registered";
+/** What eligibility is computed from: everything declared at the click target. */
+interface ClickTarget {
+    surface: {
+        instanceId: string;
+        surfaceName: string;
+    } | null;
+    /** The resolved declaration (inheritance applied). Eligibility decides by KEY existence over it. */
+    declaration: ResolvedSurfaceDeclaration | null;
+    /** Declared value keys with a read path here (screen names + qualified item keys). Key existence, not population. */
+    valueKeys: ReadonlySet<QualifiedValueKey>;
+    /** Scope chain, most general first: ["global", "<domain>", "<surfaceName>"]. */
+    scopeChain: readonly string[];
+    /** The surface's explicit exclusions (the one override). */
+    excludedActionIds: ReadonlySet<string>;
+    item: ResolvedItem | null;
+    level: string | null;
+    /** Offsets + the live range handle, editable or not. */
+    selection: {
+        text: string;
+        type: "editable" | "non-editable";
+        start: number;
+        end: number;
+        /** Opaque host handle (DOM Range / element) used to restore or stream into the selection. */
+        handle?: unknown;
+    } | null;
+    /** Payload kinds a capture of this target would produce (from declared value types/kinds). */
+    payloadKinds: readonly PayloadKind[];
+    /** Declared targets writable on this target right now. */
+    writable: readonly WriteTarget[];
+    readOnly: boolean;
+    /** True when any declared value here is secret/credential or non-exportable. */
+    restricted: boolean;
+    organizationId: string | null;
+    auth: {
+        authenticated: boolean;
+        admin: boolean;
+        creator: boolean;
+    };
+    /**
+     * Host-owned context a provider reads to act (the rich-document source, the
+     * editable field's callbacks). Opaque to the package; never crosses into the
+     * model. Providers that need it narrow it themselves.
+     */
+    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;
+}
+
+/**
+ * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
+ *
+ * The app binds these ONCE, at its boundary (where the Alchemy host is
+ * mounted). The package never imports the host.
+ *
+ * ── Ports arrive with the wave that needs them (chair ruling N8) ────────────
+ *
+ * This entry declares only the ports the current waves use:
+ *
+ *   ALC-13  `kinds` (content-ir's validator, injected), `diagnostics` (required)
+ *   ALC-14  `identity`, `persistence`
+ *   ALC-15  `store`, `notify`, `overlay`, `icons`, `knobs`, `i18n`, `auth`, `dialogs`
+ *
+ *   ALC-16  `transport`, `assets`, `server`
+ *   PP-01a  `window` (host-rendered windows for a live preparation session)
+ *   PP-13a  `transferKnobs` (organization default recipes)
+ *
+ *   ALC-17  `door` (the one write door), `review` (queued writes)
+ *
+ * ── Absent-port semantics ───────────────────────────────────────────────────
+ *
+ * Every port except `diagnostics` is OPTIONAL. A port the host does not bind
+ * means that capability is ABSENT: the actions, formats or writes that need
+ * it are not offered at all. A missing port is never stubbed, never faked
+ * with a default that pretends to work, and never shown as a dead control.
+ *
+ *   kinds        absent → kind validation is absent (no value can be checked,
+ *                         so a kind-bearing write is not offered)
+ *   diagnostics  REQUIRED → nothing fails silently; contract breaks land here
+ *   identity     absent → organization-scoped declarations are absent
+ *   persistence  absent → per-person settings are absent (organization and
+ *                         platform defaults apply)
+ *   store        absent → actions that read named host state or run named
+ *                         host commands are absent
+ *   notify       absent → outcomes are not announced (diagnostics still captures)
+ *   overlay      absent → actions that open an overlay or navigate are absent
+ *   icons        absent → rows render label-only (a key is never shown as text)
+ *   knobs        absent → the platform default layout/density applies
+ *   i18n         absent → labels as written
+ *   auth         absent → a signed-out person does not see requiresAuth actions
+ *                         (sign-in-then-resume is the capability that is missing)
+ *   dialogs      absent → actions that need a host dialog are absent
+ *   window       absent → the preparation workspace window is absent (its
+ *                         Prepare entry is not offered; it never falls back
+ *                         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.
+ */
+/** JSON as it crosses a port. */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * content-ir's kind validator, injected so Alchemy validates without
+ * importing the app or the kind catalog. The host builds it from
+ * `@ai-matrx/content-ir`'s `createKindValidator` over its own
+ * `SchemaSourcePort` (which content-ir defines and exports; Alchemy never
+ * declares it).
+ *
+ * `unverifiable: true` marks a verdict where the kind could not be checked
+ * (not registered, no schema, uncompilable schema, catalog unreachable) — a
+ * skip, which is never a pass.
+ */
+interface KindValidatorPort {
+    validate(kindKey: string, value: unknown, signal: AbortSignal): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        sentence: string;
+        remedy: string;
+        unverifiable?: true;
+    }>;
+}
+
+/** Where contract breaks are captured. Required: nothing fails silently. */
+interface DiagnosticsPort {
+    capture(error: unknown, context: {
+        area: "declare" | "operate" | "write" | "actions" | "menu";
+        detail: Json;
+    }): void;
+}
+/** Who is using the app right now, and in which organization. */
+interface IdentityPort {
+    /** `null` while the host has no resolved identity yet. */
+    current(): {
+        userId: string;
+        organizationId: string | null;
+        isAuthenticated: boolean;
+        isAdmin: boolean;
+    } | null;
+    /** Called whenever `current()` may answer differently; returns unsubscribe. */
+    onChange(listener: () => void): () => void;
+}
+/** Per-person settings (layout, density, transfer preferences), layered by the host's settings system. */
+interface PersistencePort {
+    readSetting<T extends Json>(key: string): Promise<T | null>;
+    writeSetting(key: string, value: Json): Promise<void>;
+}
+/** Neutral state access: named reads and named commands. No Redux type or dispatch crosses this line. */
+interface StorePort {
+    /** A named, typed read the host registered ("activeConversationId", "organizationName"). */
+    read<T extends Json>(key: string): T | null;
+    /** A named command the host registered ("tasks.setPendingSource"); resolves with its result. */
+    command(name: string, input: Json): Promise<Json | void>;
+    subscribe(key: string, listener: () => void): () => void;
+}
+interface NotifyPort {
+    success(sentence: string): void;
+    info(sentence: string): void;
+    /** Every failure names its remedy. */
+    error(sentence: string, remedy: string): void;
+}
+/** Overlays are dispatched through the host; the menu never renders a modal. */
+interface OverlayHostPort {
+    open(overlayId: string, data: Json, instanceId?: string): void;
+    close(overlayId: string, instanceId?: string): void;
+    navigate(href: string): void;
+}
+/** Icon key → the host's icon component. The model only ever holds keys. */
+interface IconResolverPort {
+    resolve(key: string): unknown | null;
+}
+type ContextArrangementKnob = "classic" | "tiered" | "command";
+type DensityKnob = "comfortable" | "compact";
+/** ORGANIZATION defaults only; every method takes the organization. */
+interface MenuKnobsPort {
+    /** Replaces the constant PLACEMENT_LABEL_OVERRIDE. */
+    placementLabel(placement: string, organizationId: string | null): string | null;
+    /** Replaces the constant DEFAULT_PLACEMENT_MODE. */
+    placementMode(placement: string, organizationId: string | null): "show" | "hide";
+    /** The organization's default layout and density (platform default when null: command / comfortable). */
+    layout(organizationId: string | null): {
+        context: ContextArrangementKnob;
+        density: DensityKnob;
+    } | null;
+}
+/** Label translation. Absent = labels as written. */
+interface I18nPort {
+    t(key: string, fallback: string): string;
+}
+/** Sign in, then resume the action the person picked. */
+interface AuthResumePort {
+    isSignedIn(): boolean;
+    /** Stash {actionId, target fingerprint} and open sign-in; after sign-in the next matching menu host resumes it. */
+    signInThenResume(pending: {
+        actionId: string;
+        contentFingerprint: string;
+    }): void;
+    takePending(contentFingerprint: string): {
+        actionId: string;
+    } | null;
+}
+/** Per-instance host dialogs (today's RichDocumentActionContextCallbacks). */
+interface HostDialogsPort {
+    requestDelete?(target: ClickTarget): void;
+    requestConvert?(target: ClickTarget): void;
+    requestEditHistory?(target: ClickTarget): void;
+    requestFullPrint?(target: ClickTarget): void;
+    requestSaveTable?(table: {
+        headers: string[];
+        rows: string[][];
+    }): void;
+    requestFlashcard?(answer: string): void;
+}
+/** The ports a host binds. Optional = absent capability when unbound (see above). */
+interface AlchemyHostPorts {
+    kinds?: KindValidatorPort;
+    /** REQUIRED from ALC-13 (the only non-optional port): contract breaks are captured here. */
+    diagnostics: DiagnosticsPort;
+    identity?: IdentityPort;
+    persistence?: PersistencePort;
+    store?: StorePort;
+    notify?: NotifyPort;
+    overlay?: OverlayHostPort;
+    icons?: IconResolverPort;
+    /** Organization defaults for menu knobs; a person's own choice is layered over them via persistence (N9). */
+    knobs?: MenuKnobsPort;
+    i18n?: I18nPort;
+    auth?: AuthResumePort;
+    dialogs?: HostDialogsPort;
+    /** Clipboard and download for this runtime (the browser default ships in /operate). */
+    transport?: TransportPort;
+    /** Private or signed images → share-safe URLs before HTML is sealed. Absent = images keep their URL. */
+    assets?: AssetResolverPort;
+    /** Present when the host can reach aidream server operations; absent = server formats are not offered. */
+    server?: ServerPort;
+    /** Host-rendered windows for a LIVE preparation session (functions, subscriptions, sealed artifacts). */
+    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 {
+    /**
+     * 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;
+    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
+ * session is not — it holds functions, subscriptions and sealed-artifact handles. So the workspace
+ * never travels as overlay data; the package hands the host a render function and the host draws it
+ * inside its own window system, with the session still live in the closure.
+ */
+interface WindowSize {
+    width: number;
+    height: number;
+}
+interface WindowOpenOptions {
+    /** The window's title, as a person reads it. */
+    title: string;
+    /** Preferred size; `"full"` = near-full-screen. The host clamps to the viewport. */
+    size?: WindowSize | "full";
+    /**
+     * Stable identity. Opening an id that is already open focuses that window and draws the new
+     * render in it instead of opening a second one.
+     */
+    instanceId?: string;
+    /** Called exactly once when the window closes, whoever closed it (the person, `close()`, the host). */
+    onClose?: () => void;
+}
+interface WindowHandle {
+    readonly instanceId: string;
+    /** Close the window; idempotent. */
+    close(): void;
+    /** Bring the window to the front; a no-op once closed. */
+    focus(): void;
+    isOpen(): boolean;
+}
+interface WindowPort {
+    /**
+     * What the host really draws. `"window"`: non-blocking, movable, resizable. `"dialog"`: a blocking
+     * full-screen dialog — a surface on a dialog host never says "window" and never offers a second one.
+     */
+    readonly presentation: "window" | "dialog";
+    /** True only when several windows can be open and usable at once. False = never offer "open another". */
+    readonly multiInstance: boolean;
+    /**
+     * Draw `render(handle)` inside a host window. `render` returns a host UI node (a React element in
+     * a React host) and is called by the host while the window is open.
+     */
+    open(render: (window: WindowHandle) => unknown, options: WindowOpenOptions): WindowHandle;
+}
+/**
+ * ORGANIZATION defaults for transfer, resolved by the host's Feature Knob ladder: the platform
+ * default an admin sets, overridden by the organization. Never per-person — a person's own choice
+ * lives only in `PersistencePort` and is layered over this by the package (`resolveDefaultRecipe`).
+ */
+interface TransferKnobsPort {
+    /**
+     * The organization's default recipe for one source kind (the platform default when the
+     * organization set none), or null when neither names one. A read that fails rejects; it never
+     * answers null for "could not ask".
+     */
+    defaultRecipe(sourceKind: string, organizationId: string | null): Promise<Json | null>;
+}
+/** A transferable artifact as the transport sees it (structurally `@ai-matrx/alchemy/operate`'s Artifact). */
+interface TransportArtifact {
+    format: string;
+    plainText: string;
+    html?: string;
+    file?: {
+        filename: string;
+        mime: string;
+        bytes: Uint8Array;
+    };
+}
+type TransportOutcome = {
+    status: "success";
+    delivered: "clipboard" | "download-started";
+    mimeTypes: string[];
+} | {
+    status: "degraded";
+    delivered: "plain-text";
+    reason: string;
+} | {
+    status: "cancelled";
+} | {
+    status: "error";
+    code: string;
+    message: string;
+    retryable: boolean;
+};
+/** Clipboard and download for a non-browser runtime (MV3 service worker, Tauri — CONTRACT R8). */
+interface TransportPort {
+    copy(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;
+    download(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;
+}
+interface AssetResolverPort {
+    resolve(url: string, signal: AbortSignal): Promise<{
+        url: string;
+    } | null>;
+}
+type ServerResult = {
+    status: "bytes";
+    filename: string;
+    mime: string;
+    bytes: Uint8Array;
+    notices: readonly {
+        code: string;
+        sentence: string;
+        remedy: string;
+    }[];
+} | {
+    status: "receipt";
+    receipt: {
+        status: string;
+        sentence: string;
+        remedy?: string;
+    };
+};
+interface ServerPort {
+    call(operationId: string, input: Json, signal: AbortSignal): Promise<ServerResult>;
+}
+
+/**
+ * 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 })` — answers with the
+ *                started run's `MandateRunRef`; the result streams later on `run:<requestId>`
+ *   "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">;
+
+/**
+ * `createSurfacePort` — the one SurfacePort runtime (Applets CONTRACTS §6 + Amendment 2.1).
+ *
+ * A parent surface offers every Action and value it has; a user's or organization's surface
+ * extends it. This is the runtime a host binds once and hands to a frame:
+ *
+ *   mount          reads the chain from the DATABASE (`readSurfaceChain`); the frame's `parent`
+ *                  argument names the same thing and is not trusted over it
+ *   get/setValue   the surface's named values, cloned both ways; `setValue` emits `value:<name>`
+ *   listActions    never throws — a refusal goes to `ports.diagnostics` and answers `[]`
+ *   runAction      found by name in the mounted chain (or a fresh read), run through
+ *                  `runSurfaceAction` (the one runner); an Action that `updatesValue` sets it
+ *   completeAction settles a pending page-Action run by its runId
+ *
+ * Page Actions: with `opts.pageActions` the host routes them (e.g. to the frame that declared the
+ * surface) and may park the run with `awaitPageAction(runId)`. Without it the port routes them
+ * itself: it emits `"actions"` `{ action, input, runId, by }` and waits for `completeAction`.
+ * `dispose()` settles every run this port parked with `host_disposed`.
+ *
+ * The package never imports the host or supabase: the client is structural (`./client.ts`), and
+ * every capability arrives as a port. Nothing here picks an organization.
+ */
+
+/** The stream a self-routed page Action travels on (CONTRACTS Amendment 2.1). */
+declare const PAGE_ACTION_STREAM = "actions";
+/** The stream a surface value travels on. */
+declare const valueStream: (name: string) => string;
+/** What travels on `"actions"`; the frame answers with `surface.completeAction(runId, result)`. */
+interface PageActionEvent {
+    action: string;
+    input: unknown;
+    runId: string;
+    by?: ActionCaller;
+}
+/** The runner's ports the host binds; page Actions are routed by `pageActions` / the port itself. */
+type SurfacePortRunPorts = Omit<SurfaceActionPorts, "pageActions">;
+/** One settle function per parked page-Action run. */
+type PendingPageActions = Map<string, (result: ActionResult<unknown>) => void>;
+interface CreateSurfacePortOptions {
+    /** A supabase-js v2 client carrying the VIEWER's session. Typed `object` on purpose (see ./client.ts). */
+    client: object;
+    /** ALL of the viewer's memberships, for organization extensions. Absent = extensions are dropped. */
+    organizationIds?: () => Promise<readonly string[]>;
+    /** The viewer's user id, stamped on every run's context. */
+    viewerId?: () => Promise<string | null>;
+    /** The runner's capabilities. `diagnostics` is required; each absent port = that capability is absent. */
+    ports: SurfacePortRunPorts;
+    /** The host's own page-Action routing. Absent = the port emits `"actions"` and waits for `completeAction`. */
+    pageActions?: PageActionPort;
+    /**
+     * The host's event hub: `value:<name>` on `setValue`, and `"actions"` for self-routed page Actions.
+     * Return `false` when nobody is subscribed to the stream — a self-routed page Action is then
+     * refused `action_unhandled` instead of waiting for an answer that cannot come.
+     */
+    emit(stream: string, payload: unknown): void | boolean;
+    /** Values seeded at mount; a value already set is never overwritten. */
+    seedValues?: () => Promise<Record<string, unknown>>;
+    /** The surface to read when nothing is mounted yet (e.g. the Applet's own `applets/<id>`). */
+    surfaceName?: () => Promise<string>;
+    /** Most ancestors a surface may have. */
+    maxDepth?: number;
+    /** Ids for mounts (`"mount"`) and runs (`"act"`). */
+    mintId?: (prefix: string) => string;
+    /**
+     * Share ONE map across the ports of one host tree, so a frame answering on its own host settles a
+     * run another host routed to it. Absent = this port's own map.
+     */
+    pending?: PendingPageActions;
+}
+interface SurfacePortHandle extends SurfacePort {
+    /** Park a page-Action run until `completeAction(runId, …)` (or `dispose()`) settles it. */
+    awaitPageAction(runId: string): Promise<ActionResult<unknown>>;
+    /** Settle every run this port parked with `host_disposed`, and forget the mount and values. */
+    dispose(): void;
+}
+declare function createSurfacePort(opts: CreateSurfacePortOptions): SurfacePortHandle;
+
+/**
+ * The few reads the surface runtime makes through the VIEWER's supabase client, typed STRUCTURALLY.
+ *
+ * Alchemy never imports supabase or the host (package rule 13). Deliberately not
+ * `SupabaseClient<Database>` either: a generated `Database` type makes `schema().from().select()`
+ * enormous and a host passing its typed client hits TS2589. The host hands its client in as an
+ * `object`; the ONE cast lives in `asSurfaceClient`, and every read names its schema out loud.
+ *
+ * Holds no key and opens no connection: the client carries the person's session, so row security
+ * decides every answer.
+ */
+
+/** What a supabase-js read resolves with. */
+interface SurfaceReadAnswer {
+    data: unknown;
+    error: {
+        message: string;
+        code?: string;
+        details?: string;
+        hint?: string;
+    } | null;
+}
+/** The filter chain the reads use — a subset of supabase-js's `PostgrestFilterBuilder`. */
+interface SurfaceReadChain extends PromiseLike<SurfaceReadAnswer> {
+    eq(column: string, value: unknown): SurfaceReadChain;
+    in(column: string, values: readonly unknown[]): SurfaceReadChain;
+    is(column: string, value: null): SurfaceReadChain;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): SurfaceReadChain;
+    maybeSingle(): PromiseLike<SurfaceReadAnswer>;
+}
+/** The part of a supabase-js v2 client the surface runtime reads through. */
+interface SurfaceClient {
+    schema(name: string): {
+        from(table: string): {
+            select(columns: string): SurfaceReadChain;
+        };
+    };
+}
+
+export { APPLET_SURFACE_PREFIX, type ActionCaller, type ActionContext, type ActionInfo, type ActionResult, type CreateSurfacePortOptions, type MandateRunRef, PAGE_ACTION_STREAM, type PageActionEvent, type PendingPageActions, type ReadSurfaceChainOptions, type SurfaceClient, type SurfacePort, type SurfacePortHandle, type SurfacePortRunPorts, type SurfaceReadAnswer, type SurfaceReadChain, createSurfacePort, readSurfaceChain, surfaceActionVisible, valueStream };