@ai-matrx/alchemy 0.6.2 → 0.8.2

package/dist/index.d.cts

@@ -1 +1,595 @@
-export * from '@ai-matrx/kit/content-transfer';
+/**
+ * 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 Payload = 
+/** A text payload may name its language (code blocks): downloads take its extension, Markdown fences it. */
+{
+    kind: "text";
+    text: string;
+    language?: string;
+} | {
+    kind: "markdown";
+    text: string;
+} | {
+    kind: "json";
+    value: Json;
+} | {
+    kind: "rows";
+    rows: Record<string, Json>[];
+    columns: Column[];
+} | {
+    kind: "registered";
+    format: string;
+    value: Json;
+};
+type Column = {
+    id: string;
+    label: string;
+    path: string;
+    visible: boolean;
+    exportable?: boolean;
+    classification?: "ordinary" | "secret" | "credential";
+    /** Declared field shape suitable for a projected table-schema export. */
+    schema?: {
+        dataType?: string;
+        order?: number;
+        required?: boolean;
+        defaultValue?: Json;
+        validation?: Json;
+        metadata?: Json;
+    };
+};
+type ExportProjection = {
+    rules: {
+        target: "payload" | "row";
+        path: string;
+        exportable: boolean;
+        classification: "ordinary" | "secret" | "credential";
+    }[];
+};
+type TransferScope = "target" | "row" | "selected" | "view" | "loaded" | "all-matching";
+type Section = {
+    id: string;
+    label: string;
+    path: string;
+    includedByDefault: boolean;
+};
+type Coverage = {
+    status: "complete" | "loaded" | "partial" | "unknown";
+    included: number;
+    total: number | null;
+    reason?: string;
+};
+type Omission = {
+    path: string;
+    reason: "excluded" | "filtered" | "truncated" | "unsupported" | "escaped" | "duplicate";
+    count?: number;
+};
+type RawSnapshot = {
+    id: string;
+    sourceId: string;
+    revision: string;
+    capturedAt: string;
+    label: string;
+    payload: Payload;
+    coverage: Coverage;
+    unsavedChanges: boolean;
+    omissions: Omission[];
+    sections: Section[];
+    limits?: TransferLimits;
+};
+declare const projected: unique symbol;
+type Snapshot = RawSnapshot & {
+    readonly [projected]: true;
+};
+type QuerySnapshot = {
+    sourceId: string;
+    revision: string;
+    query: Json;
+    order: {
+        field: string;
+        direction: "asc" | "desc";
+    }[];
+};
+type ExportPage = {
+    rows: Record<string, Json>[];
+    nextCursor: string | null;
+    coverage: Coverage;
+    consistencyToken: string | null;
+};
+type CapturedAllMatching = {
+    query: QuerySnapshot;
+    getRowId(row: Record<string, Json>): string;
+    page(request: {
+        query: QuerySnapshot;
+        cursor: string | null;
+        consistencyToken: string | null;
+        signal: AbortSignal;
+    }): Promise<ExportPage>;
+    stableSnapshot?: boolean;
+};
+type CapturedSource = {
+    snapshot: RawSnapshot;
+    projection: ExportProjection;
+    allMatching?: CapturedAllMatching;
+};
+type Source = {
+    id: string;
+    label: string;
+    capture(request: {
+        scope: TransferScope;
+        signal: AbortSignal;
+    }): Promise<CapturedSource>;
+};
+type Draft = {
+    snapshotId: string;
+    sourceId: string;
+    sourceRevision: string;
+    revision: number;
+    payload: Payload;
+    omissions: Omission[];
+    manuallyEdited: boolean;
+    provenance: {
+        kind: "original" | "deterministic" | "manual" | "ai";
+        operationId?: string;
+        description: string;
+    }[];
+    /** Frozen prior states, with history omitted to avoid recursive duplication. */
+    history?: readonly Omit<Draft, "history">[];
+};
+type Transform = {
+    id: string;
+    apply(draft: Draft, options: Json, signal: AbortSignal): Promise<Draft>;
+};
+type Artifact = {
+    snapshotId: string;
+    draftRevision: number;
+    format: string;
+    plainText: string;
+    html?: string;
+    file?: {
+        filename: string;
+        mime: string;
+        bytes: Uint8Array;
+    };
+    omissions: Omission[];
+};
+/** A concrete destination receipt; opening an editor is not a persisted save. */
+type TransferTarget = {
+    kind: string;
+    id: string;
+    label: string;
+    href?: string;
+};
+type TransferOutcome = {
+    status: "success";
+    delivered: "clipboard" | "download-started" | "action";
+    mimeTypes: string[];
+    /** Host-provided completion text for an explicit page action. */
+    message?: string;
+    target?: TransferTarget;
+} | {
+    status: "degraded";
+    delivered: "plain-text";
+    reason: string;
+}
+/**
+ * Accepted for review; NOTHING was written and NOTHING failed.
+ *
+ * A destination whose organization reviews this kind of change first answers
+ * "filed, waiting for a person" — a queued write is neither a delivery nor a
+ * failure, and reporting it as either lies in one of two directions: claiming
+ * a record that does not exist, or telling someone their work was lost while
+ * it sits in a queue with their name on it.
+ *
+ * It carries the same sentence/remedy pair the other members carry, both
+ * REQUIRED: `message` is what happened in the host's own words, `remedy` is
+ * the half that sentence never states — what has NOT happened yet and what
+ * the person does next. `target`, when the host can name it, is the pending
+ * request itself (the approval row, which exists and opens) and NEVER the
+ * destination record, which does not exist yet.
+ */
+ | {
+    status: "queued";
+    message: string;
+    remedy: string;
+    target?: TransferTarget;
+} | {
+    status: "cancelled";
+} | {
+    status: "error";
+    code: string;
+    message: string;
+    retryable: boolean;
+    target?: TransferTarget;
+};
+type Transport = {
+    copy(artifact: Artifact, signal: AbortSignal): Promise<TransferOutcome>;
+    download(artifact: Artifact, signal: AbortSignal): Promise<TransferOutcome>;
+};
+type SurfaceHandle = {
+    instanceId: string;
+    surfaceName: string;
+    isMounted(): boolean;
+    capture(signal: AbortSignal): Promise<CapturedSource>;
+};
+type AiPreparation = {
+    supports(snapshot: Snapshot): boolean;
+    run(request: {
+        snapshot: Snapshot;
+        draft: Draft;
+        instruction: string;
+        signal: AbortSignal;
+    }): Promise<Draft>;
+    /** Create an isolated adapter session for one preparation workspace. */
+    fork?(): AiPreparation;
+    /** Cancel the retained provider request; closing a host UI does not imply this. */
+    cancel?(): Promise<void>;
+    /** Revalidate the frozen source and recover a previously saved provider result. */
+    recover?(input: {
+        snapshot: Snapshot;
+        draft: Draft;
+        signal: AbortSignal;
+    }): Promise<Draft>;
+};
+type TransferLimits = {
+    maxRows: number | null;
+    maxStringChars: number | null;
+    maxDepth: number | null;
+    maxArrayItems?: number | null;
+    targetTokens: number | null;
+};
+type TransferPreferences = {
+    initialFormat: string;
+    initialPreset: "full" | "compact" | "brief";
+    limits: TransferLimits;
+};
+type PageAction = {
+    /** Alternate click-time source, captured through the same projection and limits before run. */
+    source?: Source;
+    id: string;
+    label: string;
+    supports(snapshot: Snapshot, draft?: Draft): boolean;
+    run(request: {
+        snapshot: Snapshot;
+        draft: Draft;
+        signal: AbortSignal;
+    }): Promise<TransferOutcome>;
+};
+
+/** Matrx's portable, source-labelled envelope for external AI tools. */
+interface AgentPayloadInput {
+    kind: string;
+    location: string;
+    description: string;
+    data: unknown;
+    summary?: string;
+    attributes?: Record<string, string | number | boolean | null | undefined>;
+    context?: Record<string, string | number | boolean | null | undefined>;
+}
+interface AgentPayloadEnvironment {
+    url?: string;
+    route?: string;
+    capturedAt?: string;
+}
+/** A fence longer than any content fence prevents accidental Markdown closure. */
+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;
+
+declare class ContentTransferError extends Error {
+    readonly code: string;
+    readonly path: string | undefined;
+    constructor(code: string, message: string, path?: string);
+    /**
+     * One error class across every loaded copy: while `@ai-matrx/kit/content-transfer`
+     * still bundles this module for its not-yet-repointed consumers (ALC-16), an
+     * error raised by one copy is `instanceof` the other.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/** A realm-wide brand (Symbol.for), so a binding made by one loaded copy is recognised by another. */
+declare const bound: unique symbol;
+type BoundAllMatching = {
+    readonly [bound]: true;
+    readonly source: CapturedAllMatching;
+    readonly projection: ExportProjection;
+    readonly columns: readonly Column[];
+    readonly limits?: TransferLimits;
+};
+type NormalizeTransferJsonOptions = {
+    omitUndefinedObjectProperties?: boolean;
+};
+declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json;
+/** Column ids are identities, never an alternative data address. */
+declare function readTransferCell(row: Record<string, Json>, column: Column): Json | 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;
+}>): CapturedSource;
+declare function capture(source: Source | Payload, signal: AbortSignal, scope?: TransferScope): Promise<{
+    snapshot: Snapshot;
+    allMatching?: BoundAllMatching;
+}>;
+declare function createDraft(s: Snapshot): Draft;
+declare const editDraft: (d: Draft, p: Payload) => Draft;
+declare const resetDraft: (s: Snapshot) => Draft;
+declare const sourceChanged: (d: Draft, s: Snapshot) => boolean;
+declare function undoDraft(d: Draft): Draft;
+/** Keep and regenerate are explicit choices; observing fresh data never overwrites edits. */
+declare function refreshDraft(draft: Draft, snapshot: Snapshot, choice: "keep" | "regenerate"): Draft;
+declare function applySectionSelection(d: Draft, s: Snapshot, ids: readonly string[]): Draft;
+declare function transformRows(d: Draft, o: {
+    search?: string;
+    sort?: {
+        column: string;
+        direction: "asc" | "desc";
+    };
+    filters?: Readonly<Record<string, string>>;
+    /** Positions in this call's input draft rows; unlike ids, no guessed key is used. */
+    selectedIndices?: readonly number[];
+    selectedIds?: readonly string[];
+    idColumn?: string;
+    visibleColumns?: readonly string[];
+    structuredProjection?: "full" | "visible";
+    top?: number | null;
+}): Draft;
+declare function reduceJson(draft: Draft, options: {
+    exclude?: readonly string[];
+    maxDepth?: number | null;
+    maxStringChars?: number | null;
+    maxArrayItems?: number | null;
+}): Draft;
+declare function collectAllMatching(c: BoundAllMatching, signal: AbortSignal): Promise<{
+    rows: Record<string, Json>[];
+    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;
+declare function serialize(draft: Draft, format: "plain" | "markdown" | "json" | "compact-json" | "csv" | "tsv" | "html", options?: {
+    spreadsheetSafe?: boolean;
+    filename?: string;
+}): Artifact;
+declare function createBrowserTransport(): Transport;
+type TransferPreferenceOverrides = Partial<Omit<TransferPreferences, "limits">> & {
+    limits?: Partial<TransferLimits>;
+};
+/** Restrictions intersect: neither a menu nor a provider can relax a source limit. */
+declare function resolveTransferPreferences(provider?: TransferPreferenceOverrides, menu?: TransferPreferenceOverrides, sourceLimits?: Partial<TransferLimits>): TransferPreferences;
+/** One stable id per registered format or action; ambiguous overrides fail loudly. */
+declare function resolveTransferRegistry<T extends {
+    id: string;
+}>(...groups: readonly (readonly T[])[]): readonly T[];
+type TransferSurfaceDeclaration = {
+    surfaceName: string;
+    label?: string;
+    values: readonly {
+        name: string;
+        label: string;
+        exportable?: boolean;
+        classification?: "ordinary" | "secret" | "credential";
+        includedByDefault?: boolean;
+    }[];
+};
+/** A structural adapter to the actual mounted surface, never a global name lookup. */
+declare function createSurfaceTransferHandle(options: {
+    instanceId: string;
+    manifest: TransferSurfaceDeclaration;
+    isMounted(): boolean;
+    getScope(): Record<string, unknown> | Promise<Record<string, unknown>>;
+    getRevision?(): string;
+    unsavedChanges?(): boolean;
+    projection?: ExportProjection;
+    limits?: TransferLimits;
+}): SurfaceHandle;
+/** Applies explicit preparation/source limits with exact omissions; token target is advisory. */
+declare function applyTransferLimits(draft: Draft, limits: Partial<TransferLimits>): Draft;
+
+interface AssetResolverPort {
+    resolve(url: string, signal: AbortSignal): Promise<{
+        url: string;
+    } | null>;
+}
+
+/**
+ * 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.
+ */
+
+type Notice = {
+    code: string;
+    sentence: string;
+    remedy: string;
+};
+/** A reference to a declared write target (the write door arrives in ALC-17). */
+interface WriteTargetRef {
+    surfaceName?: string;
+    target: string;
+    item?: {
+        itemType: string;
+        identity: Record<string, string>;
+    };
+}
+/** What a person or agent asks Operate to do with a source. */
+type TransferOperation = {
+    kind: "copy";
+    format: string;
+} | {
+    kind: "download";
+    format: string;
+} | {
+    kind: "transform";
+    transform: string;
+    options?: Json;
+} | {
+    kind: "prepare-for-ai";
+    instruction?: string;
+} | {
+    kind: "send";
+    destination: WriteTargetRef;
+};
+/** The stable format ids. A registered row format adds its own id. */
+type BuiltInFormatId = "plain" | "markdown" | "rich-html" | "html" | "json" | "compact-json" | "csv" | "tsv" | "xlsx" | "pdf" | "docx" | "epub";
+interface FormatOptions {
+    filename?: string;
+    spreadsheetSafe?: boolean;
+    /** Markdown→HTML skin: the two page looks plus "inline" for the rich clipboard (styles on elements). */
+    skin?: "document" | "article" | "inline";
+    /** Rich clipboard destination profile (1.9a). A profile is its own action only when its bytes differ. */
+    profile?: "generic" | "google-docs" | "word";
+    /** Private or signed images → share-safe URLs before HTML is sealed (the host's `assets` port). */
+    assets?: AssetResolverPort;
+    /** Opt-in lazy code highlighting (default off; no highlighter is chosen yet — CONTRACT R19). */
+    highlightCode?: boolean;
+    onNotice?(notice: Notice): void;
+}
+interface FormatEngine {
+    build(draft: Draft, options: FormatOptions, signal: AbortSignal): Promise<Artifact>;
+}
+interface FormatAdapter {
+    id: BuiltInFormatId | (string & {});
+    label: string;
+    extension: string;
+    mime: string;
+    modes: readonly ("copy" | "download")[];
+    runsOn: "client";
+    supports(payload: Payload): boolean;
+    load(): Promise<FormatEngine>;
+}
+/** Work the client cannot do (Office generation/conversion, server PDF letters). */
+interface ServerOperation {
+    id: string;
+    label: string;
+    runsOn: "server";
+    /** Shown in the menu: the person is told this leaves the device. */
+    statement: string;
+    supports(payload: Payload): boolean;
+    /** Projected draft only; sensitivity already applied. */
+    toInput(draft: Draft): Json;
+}
+/** Delivery results: `copy` and `download` only ever deliver, degrade, cancel or fail (CONTRACT R16). */
+type DeliveryOutcome = Extract<TransferOutcome, {
+    status: "success" | "degraded" | "cancelled" | "error";
+}>;
+declare const sealed: unique symbol;
+/** Only `seal` (a preparation session or `sealArtifact`) produces one; delivery accepts nothing else. */
+type SealedArtifact = Artifact & {
+    readonly [sealed]: true;
+};
+/** Every send returns one (the write door's receipt shape, CONTRACT §2.3; the door itself is ALC-17). */
+type Receipt = {
+    status: "applied";
+    to: WriteTargetRef;
+    sentence: string;
+} | {
+    status: "queued";
+    to: WriteTargetRef;
+    sentence: string;
+    remedy: string;
+} | {
+    status: "refused";
+    to: WriteTargetRef;
+    reason: string;
+    sentence: string;
+    remedy: string;
+};
+interface Delivery {
+    copy(artifact: SealedArtifact, signal: AbortSignal): Promise<DeliveryOutcome>;
+    /**
+     * Safari: call SYNCHRONOUSLY inside the click. Writes a promise-valued ClipboardItem at once and
+     * resolves it with the sealed artifact's bytes when `seal` finishes — the same bytes as `copy`,
+     * never a rebuild. `html` says whether the format carries rich HTML (decided before sealing).
+     */
+    copyPending(artifact: Promise<SealedArtifact>, signal: AbortSignal, options?: {
+        html?: boolean;
+    }): Promise<DeliveryOutcome>;
+    download(artifact: SealedArtifact, signal: AbortSignal): Promise<DeliveryOutcome>;
+    /** Sends the sealed bytes through the write door (ALC-17). Without a door: refused, with a remedy. */
+    send(artifact: SealedArtifact, to: WriteTargetRef, via: "destination"): Promise<Receipt>;
+}
+
+/**
+ * Operate formats — one adapter per format, stable ids, synchronous eligibility, lazy engines
+ * (Matrx Alchemy CONTRACT §1.9 / §2.3, ALC-16).
+ *
+ * Built in (no heavy dependency): plain, markdown, json, compact-json, csv, tsv, rows→html.
+ * Loaded on first use: rich-html, html (documents), pdf, docx, epub (print's one Markdown→HTML
+ * engine and document writers) and xlsx (SheetJS). The heavy libraries are only ever reached
+ * through `import()`, so choosing plain text never downloads a PDF writer.
+ */
+
+declare function extensionForLanguage(language: string | undefined): string;
+/** THE format adapters. Order is menu order. Ids are stable; labels are what a person reads. */
+declare const FORMAT_ADAPTERS: readonly FormatAdapter[];
+/**
+ * The adapters for a payload, in menu order: built-ins first, then registered formats (a
+ * duplicate id is refused — a registered format can never shadow a built-in).
+ */
+declare function eligibleFormats(payload: Payload, registered?: readonly FormatAdapter[], mode?: "copy" | "download"): FormatAdapter[];
+/** Find an adapter by id (built-in or registered); an unknown id is an error with a remedy. */
+declare function formatAdapter(id: string, registered?: readonly FormatAdapter[]): FormatAdapter;
+
+/**
+ * The preparation workspace and delivery (CONTRACT §2.3, "exact bytes: preview = copy = download = send").
+ *
+ *   capture → draft edits → SEAL → copy / download / send, and delivery takes the sealed artifact as-is.
+ *
+ * `seal` builds once per (draft revision, format, options) and brands the result; `copy`,
+ * `copyPending`, `download` and `send` accept only a branded artifact and never rebuild, so the
+ * bytes a person previewed are the bytes that reach the clipboard, the file or the destination.
+ */
+
+/** Freeze an artifact's bytes and brand it; the only way to make a `SealedArtifact`. */
+declare function sealArtifact(artifact: Artifact): SealedArtifact;
+/** True only for an artifact `sealArtifact` (or a preparation session's `seal`) produced. */
+declare function isSealed(artifact: unknown): artifact is SealedArtifact;
+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>;
+    /** A manual edit. */
+    edit(payload: Payload): Draft;
+    /** Keep only these sections (ids from the snapshot). */
+    selectSections(ids: readonly string[]): Draft;
+    undo(): Draft;
+    /** Build once and seal; cached per (draft revision, format, options). */
+    seal(format: string, options: FormatOptions, signal: AbortSignal): Promise<SealedArtifact>;
+}
+interface PreparationOptions {
+    /** Transforms this session may run, by id (a duplicate id is refused). */
+    transforms?: readonly Transform[];
+    /** Registered row formats beside the built-ins (a duplicate id is refused). */
+    formats?: readonly FormatAdapter[];
+}
+declare function openPreparation(source: Source | Payload, scope: TransferScope, signal: AbortSignal, options?: PreparationOptions): Promise<PreparationSession>;
+/** Seal a draft directly (hosts without a workspace, e.g. a one-click "Copy as CSV"). */
+declare function sealDraft(draft: Draft, format: string, options: FormatOptions, signal: AbortSignal, formats?: readonly FormatAdapter[]): Promise<SealedArtifact>;
+/**
+ * The one delivery. `transport` defaults to the browser (clipboard + download link); a non-browser
+ * host binds its own (`TransportPort`). `send` needs the write door (ALC-17): without one it is
+ * refused with a remedy, never faked.
+ */
+declare function createDelivery(ports?: {
+    transport?: Transport;
+    door?: {
+        apply(request: {
+            to: WriteTargetRef;
+            value: unknown;
+            origin: "user";
+            via: "destination";
+        }): Promise<Receipt>;
+    };
+}): 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 };