@docstack/client 0.1.8 → 0.2.0

package/lib/core/stack.d.ts

@@ -9,6 +9,7 @@ import { JobEngine } from "./job-engine/index.js";
 import { JobScheduler } from "./job-engine/scheduler.js";
 import { PolicyEngine } from "./policy-engine/index.js";
 import { CryptoEngine } from "./crypto-engine/index.js";
+import { TransactionEngine, TransactionHandle, TransactionStage, TransactionCommitReport } from "./transaction-engine/index.js";
 import type { ContentExport, ContentExportOptions, ContentImportOptions, ContentImportReport } from "./content-transfer.js";
 export declare const BASE_SCHEMA: ClassModel["schema"];
 export declare const CLASS_SCHEMA: ClassModel["schema"];
@@ -168,6 +169,11 @@ declare class ClientStack extends Stack {
      * Handles key derivation (PBKDF2) and AES-GCM encryption.
      */
     cryptoEngine: CryptoEngine;
+    /**
+     * Named write transactions (ADR-0039). Dormant unless the stack was opened with
+     * `transactions: true`; see {@link beginTransaction}.
+     */
+    transactionEngine: TransactionEngine;
     schemaVersion: string | undefined;
     /**
      * The current authenticated user session, if any.
@@ -521,7 +527,64 @@ declare class ClientStack extends Stack {
      *
      * @param patches - Patches not yet present in this stack.
      */
+    /**
+     * The highest consumer patch version this device has applied, from the patch
+     * ledger - `null` when no consumer patch has ever applied (or they are all
+     * deferred, which for the schema gate is the same thing: the schema those
+     * patches install is not here yet). The sync layer folds this into what it
+     * publishes and compares, so consumer-schema skew between devices refuses at
+     * the gate instead of pulling documents this device's schema cannot describe
+     * (ADR-0040).
+     */
+    getConsumerSchemaVersion(): Promise<string | null>;
     private applyConsumerPatches;
+    /**
+     * The stack a patch job executes against (ADR-0044): reads see the chain
+     * transaction's overlay, writes stage into it - so a migration's data
+     * transformation lands in the same commit as the model it prepares, or not at
+     * all. While the stack is locked, class-aware reads of an encrypting class
+     * THROW instead of serving the null convention: a migration wants the refusal
+     * (a `requiresKey: false` job that was declared wrongly must fail loudly, and
+     * the chain converts that failure to a deferral). Raw reads (`db.find`) bypass
+     * the class-aware path by design and stay the author's responsibility.
+     */
+    private createPatchJobStack;
+    /**
+     * Runs one of a patch's one-shot jobs against the transaction facade. The run
+     * receipt is a `~JobRun` with NO `jobId` - patch jobs are deliberately never
+     * persisted as `~Job` documents, so there is no row to point at (`~sys-0.0.17`
+     * made the foreign key optional for exactly this) - carrying the patch
+     * identity in `runtimeArgs`. It writes DIRECTLY, win or lose: a failed
+     * migration's receipt is the troubleshooting trail and must survive the
+     * discard that protects everything else (ADR-0044).
+     */
+    private runPatchJob;
+    /**
+     * The ADR-0042 protocol: the whole pending chain stages through one internal
+     * transaction - patch N+1 hydrates against the classes patch N staged, so the
+     * ADR-0038 merge composes in memory before anything is real - propagation is
+     * validated dry with nothing kept, and one commit lands every staged doc (class
+     * models and data documents alike, since the mixed extension) as one batch
+     * through the unchanged pipeline, where real propagation runs. The ledger
+     * (ADR-0041) arms only after that commit; any refusal beforehand persists
+     * nothing and names the patch at fault.
+     */
+    private applyConsumerPatchChain;
+    /**
+     * Stages one patch's documents into the chain transaction. Hydration reads
+     * through the transaction's overlay, so an `_rev: "auto"` document merges onto
+     * what an earlier patch staged - or onto committed state when the chain has not
+     * touched it.
+     */
+    private stagePatch;
+    /**
+     * ADR-0042 §3 - propagation, validated dry: for every class the chain staged
+     * over a committed predecessor, run the schema delta across the class's
+     * committed documents and keep nothing. The point is the refusal - a document
+     * that cannot satisfy the new model fails here, before the first write, naming
+     * the patch, the document and the attribute.
+     */
+    private validateChainPropagation;
     /**
      * Decides whether applying a patch would write an encrypted attribute.
      *
@@ -532,6 +595,9 @@ declare class ClientStack extends Stack {
      * simulate schema evolution ahead of time.
      *
      * @param patch - The patch about to be applied.
+     * @param stagedSchema - Chain staging only (ADR-0042): resolves a class the
+     * current transaction already staged, so patch N+1 defers exactly as it would
+     * have when patch N had committed.
      * @returns `true` if any document in it belongs to a class with encrypted attributes.
      */
     private patchNeedsDocumentKey;
@@ -598,6 +664,34 @@ declare class ClientStack extends Stack {
     getLastDocId(): Promise<number>;
     getSystem(): Promise<SystemDoc>;
     private loadPatches;
+    /**
+     * Finds a patch's ledger entry, raw - ledger documents are read outside the
+     * `active: true` visibility convention because `active` carries the ledger's own
+     * meaning here: `true` is applied, `false` is deferred, absent is a legacy entry
+     * from before the flag (treated as applied). See ADR-0041.
+     */
+    private findPatchLedgerEntry;
+    /**
+     * Records a successful application: the ledger entry arms with `active: true` -
+     * flipping the deferral entry in place when one exists, so a replayed patch does
+     * not duplicate its record.
+     */
+    private recordPatchApplication;
+    /**
+     * Records a deferral: the patch is known but dormant (`active: false`), waiting
+     * on the document key. The entry is what makes a deferred device honest at the
+     * sync gate - {@link getConsumerSchemaVersion} does not count it.
+     */
+    private recordPatchDeferral;
+    /**
+     * The ADR-0038 half of patch hydration: `schema` does not ride the shallow
+     * merge, which would replace it wholesale - it merges attribute by attribute.
+     * A patch states only the attributes it changes, an absent attribute stays as
+     * stored, and an explicit `null` entry drops the attribute - from the model
+     * here, and from the documents when the write propagates. Shared by
+     * {@link applyPatch} and the chain staging of ADR-0042 so the two cannot drift.
+     */
+    private static mergePatchSchema;
     applyPatch: (patch: Patch) => Promise<string>;
     private applyPatches;
     checkSystem(): Promise<void>;
@@ -801,6 +895,27 @@ declare class ClientStack extends Stack {
      * Removes event listeners and terminates background workers.
      */
     close: () => void;
+    /**
+     * Opens a named write transaction (ADR-0039). Requires the stack to have been
+     * opened with `transactions: true`.
+     *
+     * Writes through the handle validate at the call site and stage in memory;
+     * reads through it see the staged state overlaid on committed state. Nothing
+     * reaches the database - or replication, or any other reader - until
+     * {@link commit}. `stack.db` stays live and unchanged next to open transactions:
+     * direct writes land immediately, and only touch a transaction by making its
+     * commit refuse when they advance a staged document's revision.
+     */
+    beginTransaction: () => TransactionHandle;
+    /**
+     * Flushes a transaction's staged writes as one batch through the authoring
+     * pipeline. On refusal - validation, or a document changed underneath - nothing
+     * is persisted and the transaction stays open. The report says what landed and
+     * on what storage guarantee (`adapter.atomicBatch`).
+     */
+    commit: (t: TransactionHandle | string) => Promise<TransactionCommitReport>;
+    /** Drops a transaction's staged writes. Idempotent. */
+    discardTransaction: (t: TransactionHandle | string) => void;
     /**
      * Retrieves a Class instance by name.
      * Results are cached for 15 minutes to improve performance.
@@ -900,6 +1015,26 @@ declare class ClientStack extends Stack {
         [key: string]: any;
         docs: T[];
     }>;
+    /**
+     * {@link findDocuments} with an optional transaction stage overlaid - the shared
+     * implementation, so a transaction's reads and ordinary reads run the identical
+     * pipeline (policy, decryption, field visibility) and cannot drift (ADR-0039).
+     *
+     * With a stage: the database's index cannot see staged documents, so the
+     * committed query runs unwindowed, staged ids mask their committed rows, staged
+     * matches join the set, and sort/skip/limit apply after the merge. A selector
+     * over a class the stage never touched skips all of that.
+     *
+     * @internal
+     */
+    findDocumentsForView: <T extends Document | RelationDocument = Document>(stage: TransactionStage | undefined, selector: {
+        [key: string]: any;
+    }, fields?: string[], skip?: number, limit?: number, sort?: {
+        [field: string]: "asc" | "desc";
+    }[]) => Promise<{
+        [key: string]: any;
+        docs: T[];
+    }>;
     /**
      * Runs raw fetched documents through the read pipeline: per-document policy
      * check, decryption, and field visibility. Shared by {@link findDocuments} and
@@ -1153,6 +1288,18 @@ declare class ClientStack extends Stack {
         rows: any;
         ast: (SelectAST | UnionAST)[];
     }>;
+    /**
+     * {@link query}'s implementation, with the executor's data source as a
+     * parameter: the executor reaches documents only through stack APIs, so a
+     * transaction hands in a facade that routes them at its overlay while everything
+     * else - parsing, binding, planning - stays exactly this code (ADR-0039).
+     *
+     * @internal
+     */
+    runQuery: (sql: string, params: any[], execStack: ClientStack) => Promise<{
+        rows: any;
+        ast: (SelectAST | UnionAST)[];
+    }>;
     /**
      * Executes a SQL query as an async stream of rows.
      *

package/lib/core/sync/index.d.ts

@@ -142,7 +142,9 @@ export declare class SyncSchemaMismatchError extends Error {
     readonly localVersion: string | undefined;
     /** The schema version the remote was last written with. */
     readonly remoteVersion: string;
-    constructor(stack: string, localVersion: string | undefined, remoteVersion: string);
+    /** Which half of the gate refused: the system schema, or the application's consumer patches. */
+    readonly scope: "system" | "consumer";
+    constructor(stack: string, localVersion: string | undefined, remoteVersion: string, scope?: "system" | "consumer");
 }
 /**
  * The document DocStack keeps on a remote to record which schema wrote it.
@@ -158,6 +160,12 @@ export interface SyncMetaDoc {
     _rev?: string;
     /** Highest schema version any device has pushed to this remote. */
     schemaVersion?: string;
+    /**
+     * Highest *consumer* patch version any device has pushed. The system version
+     * alone cannot see consumer-schema skew - two devices on the same build always
+     * agree on it, whatever their application patches are doing (ADR-0040).
+     */
+    consumerSchemaVersion?: string;
     /** Application version of the device that last wrote it, for diagnostics. */
     appVersion?: string;
     /** When it was last written. */
@@ -173,6 +181,13 @@ export interface SyncMetaDoc {
  * @returns The recorded version, or `null` for a remote nobody has written yet.
  */
 export declare const readRemoteSchemaVersion: (remote: PouchDB.Database) => Promise<string | null>;
+/**
+ * Reads the highest consumer patch version recorded on a remote.
+ *
+ * `null` for a remote nobody has written, or one written only by builds that
+ * predate the consumer half of the gate.
+ */
+export declare const readRemoteConsumerSchemaVersion: (remote: PouchDB.Database) => Promise<string | null>;
 /**
  * Records this device's schema version on a remote, if it is the newest seen.
  *
@@ -180,7 +195,7 @@ export declare const readRemoteSchemaVersion: (remote: PouchDB.Database) => Prom
  * @param schemaVersion - The local schema version; a missing value writes nothing.
  * @param appVersion - The local application version, stored for diagnostics.
  */
-export declare const publishSchemaVersion: (remote: PouchDB.Database, schemaVersion: string | undefined, appVersion?: string) => Promise<void>;
+export declare const publishSchemaVersion: (remote: PouchDB.Database, schemaVersion: string | undefined, appVersion?: string, consumerSchemaVersion?: string | null) => Promise<void>;
 /**
  * One stack's replication: its lifecycle, its filter, and its convergence state.
  *

package/lib/core/transaction-engine/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Errors of the transaction engine (ADR-0039).
+ *
+ * Every one of them leaves the database untouched: a transaction failure is a refusal,
+ * never a partial application. The one exception is named where it happens -
+ * a commit on a non-atomic adapter can land a subset, and that outcome is reported as
+ * a `partial` status on the handle, not thrown as one of these.
+ *
+ * @module
+ */
+/** Raised by `beginTransaction()` on a stack opened without `transactions: true`. */
+export declare class TransactionsDisabledError extends Error {
+    name: string;
+    constructor(stackName: string);
+}
+/** Raised when a handle is used in a state that cannot accept the operation. */
+export declare class TransactionStateError extends Error {
+    name: string;
+    constructor(transactionId: string, status: string, operation: string);
+}
+/**
+ * Raised when the validation sweep refuses a document - at stage time (the write is
+ * not staged) or at commit time (nothing is written, the transaction stays open).
+ */
+export declare class TransactionValidationError extends Error {
+    name: string;
+    /** The document that failed. */
+    readonly docId: string | undefined;
+    constructor(message: string, docId?: string);
+}
+/**
+ * Raised by commit when a staged document's base revision no longer matches the
+ * stored winner - a direct write, another transaction's commit, or replication moved
+ * it. Nothing is written; the transaction stays open for re-staging or discard.
+ */
+export declare class TransactionConflictError extends Error {
+    name: string;
+    readonly conflicts: {
+        id: string;
+        baseRev: string | undefined;
+        currentRev: string | undefined;
+    }[];
+    constructor(conflicts: {
+        id: string;
+        baseRev: string | undefined;
+        currentRev: string | undefined;
+    }[]);
+}
+/**
+ * Raised at stage time for documents transactions cannot carry: class models (their
+ * write propagates to other documents mid-pipeline and cannot be staged or rolled
+ * back - ADR-0039), `_local/` device state, and design documents.
+ */
+export declare class TransactionUnsupportedDocError extends Error {
+    name: string;
+    constructor(docId: string, reason: string);
+}

package/lib/core/transaction-engine/handle.d.ts

@@ -0,0 +1,165 @@
+import { Document } from "@docstack/shared";
+import type ClientStack from "../stack.js";
+import { TransactionStage, StagedEntry } from "./stage.js";
+import { MangoSort } from "./overlay.js";
+import type { TransactionEngine, TransactionCommitReport } from "./index.js";
+export type TransactionStatus = "open" | "committed" | "discarded" | "partial";
+/**
+ * One transaction: a private write journal plus a read view that overlays it on
+ * committed state (ADR-0039).
+ *
+ * Writes through the handle are validated at the call site (the sweep - failing
+ * stages nothing) and stage in memory; nothing reaches the database until
+ * {@link commit}, which flushes the journal as one batch through the stack's full
+ * authoring pipeline. Reads through the handle see the journal; `stack.db`, other
+ * handles, replication and live subscriptions see only committed state.
+ *
+ * @example
+ * ```typescript
+ * const t = stack.beginTransaction();
+ * await t.createDoc(null, "Task", { title: "write-up" });
+ * await t.db.put({ ...(await t.db.get("Task-77")), done: true });
+ * const drafted = await t.findDocuments({ "~class": { $eq: "Task" } });
+ * const report = await t.commit();   // or stack.commit(t)
+ * ```
+ */
+export declare class TransactionHandle {
+    readonly id: string;
+    /** @internal */
+    readonly stage: TransactionStage;
+    /** @internal - ids this handle minted, counted into the id counter after commit. */
+    readonly mintedIds: Set<string>;
+    /**
+     * True for handles DocStack mints for its own machinery (patch application,
+     * ADR-0042). Internal handles may stage class models; public ones refuse them.
+     * @internal
+     */
+    readonly internal: boolean;
+    private statusValue;
+    private readonly stack;
+    private readonly engine;
+    /** The db-like surface: staged writes, overlaid reads. */
+    readonly db: TransactionDb;
+    /** @internal */
+    constructor(stack: ClientStack, engine: TransactionEngine, id: string, internal?: boolean);
+    get status(): TransactionStatus;
+    /** @internal */
+    setStatus(status: TransactionStatus): void;
+    stagedCount(): number;
+    /** @internal */
+    assertWritable(operation: string): void;
+    /**
+     * Stages a write. The sweep runs first: a document that fails validation, policy,
+     * or the locked-stack check is not staged and the journal is untouched.
+     * @internal
+     */
+    stageWrite(doc: Document, op?: "write" | "delete"): Promise<StagedEntry>;
+    /**
+     * Creates or updates a document in the transaction - `stack.createDoc`'s UX with
+     * a staged destination: `docId: null` mints an id, an existing id merges params
+     * over the overlay-visible document.
+     */
+    createDoc(docId: string | null, type: string, params: {
+        [key: string]: any;
+    }): Promise<Document>;
+    /** Batch counterpart of {@link createDoc}; validated sequentially, fail-fast. */
+    createDocs(docs: {
+        docId: string | null;
+        params: {
+            [key: string]: any;
+        };
+    }[], type: string): Promise<Document[]>;
+    /** Soft-deletes in the transaction: the overlay stops showing the document under the default `active: true`. */
+    deleteDocument(docId: string): Promise<boolean>;
+    /** The stack's polished read, against this transaction's view. */
+    findDocuments<T extends Document = Document>(selector: {
+        [key: string]: any;
+    }, fields?: string[], skip?: number, limit?: number, sort?: MangoSort): Promise<{
+        [key: string]: any;
+        docs: T[];
+    }>;
+    /**
+     * SQL against this transaction's view. The executor reaches data only through
+     * stack APIs, so a facade routes them at the overlay; LIMIT/OFFSET pushdown and
+     * sort indexes are disabled while staged - staged documents exist in no index,
+     * so windows and orderings must be computed after the merge.
+     */
+    query(sql: string, ...params: any[]): Promise<{
+        rows: any;
+        ast: (import("@docstack/shared").SelectAST | import("@docstack/shared").UnionAST)[];
+    }>;
+    /** Flushes the journal - sugar for `stack.commit(t)`. */
+    commit(): Promise<TransactionCommitReport>;
+    /** Drops the journal - sugar for `stack.discardTransaction(t)`. */
+    discard(): void;
+}
+/**
+ * The handle's db-like surface. Writes stage; reads overlay. Not a Proxy over the
+ * guarded db on purpose: this object *has no* adapter methods or escape hatches to
+ * forward, so staging cannot become a fourth door around the authoring path.
+ */
+export declare class TransactionDb {
+    private readonly stack;
+    private readonly handle;
+    /** @internal */
+    constructor(stack: ClientStack, handle: TransactionHandle);
+    get(docId: string, options?: any): Promise<Document>;
+    bulkGet(request: {
+        docs: {
+            id: string;
+            rev?: string;
+        }[];
+    }): Promise<{
+        results: any[];
+    }>;
+    /**
+     * Raw-style Mango find over the transaction's view. Like `stack.db.find`, this
+     * skips the read pipeline (no policy filter, no decryption of committed rows);
+     * `findDocuments` on the handle is the polished read.
+     */
+    find(query: {
+        selector: {
+            [key: string]: any;
+        };
+        fields?: string[];
+        skip?: number;
+        limit?: number;
+        sort?: any;
+    }): Promise<{
+        docs: Document[];
+    }>;
+    put(doc: Document, options?: any): Promise<{
+        ok: true;
+        id: string;
+        rev?: string;
+        staged: true;
+    }>;
+    post(doc: Document): Promise<{
+        ok: true;
+        id: string;
+        rev?: string;
+        staged: true;
+    }>;
+    /** Hard removal, staged: the commit writes `_deleted: true`. Soft deletion is `handle.deleteDocument`. */
+    remove(doc: {
+        _id: string;
+        _rev?: string;
+    } | string, rev?: string): Promise<{
+        ok: true;
+        id: string;
+        staged: true;
+    }>;
+    /**
+     * Stages a batch. Validated sequentially - the first refusal unwinds every entry
+     * this call staged, so a failing batch stages nothing. Documents stage before
+     * relations, mirroring the commit batch, so a relation and its endpoint can
+     * arrive in one array in any order.
+     */
+    bulkDocs(docs: Document[] | {
+        docs: Document[];
+    }, options?: any): Promise<{
+        ok: true;
+        id: string;
+        staged: true;
+    }[]>;
+}

package/lib/core/transaction-engine/index.d.ts

@@ -0,0 +1,82 @@
+import type ClientStack from "../stack.js";
+import { TransactionHandle } from "./handle.js";
+export { TransactionHandle, TransactionDb } from "./handle.js";
+export type { TransactionStatus } from "./handle.js";
+export { TransactionStage } from "./stage.js";
+export type { StagedEntry, StagedOp } from "./stage.js";
+export { stageCoversSelector, mergeStageIntoResults, widenProjection } from "./overlay.js";
+export { classFromStage } from "./sweep.js";
+export { TransactionsDisabledError, TransactionStateError, TransactionValidationError, TransactionConflictError, TransactionUnsupportedDocError, } from "./errors.js";
+/** What one commit did, and on what guarantee. */
+export type TransactionCommitReport = {
+    transactionId: string;
+    /** Documents that landed, with their new revisions. */
+    written: {
+        id: string;
+        rev: string;
+    }[];
+    /** Documents that did not - possible only on adapters where `atomicBatch` is false. */
+    failed: {
+        id: string;
+        error: string;
+        name?: string;
+    }[];
+    /** Journal size at the moment commit ran. */
+    stagedCount: number;
+    durationMs: number;
+    /**
+     * The storage adapter's honest guarantee for this commit: `atomicBatch: true`
+     * means the batch landed (or failed) as one storage transaction; `false` means
+     * per-document results, mitigated by the rev pre-flight but not eliminated.
+     */
+    adapter: {
+        name: string;
+        atomicBatch: boolean;
+    };
+};
+/**
+ * Named write transactions for one stack (ADR-0039).
+ *
+ * Enabled per stack by `transactions: true` in its configuration - the flag only
+ * unlocks {@link begin}; direct writes stay immediate, and the framework's own
+ * writers (scheduler, jobs, sync) always write directly. The stage lives above the
+ * plugin: nothing a transaction does touches the database until commit, and commit
+ * is exactly one `stack.db.bulkDocs` through the full authoring pipeline.
+ */
+export declare class TransactionEngine {
+    private readonly stack;
+    private readonly enabled;
+    private readonly handles;
+    /** Commits serialize here so one commit's rev pre-flight cannot be invalidated by another's write. */
+    private commitChain;
+    constructor(stack: ClientStack, enabled: boolean);
+    isEnabled(): boolean;
+    /** How many transactions are currently open (or partial). */
+    openCount(): number;
+    begin(): TransactionHandle;
+    /**
+     * Opens a transaction for DocStack's own machinery - patch application
+     * (ADR-0042). Independent of the `transactions: true` config gate (the flag
+     * governs the consumer feature, not the framework's internals) and permitted to
+     * stage class models: an internal handle claims staged validation and a single
+     * class-write batch, never propagation atomicity.
+     * @internal
+     */
+    beginInternal(): TransactionHandle;
+    private resolve;
+    /**
+     * Drops a transaction's journal. Idempotent, and a no-op on a handle already in
+     * a terminal state - discarding what is already gone is not an error.
+     */
+    discard(t: TransactionHandle | string): void;
+    /** Discards every open transaction - what `close()` and `reset()` do. */
+    discardAll(): void;
+    /**
+     * Flushes a transaction's journal as one batch through the stack's authoring
+     * pipeline. Refusals - validation, or a staged document whose base revision
+     * moved - throw with nothing persisted and the transaction still open.
+     */
+    commit(t: TransactionHandle | string): Promise<TransactionCommitReport>;
+    private commitNow;
+    private adapterInfo;
+}

package/lib/core/transaction-engine/overlay.d.ts

@@ -0,0 +1,66 @@
+import { Document } from "@docstack/shared";
+import { TransactionStage } from "./stage.js";
+/** The sort shape `findDocuments` accepts. */
+export type MangoSort = {
+    [field: string]: "asc" | "desc";
+}[] | string[];
+/**
+ * True when a query with this selector could see documents this stage holds.
+ *
+ * Derived from the selector's `~class` / `~domain` constraint against the stage's
+ * partitions; a selector naming no class is answered conservatively. This is the
+ * per-query fast path: a find over a class the transaction never touched runs
+ * exactly as it would outside the transaction.
+ */
+export declare const stageCoversSelector: (stage: TransactionStage, selector: {
+    [key: string]: any;
+}) => boolean;
+/**
+ * Fields the widened committed query (and the staged docs) must carry beyond the
+ * caller's projection, so masking, sorting and the read pipeline can work; the
+ * extras are stripped again after the merge.
+ */
+export declare const widenProjection: (fields: string[] | undefined, sort: MangoSort | undefined) => {
+    queryFields: string[] | undefined;
+    extras: string[];
+};
+/**
+ * Merges a stage into a committed query result: every staged id masks its committed
+ * row (superseded and deleted alike), staged writes matching the selector join the
+ * set, then sort, window and projection apply in memory - the database's index can
+ * never see a staged document, so the window has to be computed after the union.
+ *
+ * `committedDocs` must come from a query WITHOUT skip/limit (the mask changes what
+ * the window contains) and carrying `widenProjection`'s fields.
+ */
+export declare const mergeStageIntoResults: (stage: TransactionStage, selector: {
+    [key: string]: any;
+}, committedDocs: Document[], options?: {
+    sort?: MangoSort;
+    skip?: number;
+    limit?: number;
+    fields?: string[];
+    extras?: string[];
+}) => Document[];
+/** A PouchDB-shaped `not_found`, so overlay reads refuse like the database does. */
+export declare const notFoundError: (id: string) => any;
+/**
+ * Read-your-writes for a point read: a staged delete is a 404, a staged write is the
+ * authored plaintext (its `_rev` is the base revision - the revision the commit will
+ * replace), anything else is the stack's ordinary decrypting read.
+ */
+export declare const overlayGet: (stack: {
+    db: any;
+}, stage: TransactionStage, id: string, options?: any) => Promise<Document>;
+/** `bulkGet` counterpart of {@link overlayGet}, preserving request order. */
+export declare const overlayBulkGet: (stack: {
+    db: any;
+}, stage: TransactionStage, request: {
+    docs: {
+        id: string;
+        rev?: string;
+    }[];
+    [key: string]: any;
+}) => Promise<{
+    results: any[];
+}>;

package/lib/core/transaction-engine/stage.d.ts

@@ -0,0 +1,50 @@
+import { Document } from "@docstack/shared";
+/** What one staged entry means for its document id. */
+export type StagedOp = "write" | "delete";
+export interface StagedEntry {
+    /** The authored document, plaintext, cloned at stage time. */
+    doc: Document;
+    /** The winning revision the entry was staged against; absent for a new document. */
+    baseRev?: string;
+    op: StagedOp;
+    /** True when the id did not exist (in stage or store) when first staged. */
+    isNew: boolean;
+    stagedAt: number;
+}
+/**
+ * The write journal of one transaction: authored documents keyed by id, in memory.
+ *
+ * Also partitioned by class (`~class`, or `~domain` for relations) so a read can ask
+ * "could this stage affect a query over class X" in O(1) - the overlay only pays the
+ * merge for queries whose class the transaction actually touched (ADR-0039).
+ */
+export declare class TransactionStage {
+    private entries;
+    private partitions;
+    private partitionKeys;
+    /**
+     * Stages an entry. Re-staging an id replaces the document but keeps the original
+     * `baseRev` and `isNew` - the conflict check is against the world as it was when
+     * the transaction first touched the id, not against its own previous draft.
+     */
+    set(id: string, entry: StagedEntry): void;
+    get(id: string): StagedEntry | undefined;
+    has(id: string): boolean;
+    get size(): number;
+    ids(): string[];
+    /** Entries in stage order (insertion order of first staging). */
+    values(): StagedEntry[];
+    hasPartition(name: string): boolean;
+    /** Keeps only the given ids - what a partial commit leaves behind. */
+    retain(ids: Set<string>): void;
+    /**
+     * A point-in-time copy of the journal, for {@link restore}. Used by the patch
+     * chain (ADR-0044) to unwind exactly one patch's staging - a pre-apply job's
+     * writes included - when a locked refusal converts that patch to a deferral
+     * while the already-staged prefix goes on to commit.
+     */
+    snapshot(): Map<string, StagedEntry>;
+    restore(snapshot: Map<string, StagedEntry>): void;
+    remove(id: string): void;
+    clear(): void;
+}