@ai-matrx/alchemy 0.8.18 → 0.8.20

package/dist/core.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 = null | boolean | number | string | Json[] | {
-    [key: string]: Json;
+type Json$1 = null | boolean | number | string | Json$1[] | {
+    [key: string]: Json$1;
 };
 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;
+    value: Json$1;
 } | {
     kind: "rows";
-    rows: Record<string, Json>[];
+    rows: Record<string, Json$1>[];
     columns: Column[];
 } | {
     kind: "registered";
     format: string;
-    value: Json;
+    value: Json$1;
 };
 type Column = {
     id: string;
@@ -38,9 +38,9 @@ type Column = {
         dataType?: string;
         order?: number;
         required?: boolean;
-        defaultValue?: Json;
-        validation?: Json;
-        metadata?: Json;
+        defaultValue?: Json$1;
+        validation?: Json$1;
+        metadata?: Json$1;
     };
 };
 type ExportProjection = {
@@ -91,21 +91,21 @@ type Snapshot = RawSnapshot & {
 type QuerySnapshot = {
     sourceId: string;
     revision: string;
-    query: Json;
+    query: Json$1;
     order: {
         field: string;
         direction: "asc" | "desc";
     }[];
 };
 type ExportPage = {
-    rows: Record<string, Json>[];
+    rows: Record<string, Json$1>[];
     nextCursor: string | null;
     coverage: Coverage;
     consistencyToken: string | null;
 };
 type CapturedAllMatching = {
     query: QuerySnapshot;
-    getRowId(row: Record<string, Json>): string;
+    getRowId(row: Record<string, Json$1>): string;
     page(request: {
         query: QuerySnapshot;
         cursor: string | null;
@@ -145,7 +145,7 @@ type Draft = {
 };
 type Transform = {
     id: string;
-    apply(draft: Draft, options: Json, signal: AbortSignal): Promise<Draft>;
+    apply(draft: Draft, options: Json$1, signal: AbortSignal): Promise<Draft>;
 };
 type Artifact = {
     snapshotId: string;
@@ -282,6 +282,16 @@ interface AgentPayloadEnvironment {
 declare function fenceJsonBlock(json: string): string;
 /** Capture location at invocation; environment injection makes non-browser use explicit. */
 declare function buildAgentPayload(input: AgentPayloadInput, environment?: AgentPayloadEnvironment): string;
+/**
+ * The envelope, plus where its JSON body sits: `body` is the exact JSON text written between the
+ * fence lines, starting at `bodyOffset` (so a span map of the body lands in the envelope at that
+ * offset — PP-06a).
+ */
+declare function assembleAgentPayload(input: AgentPayloadInput, environment?: AgentPayloadEnvironment): {
+    text: string;
+    body: string;
+    bodyOffset: number;
+};
 
 declare class ContentTransferError extends Error {
     readonly code: string;
@@ -306,9 +316,9 @@ type BoundAllMatching = {
 type NormalizeTransferJsonOptions = {
     omitUndefinedObjectProperties?: boolean;
 };
-declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json;
+declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json$1;
 /** Column ids are identities, never an alternative data address. */
-declare function readTransferCell(row: Record<string, Json>, column: Column): Json | undefined;
+declare function readTransferCell(row: Record<string, Json$1>, column: Column): Json$1 | 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;
@@ -347,13 +357,15 @@ declare function reduceJson(draft: Draft, options: {
     maxArrayItems?: number | null;
 }): Draft;
 declare function collectAllMatching(c: BoundAllMatching, signal: AbortSignal): Promise<{
-    rows: Record<string, Json>[];
+    rows: Record<string, Json$1>[];
     coverage: RawSnapshot["coverage"];
     omissions: Omission[];
     error?: ContentTransferError;
 }>;
 /** Preserve artifact-byte identity even if a consumer mutates a returned view. */
 declare function sealTransferArtifact(artifact: Artifact): Artifact;
+/** The columns a text serialization writes: visible, exportable, never secret or credential. */
+declare function exportedColumns(columns: readonly Column[]): Column[];
 declare function serialize(draft: Draft, format: "plain" | "markdown" | "json" | "compact-json" | "csv" | "tsv" | "html", options?: {
     spreadsheetSafe?: boolean;
     filename?: string;
@@ -393,11 +405,522 @@ 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;
 
+/** 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * `@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 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
+ *   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
+ *
+ * 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;
+}
+/**
+ * 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>;
+}
 
 /**
  * Operate — the format and delivery contract (Matrx Alchemy CONTRACT §2.3, ALC-16).
@@ -432,7 +955,7 @@ type TransferOperation = {
 } | {
     kind: "transform";
     transform: string;
-    options?: Json;
+    options?: Json$1;
 } | {
     kind: "prepare-for-ai";
     instruction?: string;
@@ -477,7 +1000,7 @@ interface ServerOperation {
     statement: string;
     supports(payload: Payload): boolean;
     /** Projected draft only; sensitivity already applied. */
-    toInput(draft: Draft): Json;
+    toInput(draft: Draft): Json$1;
 }
 /** Delivery results: `copy` and `download` only ever deliver, degrade, cancel or fail (CONTRACT R16). */
 type DeliveryOutcome = Extract<TransferOutcome, {
@@ -559,7 +1082,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, signal: AbortSignal): Promise<Draft>;
+    transform(id: string, options: Json$1, signal: AbortSignal): Promise<Draft>;
     /** A manual edit. */
     edit(payload: Payload): Draft;
     /** Keep only these sections (ids from the snapshot). */
@@ -594,4 +1117,108 @@ declare function createDelivery(ports?: {
     };
 }): Delivery;
 
-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, type ExportPage, type ExportProjection, FORMAT_ADAPTERS, type FormatAdapter, type FormatEngine, type FormatOptions, type Json, type NormalizeTransferJsonOptions, type Notice, type Omission, type PageAction, type Payload, type PreparationOptions, type PreparationSession, type QuerySnapshot, type RawSnapshot, type Receipt, type SealedArtifact, type Section, type ServerOperation, type Snapshot, type Source, type SurfaceHandle, type TransferLimits, type TransferOperation, type TransferOutcome, type TransferPreferenceOverrides, type TransferPreferences, type TransferScope, type TransferSurfaceDeclaration, type TransferTarget, type Transform, type Transport, type WriteTargetRef, applySectionSelection, applyTransferLimits, buildAgentPayload, capture, collectAllMatching, createBrowserTransport, createDelivery, createDraft, createSurfaceTransferHandle, directSource, editDraft, eligibleFormats, extensionForLanguage, fenceJsonBlock, formatAdapter, isSealed, normalizeTransferJson, openPreparation, projectSnapshot, readTransferCell, reduceJson, refreshDraft, resetDraft, resolveTransferPreferences, resolveTransferRegistry, sealArtifact, sealDraft, sealTransferArtifact, serialize, sourceChanged, transformRows, undoDraft };
+/**
+ * Serializer span maps (Preparation parity PP-06a): every node of the draft payload → the exact
+ * span of the SEALED text it became.
+ *
+ * A span map is computed from the sealed artifact's own `plainText` (the bytes the preview shows,
+ * the clipboard receives and the download holds), never from a second rendering of the draft — so
+ * a span can never describe text that is not there. Offsets are UTF-16 code units into
+ * `artifact.plainText`, `[start, end)`, exactly what `String.prototype.slice` and a DOM text range
+ * take.
+ *
+ * Paths are the JSON Pointers the rest of Operate already uses for omissions:
+ *   ""                    the whole payload (a text or Markdown payload is one node)
+ *   "/messages/0/content" a node inside a JSON payload
+ *   "/rows"               the row array (JSON formats of a rows payload)
+ *   "/rows/3"             one row (its whole line in CSV / TSV / Markdown / plain)
+ *   "/rows/3/name"        one cell (the column's own path under the row)
+ *   "/columns/name"       one header cell (CSV / TSV / Markdown / plain), keyed by column id
+ *
+ * Spans nest (a row contains its cells, an object its members) and never partially overlap.
+ * PP-06b–d (the structure trees) and PP-07 (the removed-text diff) highlight through this map.
+ */
+
+interface OutputSpan {
+    /** JSON Pointer of the node in the draft payload (see the module header). */
+    path: string;
+    /** UTF-16 offset of the node's first character in `artifact.plainText`. */
+    start: number;
+    /** UTF-16 offset one past the node's last character. */
+    end: number;
+}
+type SpanMap = readonly OutputSpan[];
+/**
+ * Spans of every value in a JSON text, found by reading the text itself (whatever writer laid it
+ * out: pretty, compact, minified, escaped). Pre-order: a container before its members.
+ * Throws when the text is not exactly one JSON value.
+ */
+declare function jsonTextSpans(text: string, basePath?: string, offset?: number): OutputSpan[];
+/**
+ * The span map of a sealed artifact built from `draft` (same snapshot, same draft revision).
+ * Covers the text formats the preparation workspace previews: plain, markdown, json,
+ * compact-json, csv, tsv, and html's plain text. Binary and document formats have no text to map
+ * and are refused by name.
+ */
+declare function spanMap(draft: Draft, artifact: Artifact): SpanMap;
+/** The same spans at `offset` characters later — a map carried inside a larger sealed text. */
+declare function offsetSpans(spans: SpanMap, offset: number): OutputSpan[];
+/**
+ * The AI envelope with the span map of its data: every node of `input.data` → its span in the
+ * envelope text. The body is read where the envelope wrote it, so the spans stay exact even where
+ * the envelope escapes `<`, `>` and `&`; for data without those characters they are the bare JSON's
+ * spans moved by exactly the envelope header.
+ */
+declare function agentPayloadWithSpans(input: AgentPayloadInput, environment?: AgentPayloadEnvironment): {
+    text: string;
+    spans: SpanMap;
+};
+
+/**
+ * Default preparation recipes (Preparation parity PP-13a): which recipe a preparation workspace
+ * opens with for one source kind, layered exactly like every setting on the platform —
+ *
+ *   the person's own default   (PersistencePort, setting "alchemy.transfer.default_recipe")
+ *   → the organization default (TransferKnobsPort — the Feature Knob ladder: organization → platform)
+ *   → built in                 (null recipe: the workspace opens on Full, nothing trimmed)
+ *
+ * The recipe KEY is the declaration / source-kind id (`"cx.conversation"`, `"data.table-rows"`), the
+ * same string in every host, so a recipe saved on the dashboard is the recipe the frontend opens.
+ * Both stores hold one map, source-kind id → recipe; this module is the only reader and writer of the
+ * person's map, so the merge rules live once.
+ *
+ * Nothing fails silently: a rung that cannot be read or holds a malformed value is skipped with a
+ * notice (and captured in diagnostics), and the answer says which rung it came from. A write never
+ * merges into a map it failed to read.
+ */
+
+/** The person's setting (PersistencePort) — one map of source-kind id → recipe. */
+declare const TRANSFER_DEFAULT_RECIPE_SETTING = "alchemy.transfer.default_recipe";
+type RecipeOrigin = "person" | "organization" | "built-in";
+interface ResolvedRecipe {
+    /** The recipe to open with; null = built in (Full, nothing trimmed). */
+    recipe: {
+        [key: string]: Json;
+    } | null;
+    from: RecipeOrigin;
+    /** Rungs that were skipped, each with what to do about it. */
+    notices: {
+        sentence: string;
+        remedy: string;
+    }[];
+}
+/** The recipe key for a source kind: the declaration / source-kind id itself, validated. */
+declare function recipeKey(sourceKind: string): string;
+type RecipePorts = Pick<AlchemyHostPorts, "persistence" | "transferKnobs" | "diagnostics">;
+/** Which recipe a workspace for `sourceKind` opens with, and where it came from. */
+declare function resolveDefaultRecipe(ports: RecipePorts, sourceKind: string, organizationId: string | null): Promise<ResolvedRecipe>;
+/**
+ * Set (recipe) or clear (null) the person's own default for one source kind, keeping every other
+ * source kind's default. Throws a sentence when nothing was saved; clearing the last entry clears
+ * the setting itself, so the person inherits the organization default again.
+ */
+declare function setPersonDefaultRecipe(ports: Pick<AlchemyHostPorts, "persistence">, sourceKind: string, recipe: {
+    [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, type ExportPage, type ExportProjection, FORMAT_ADAPTERS, type FormatAdapter, type FormatEngine, type FormatOptions, type Json$1 as Json, 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 ServerOperation, type Snapshot, type Source, type SpanMap, 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, applySectionSelection, applyTransferLimits, assembleAgentPayload, buildAgentPayload, capture, collectAllMatching, createBrowserTransport, createDelivery, createDraft, createSurfaceTransferHandle, directSource, editDraft, eligibleFormats, exportedColumns, extensionForLanguage, fenceJsonBlock, formatAdapter, isSealed, jsonTextSpans, normalizeTransferJson, offsetSpans, openPreparation, projectSnapshot, readTransferCell, recipeKey, reduceJson, refreshDraft, resetDraft, resolveDefaultRecipe, resolveTransferPreferences, resolveTransferRegistry, sealArtifact, sealDraft, sealTransferArtifact, serialize, setPersonDefaultRecipe, sourceChanged, spanMap, transformRows, undoDraft };