@ai-matrx/alchemy 0.6.2 → 0.8.2

package/dist/actions.d.cts

@@ -0,0 +1,773 @@
+import { TransferOutcome } from '@ai-matrx/kit/content-transfer';
+
+/**
+ * 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;
+/** Live slot payloads (page-capture's shapes, kept). */
+interface LiveValues {
+    selection?: {
+        choices: Record<string, Json$1>;
+        text: string | null;
+    };
+    "on-demand"?: readonly OnDemandSection[];
+    errors?: readonly string[];
+    requests?: readonly RecentRequest[];
+}
+interface OnDemandSection {
+    id: string;
+    title: string;
+    description?: string;
+    role: "data" | "request";
+    brief?: Json$1;
+    load(signal: AbortSignal): Promise<Json$1>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json$1;
+    requestBodyNote?: string;
+    errorSentence?: string;
+    timestamp: number;
+}
+/** RAW-FREE. What leaves the package about a clicked item. */
+interface ResolvedItem {
+    itemType: string;
+    identity: Record<string, string>;
+    level?: string;
+    readOnly: boolean;
+}
+
+/**
+ * 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 six universal verbs — the ONLY rows that may grey (R1 c). */
+declare const UNIVERSAL_VERBS: readonly ["copy", "cut", "paste", "undo", "redo", "find"];
+type UniversalVerb = (typeof UNIVERSAL_VERBS)[number];
+/** 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;
+}
+
+/**
+ * `@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`
+ *
+ * ALC-17 adds approvals/bodies/receipts.
+ *
+ * ── 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
+ *
+ * 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;
+}
+/** 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>;
+}
+
+/**
+ * Matrx Alchemy — Actions types (CONTRACT §2.4).
+ *
+ * One registry of everything a person can do to a thing. Providers plug in;
+ * eligibility is computed from what is declared at the click target; duplicate
+ * ids are refused; an action that does not apply is ABSENT (chair ruling R1).
+ *
+ * Framework-neutral: zero React, zero `@ai-matrx/agents`. Icons are string KEYS
+ * resolved by the host's `IconResolverPort`; labels go through `I18nPort`.
+ */
+
+/**
+ * Chair ruling R1: an action that does not apply or cannot run now is ABSENT.
+ * Only the six universal verbs may answer "unavailable-verb": greyed in the
+ * strip/bar, the sentence as tooltip. `requiresAuth` is NOT unavailability.
+ */
+type Eligibility = {
+    status: "absent";
+} | {
+    status: "available";
+} | {
+    status: "unavailable-verb";
+    verb: UniversalVerb;
+    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";
+declare const ACTION_CATEGORIES: readonly ActionCategory[];
+/**
+ * An optional named section inside the action's group (a grid's cell / row /
+ * column). `primary` marks the thing the person clicked: every layout renders
+ * it first, inline, heading kept (context-menu-v3's primary section law).
+ */
+interface ActionSection {
+    id: string;
+    label: string;
+    labelKey?: string;
+    icon?: string;
+    primary?: boolean;
+}
+interface Action {
+    /** Globally unique. A duplicate is refused (never overwritten). */
+    id: string;
+    /** The provider that registered it — filled by the registry. */
+    provider?: string;
+    /** Resolved through I18nPort.t(labelKey ?? id, label). */
+    label: string | ((target: ClickTarget) => string);
+    labelKey?: string;
+    /** Icon KEY resolved by IconResolverPort — the model stays framework-neutral. */
+    icon?: string;
+    /** Host styling hint for the glyph (rich-document iconColor). Renderers may ignore it. */
+    iconTone?: string;
+    /** Replaces `icon` while a state holds (a spinner while speaking). */
+    stateIcon?(target: ClickTarget): {
+        icon: string;
+        spin?: boolean;
+    } | null;
+    hint?: string;
+    hintKey?: string;
+    description?: string;
+    category: ActionCategory;
+    /** Which universal verb this clipboard action is (addressed by role in every layout). */
+    verb?: UniversalVerb;
+    order?: number;
+    /** Bar layout slot. Default "overflow". */
+    placement?: "primary" | "overflow" | "both";
+    section?: ActionSection;
+    /** A signed-out person still sees it; running goes through AuthResumePort (sign in, then resume). */
+    requiresAuth?: boolean;
+    /** Declared write targets this action lands through. Absent on a read-only target. */
+    writes?: readonly string[];
+    destructive?: boolean;
+    preserveSelection?: boolean;
+    /** Link rows navigate instead of running. */
+    href?: string | ((target: ClickTarget) => string);
+    eligible(target: ClickTarget): Eligibility;
+    /** Toggle/pressed state: a pressed button or a checked row. */
+    pressed?(target: ClickTarget): boolean;
+    /** Present = the row is a checkbox (pressed is its state). */
+    toggle?: boolean;
+    subscribe?(onChange: () => void, target: ClickTarget): () => void;
+    /** Submenus whose rows load on open (agent lists). */
+    expand?(target: ClickTarget, signal: AbortSignal): Promise<readonly Action[]>;
+    /** Shown centred when `expand` resolves empty. */
+    emptyLabel?: string;
+    run(target: ClickTarget, context: ActionRunContext): Promise<TransferOutcome | void> | TransferOutcome | void;
+}
+/** One removed read, recorded (kit content-transfer's omission shape). */
+interface ReadOmission {
+    path: string;
+    reason: "excluded" | "filtered";
+    classification?: "secret" | "credential";
+}
+/**
+ * PROJECTION BEFORE PROVIDERS. Providers never receive a raw read. Every read
+ * they can make is projected first: secret and credential values, values
+ * declared `exportable: false`, and values nobody declared are removed, with an
+ * omission recorded. Raw reads never leave the package.
+ */
+interface ProjectedReads {
+    values(signal: AbortSignal): Promise<{
+        values: Record<string, Json$1>;
+        omissions: readonly ReadOmission[];
+    }>;
+    item(signal: AbortSignal): Promise<{
+        values: Record<string, Json$1>;
+        omissions: readonly ReadOmission[];
+    } | null>;
+    live(signal: AbortSignal): Promise<LiveValues>;
+}
+/**
+ * What a running action receives. `door` (ALC-17) and `operate` (ALC-16) join
+ * with their waves; until then those capabilities are absent (N8).
+ */
+interface ActionRunContext {
+    reads: ProjectedReads;
+    ports: AlchemyHostPorts;
+    signal: AbortSignal;
+}
+interface ActionProvider {
+    id: string;
+    /** T0 providers are known at mount; T1 providers load with the menu on first open. */
+    tier: "T0" | "T1";
+    /**
+     * The ids this provider can ever yield, when known up front. Lets the
+     * registry refuse a duplicate at registration instead of at first open.
+     */
+    declaredIds?(): readonly string[];
+    actions(target: ClickTarget): readonly Action[] | Promise<readonly Action[]>;
+}
+interface ResolvedAction {
+    action: Action;
+    eligibility: Exclude<Eligibility, {
+        status: "absent";
+    }>;
+}
+interface ResolveRestriction {
+    exclude?: readonly string[];
+    categories?: readonly ActionCategory[];
+}
+interface ActionRegistry {
+    /** Throws DuplicateActionError naming both providers; nothing is overwritten. */
+    register(provider: ActionProvider): () => void;
+    /** restrict: a host may remove ids or categories, never add ineligible ones. */
+    resolve(target: ClickTarget, restrict?: ResolveRestriction): Promise<readonly ResolvedAction[]>;
+    /** Registered provider ids, in registration order. */
+    providers(): readonly string[];
+    /** Change notification (a provider registered or unregistered). */
+    subscribe(listener: () => void): () => void;
+}
+
+/**
+ * The one action registry (CONTRACT §2.4).
+ *
+ * - Duplicate ids are REFUSED, never overwritten (rich-document's registry
+ *   silently overwrote — R12). A duplicate known at registration throws; one
+ *   that only appears when a provider yields it is dropped and captured.
+ * - Eligibility is one pure pass over the resolved click target, under
+ *   "restrict, never relax": a host may remove ids or categories, never add.
+ * - R1: an action that does not apply is ABSENT. Only the six universal verbs
+ *   (category "clipboard") may answer `unavailable-verb`, with a sentence; any
+ *   other action answering it is a contract break → absent + diagnostics.
+ */
+
+declare class DuplicateActionError extends Error {
+    readonly actionId: string;
+    readonly providers: readonly [string, string];
+    constructor(actionId: string, first: string, second: string);
+}
+declare class DuplicateProviderError extends Error {
+    readonly providerId: string;
+    constructor(providerId: string);
+}
+interface ActionRegistryOptions {
+    /** `diagnostics` is required (nothing fails silently); `auth` decides whether requiresAuth actions reach a signed-out person. */
+    ports: Pick<AlchemyHostPorts, "diagnostics" | "auth">;
+}
+/**
+ * Eligibility of one action at one target — the ONE pure pass (CONTRACT §1.6).
+ * Exported for providers' tests; hosts call `registry.resolve`.
+ */
+declare function computeEligibility(action: Action, target: ClickTarget, options: {
+    restrict?: ResolveRestriction;
+    authResumable: boolean;
+}): Eligibility | {
+    status: "contract-break";
+    reason: string;
+};
+declare function createActionRegistry(options: ActionRegistryOptions): ActionRegistry;
+/** A provider over a fixed list; its ids are declared up front so duplicates fail at registration. */
+declare function staticActionProvider(id: string, actions: readonly Action[], tier?: ActionProvider["tier"]): ActionProvider;
+/** Always-available eligibility, for actions with no rule of their own. */
+declare const alwaysEligible: () => Eligibility;
+
+/**
+ * `@ai-matrx/alchemy/declare/host` — HOST-BINDING types only (CONTRACT §2.1, §2.6).
+ * Never imported by providers (`/declare`, `/actions`, `/menu`, `/operate` see only
+ * the raw-free `ResolvedItem`). Types only: no runtime code.
+ */
+
+interface ItemAnchor {
+    /** The host element the person clicked. */
+    element: unknown;
+    level?: string;
+}
+/** Raw item reads: consumed only by projection and the write handler that owns the target. */
+interface InternalResolvedItem extends ResolvedItem {
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+/** A mounted instance of a declared surface. Structural handle, never a global name lookup. */
+interface MountedSurface {
+    instanceId: string;
+    surfaceName: string;
+    isMounted(): boolean;
+    /** Same revision before and after a read, or capture refuses with "surface-changed". */
+    getRevision?(): string;
+    unsavedChanges?(): boolean;
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+    readLive?(signal: AbortSignal): Promise<LiveValues>;
+    resolveItem?(anchor: ItemAnchor): InternalResolvedItem | null;
+}
+
+interface ProjectionSource {
+    surface: MountedSurface | null;
+    declaration: ResolvedSurfaceDeclaration | null;
+    item: InternalResolvedItem | null;
+}
+/** Keep declared, ordinary, exportable values; record every removal. */
+declare function projectValues(raw: Record<string, unknown>, declared: readonly Pick<DeclaredValue, "name" | "sensitivity">[], pathPrefix?: string): {
+    values: Record<string, Json$1>;
+    omissions: ReadOmission[];
+};
+declare function createProjectedReads(source: ProjectionSource): ProjectedReads;
+
+interface ClickTargetInput {
+    surface?: ClickTarget["surface"];
+    declaration?: ResolvedSurfaceDeclaration | null;
+    item?: ResolvedItem | null;
+    level?: string | null;
+    selection?: ClickTarget["selection"];
+    payloadKinds?: ClickTarget["payloadKinds"];
+    /** Defaults to the item's readOnly (or false). */
+    readOnly?: boolean;
+    /** Extra exclusions on top of the declaration's own. */
+    excludedActionIds?: Iterable<string>;
+    scopeChain?: readonly string[];
+    organizationId?: string | null;
+    auth?: Partial<ClickTarget["auth"]>;
+    /** Write targets the host can serve right now; defaults to every declared target for the screen/item. */
+    writable?: readonly WriteTarget[];
+    host?: unknown;
+}
+declare function createClickTarget(input?: ClickTargetInput): ClickTarget;
+
+/**
+ * The one run path (T1e). Every layout runs an action through here, so the
+ * sign-in-then-resume rule, projection and failure capture live once.
+ */
+
+interface RunActionOptions {
+    ports: AlchemyHostPorts;
+    /** Raw sources; projected before the action sees them. */
+    source?: ProjectionSource;
+    /** Stable fingerprint of the content, for sign-in-then-resume. */
+    contentFingerprint?: string;
+    signal?: AbortSignal;
+}
+type RunResult = {
+    status: "ran";
+    outcome: TransferOutcome | void;
+} | {
+    status: "auth-pending";
+} | {
+    status: "failed";
+    error: unknown;
+};
+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 };