@docstack/client 0.1.6 → 0.2.0

package/lib/core/index.d.ts

@@ -3,6 +3,7 @@ import Class from "./class.js";
 import Domain from './domain.js';
 import { Trigger } from "./trigger/index.js";
 import { JobEngine } from "./job-engine/index.js";
+import { JobScheduler } from "./job-engine/scheduler.js";
 import Attribute from './attribute.js';
 import { AttributeType, ClientCredentials, StackConfig } from "@docstack/shared";
 import { DocStackSyncHandle } from './sync/index.js';
@@ -56,6 +57,13 @@ declare class DocStack extends EventTarget {
     private pendingStacks;
     /** The handle from the last {@link sync} call. */
     private syncHandle?;
+    /**
+     * What the last un-scoped {@link sync} call asked for, kept so a stack added
+     * later can be bound to the same replication. `null` when sync was never
+     * called, was called with an explicit `stacks` list (a caller who named three
+     * databases asked for three), or was cancelled. See ADR-0033.
+     */
+    private syncOptions;
     private logger;
     /**
      * Splits a {@link StackConfig} into the connection string and the options a stack
@@ -125,6 +133,25 @@ declare class DocStack extends EventTarget {
      * ```
      */
     sync: (options: DocStackSyncOptions) => Promise<DocStackSyncHandle>;
+    /**
+     * Binds one stack to the live sync, if there is one and it was un-scoped.
+     *
+     * Failure here must not fail {@link addStack} - the stack itself opened fine -
+     * but it must not be silent either, silence being this defect's whole shape:
+     * it is logged and dispatched as an `error` event on the sync handle.
+     */
+    private bindStackToSync;
+    /**
+     * Which open stacks the current sync covers, and which it does not.
+     *
+     * An idle stack and an unbound one are opposite problems, and `getStatus()`
+     * cannot tell them apart - the unbound one has no key at all. With no sync
+     * running, every open stack is unbound.
+     */
+    getSyncCoverage: () => {
+        bound: string[];
+        unbound: string[];
+    };
     /**
      * Returns the handle from the last {@link sync} call, or `null`.
      */
@@ -272,9 +299,13 @@ declare class DocStack extends EventTarget {
  *
  * @module @docstack/client
  */
-export { ClientStack, Trigger, Class, Attribute, Domain, JobEngine };
-export { StackSyncHandle, DocStackSyncHandle, SyncSchemaMismatchError, SYNC_META_DOC_ID, readRemoteSchemaVersion, publishSchemaVersion, createReplicationFilter, isInternalDoc, resolveInternalClasses, createClassFilter, hasClassRules, DATA_MODEL_CLASSES, withFilterIdentity, describeFilter, INTERNAL_DOC_IDS, INTERNAL_DOC_ID_PREFIXES, INTERNAL_DOC_CLASSES, OPTIONAL_INTERNAL_DOC_CLASSES, } from "./sync/index.js";
-export type { SyncDirection, SyncState, SyncStatus, StackSyncOptions, DocStackSyncOptions, RemoteResolver, SyncMetaDoc, InternalDocFilterOptions, ClassFilterOptions, } from "./sync/index.js";
+export { ClientStack, Trigger, Class, Attribute, Domain, JobEngine, JobScheduler };
+export { JOB_SCHEDULE_DOC_ID } from "./job-engine/scheduler.js";
+export type { SchedulerOptions, SchedulerHost, JobScheduleState, TickReport, SkipReason, } from "./job-engine/scheduler.js";
+export { parseSchedule, nextOccurrence, MIN_PERIOD_MS } from "./job-engine/schedule.js";
+export type { ParsedSchedule } from "./job-engine/schedule.js";
+export { StackSyncHandle, DocStackSyncHandle, SyncSchemaMismatchError, SYNC_META_DOC_ID, readRemoteSchemaVersion, readRemoteConsumerSchemaVersion, publishSchemaVersion, createReplicationFilter, isInternalDoc, resolveInternalClasses, createClassFilter, hasClassRules, DATA_MODEL_CLASSES, withFilterIdentity, describeFilter, INTERNAL_DOC_IDS, INTERNAL_DOC_ID_PREFIXES, INTERNAL_DOC_CLASSES, OPTIONAL_INTERNAL_DOC_CLASSES, deriveTenantScope, classTenants, } from "./sync/index.js";
+export type { SyncDirection, SyncState, SyncStatus, StackSyncOptions, DocStackSyncOptions, RemoteResolver, SyncMetaDoc, InternalDocFilterOptions, ClassFilterOptions, TenantScope, } from "./sync/index.js";
 export type { ClassBuildOptions } from "./class.js";
 export { CONTENT_EXPORT_FORMAT, META_CLASSES, isContentClassName, isContentDocument, isContentRelation, stripTransientFields, } from "./content-transfer.js";
 export type { ContentExport, ContentExportOptions, ContentImportOptions, ContentImportReport, ContentImportIssue, } from "./content-transfer.js";
@@ -282,6 +313,8 @@ export { SYSTEM_SEEDED_DOC_IDS } from "./datamodel/index.js";
 export { collectQueryClasses } from "./query-engine/index.js";
 export { StackWriteGuardError } from "./guarded-db.js";
 export { StackLockedError } from "../plugins/pouchdb.js";
+export { TransactionEngine, TransactionHandle, TransactionDb, TransactionsDisabledError, TransactionStateError, TransactionValidationError, TransactionConflictError, TransactionUnsupportedDocError, } from "./transaction-engine/index.js";
+export type { TransactionCommitReport, TransactionStatus } from "./transaction-engine/index.js";
 /**
  * Key-identity helpers, for applications that re-key a database.
  *

package/lib/core/job-engine/schedule.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The schedule grammar a client can actually honour.
+ *
+ * `JobModel.schedule` is a string, and the obvious thing to put in it is cron. Cron is
+ * not offered here, and the reason is not implementation cost: cron's entire vocabulary
+ * is about *naming occurrences* — "02:15 on the 3rd of every month" — and a client
+ * cannot promise to be running at an occurrence. It is a closed tab, a suspended app, a
+ * sleeping laptop. Accepting the syntax would promise a precision the runtime has no way
+ * to keep, and the failure would be silent: the job simply never runs on the 3rd.
+ *
+ * So the grammar says only what a client can honour, which is a floor rather than a
+ * moment: *not more often than this*.
+ *
+ * | Form | Meaning |
+ * | --- | --- |
+ * | `@every 30m`, `@every 6h`, `@every 7d` | Fixed interval since the last run. |
+ * | `@hourly` | Top of each local hour. |
+ * | `@daily` | Local midnight. |
+ * | `@daily@09:00` | A local wall-clock time. |
+ * | `@weekly` | Monday, local midnight. |
+ * | `@weekly@09:00` | Monday, at a local wall-clock time. |
+ *
+ * Anchored forms are computed against *local* time through `Date`, so they follow the
+ * device across daylight-saving changes: `@daily@09:00` stays 09:00 to the person
+ * reading the screen, which is the only definition of "nine" that a campaign cares
+ * about.
+ *
+ * @module
+ */
+/** Shortest interval `@every` will accept. Below this a client is polling, not scheduling. */
+export declare const MIN_PERIOD_MS = 30000;
+/** A schedule string after parsing. `source` is kept so callers can report what they read. */
+export type ParsedSchedule = {
+    kind: "interval";
+    source: string;
+    periodMs: number;
+} | {
+    kind: "hourly";
+    source: string;
+} | {
+    kind: "daily";
+    source: string;
+    minutes: number;
+} | {
+    kind: "weekly";
+    source: string;
+    weekday: number;
+    minutes: number;
+};
+/**
+ * Reads a schedule string, or returns `null` when it is not one.
+ *
+ * `null` is a value the scheduler acts on rather than an error to throw: a job document
+ * carrying a schedule nobody can parse should be skipped and reported, not allowed to
+ * take down the tick that would have run the other jobs.
+ *
+ * @example
+ * ```typescript
+ * parseSchedule("@every 6h");     // { kind: "interval", periodMs: 21600000, ... }
+ * parseSchedule("@daily@09:00");  // { kind: "daily", minutes: 540, ... }
+ * parseSchedule("0 9 * * *");     // null — cron is not accepted, see the module docblock
+ * ```
+ */
+export declare const parseSchedule: (schedule: string | null | undefined) => ParsedSchedule | null;
+/**
+ * The first moment this schedule comes due strictly after `from`.
+ *
+ * **The occurrences between the last run and `from` are not returned, and there is no
+ * way to ask for them.** That absence is the design: a device that was closed for a
+ * fortnight has missed fourteen occurrences of a daily job, and replaying them would run
+ * the campaign fourteen times over data that only justifies running it once. A sweep
+ * that reads current state does the right thing in a single pass; fourteen sweeps do the
+ * same thing plus a stampede.
+ *
+ * @param schedule - A parsed schedule.
+ * @param from - The instant to measure from, normally "now".
+ * @returns The next due timestamp, strictly greater than `from`.
+ */
+export declare const nextOccurrence: (schedule: ParsedSchedule, from: number) => number;
+/** The longest a schedule may legitimately wait — the ceiling used to detect a bad clock. */
+export declare const periodCeilingMs: (schedule: ParsedSchedule) => number;
+/**
+ * Whether a stored `nextRunAt` is too far in the future to have been computed honestly.
+ *
+ * The device clock belongs to the user: it can be wrong, and it can be set back. A run
+ * recorded while the clock read 2031 leaves a `nextRunAt` that would suppress the job for
+ * years once the clock is corrected. Anything further out than two periods did not come
+ * from this schedule, so the scheduler recomputes it from now rather than honouring it.
+ */
+export declare const isImplausible: (nextRunAt: number, schedule: ParsedSchedule, now: number) => boolean;

package/lib/core/job-engine/scheduler.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Running jobs unattended, on a client.
+ *
+ * {@link JobEngine} executes a job when something asks it to. This decides *when* to
+ * ask, on a device that a server-side scheduler's assumptions do not describe:
+ *
+ * 1. **The app is closed most of the time.** "Daily at 09:00" is missed on most days.
+ * 2. **Timers are throttled or frozen.** A background tab gets about one tick a minute;
+ *    a suspended app gets none, and `setInterval` does not catch up on wake.
+ * 3. **There are several instances.** Two devices, or two tabs, run this against
+ *    replicas of the same `~Job` documents.
+ * 4. **A run can vanish mid-flight.** A closed tab kills a `RUNNING` job with no
+ *    `catch`, no `finally`, and no process left to notice.
+ * 5. **The clock is the user's.** It can be wrong, and it can move backwards.
+ *
+ * Four rules answer those, and each is load-bearing:
+ *
+ * - **Missed occurrences collapse into one run** ({@link nextOccurrence}). Never a
+ *   backlog.
+ * - **Schedule state is device-local**, in a `_local/` document. `JobModel.nextRunTimestamp`
+ *   looks like the place for it and is not: an application's `~Job` documents replicate —
+ *   `DATA_MODEL_CLASSES` keeps them even under an `include` allow-list — so every device
+ *   would write that field on every run and collide on a document whose `content` field is
+ *   executable code. A losing revision there does not lose a timestamp, it forks what the
+ *   job does.
+ * - **Duplicate work is answered by the jobs, not by a lock.** Leader election needs a
+ *   consensus point that two offline replicas do not have. Jobs that run here must write
+ *   documents whose `_id` is derived from what they are about (`ReviewRequest-<orderId>`),
+ *   so a second device's sweep collides into one document instead of sending a second
+ *   email. The scheduler cannot enforce that; it is the price of running campaign logic
+ *   on clients.
+ * - **Only named jobs run unattended** ({@link SchedulerOptions.jobs}). `~Job.content` is
+ *   JavaScript, it replicates, and {@link Job} hydrates it with `new Function` — which
+ *   runs with full ambient authority, whatever the docs call it. Until now a human was
+ *   always behind an execution. An allow-list keeps that true: a job document arriving
+ *   over sync cannot become code that runs itself.
+ *
+ * @module
+ */
+import type { JobRunModel } from "@docstack/shared";
+/** The `_local/` document holding this device's schedule state. Never replicates. */
+export declare const JOB_SCHEDULE_DOC_ID = "_local/docstack-job-schedule";
+/** What the scheduler needs from a stack. Narrow on purpose, so it can be tested without one. */
+export interface SchedulerHost {
+    db: {
+        get: (id: string) => Promise<any>;
+        put: (doc: any) => Promise<any>;
+        bulkDocs: (docs: any[]) => Promise<any>;
+        find: (request: any) => Promise<{
+            docs: any[];
+        }>;
+    };
+    jobEngine: {
+        executeJob: (jobId: string, runtimeArgs?: Record<string, any>, triggerType?: string) => Promise<JobRunModel>;
+    };
+}
+/** Per-job bookkeeping, as stored in {@link JOB_SCHEDULE_DOC_ID}. */
+export interface JobScheduleState {
+    /** When this job next comes due on this device. */
+    nextRunAt: number;
+    /** When this device last dispatched it. */
+    lastRunAt?: number;
+    /** Outcome of that dispatch. */
+    lastStatus?: string;
+    /** Drives the backoff. Reset by any success. */
+    consecutiveFailures: number;
+    /** The schedule string this state was computed from; a change to it resets the state. */
+    schedule?: string;
+}
+/** Why a due-looking job was not dispatched. Reported rather than thrown. */
+export type SkipReason = "missing" | "disabled" | "no-schedule" | "unparseable-schedule" | "hash-mismatch" | "in-flight" | "not-due";
+export interface TickReport {
+    /** The instant the tick was evaluated at. */
+    at: number;
+    /** Jobs dispatched by this tick. They may still be running when the report is returned. */
+    dispatched: string[];
+    skipped: {
+        jobId: string;
+        reason: SkipReason;
+    }[];
+    /** Abandoned `RUNNING` runs moved to `CANCELED`. */
+    sweptRuns: number;
+}
+export interface SchedulerOptions {
+    /**
+     * Job ids allowed to run unattended.
+     *
+     * Required, and there is deliberately no "all": see the module docblock. Manual
+     * {@link JobEngine.executeJob} is unaffected — it already has a human behind it.
+     */
+    jobs: string[];
+    /**
+     * Expected `hash` per job, for jobs whose code must not change under the application.
+     *
+     * `JobModel.hash` is stored beside the content it certifies, so a peer that writes
+     * one writes the other: on its own it detects corruption, not authorship. Pinning the
+     * value *in application code* is what makes it mean something.
+     */
+    pinnedHashes?: Record<string, string>;
+    /** Floor between automatic ticks. Default 60s, minimum 5s. */
+    intervalMs?: number;
+    /** A `RUNNING` run older than this is swept to `CANCELED`. Default 15 minutes. */
+    staleRunMs?: number;
+    /** First retry delay after a failure; doubles per consecutive failure. Default 5 minutes. */
+    backoffBaseMs?: number;
+    /** Ceiling for that doubling. Default 6 hours. */
+    maxBackoffMs?: number;
+    /** Injectable clock, for tests. */
+    now?: () => number;
+    /** Called with each completed run, successful or not. */
+    onRun?: (run: JobRunModel) => void;
+}
+/**
+ * Decides when the jobs an application has approved should run, and dispatches them.
+ *
+ * Mounted at `stack.jobScheduler`, but never started by the stack: what may run
+ * unattended is the application's decision.
+ *
+ * @example
+ * ```typescript
+ * stack.jobScheduler.start({
+ *     jobs: ["Job-review-campaign", "Job-cross-sell"],
+ *     pinnedHashes: { "Job-review-campaign": "9f2c…" },
+ * });
+ *
+ * // Wake sources are the application's, because `core/` imports no DOM:
+ * document.addEventListener("visibilitychange", () => {
+ *     if (document.visibilityState === "visible") void stack.jobScheduler.tick();
+ * });
+ * ```
+ */
+export declare class JobScheduler {
+    private readonly host;
+    private options;
+    private timer;
+    /** Jobs this device has dispatched and not yet seen finish. */
+    private readonly inFlight;
+    /** Dispatches still running, so {@link drain} can wait for them. */
+    private readonly pending;
+    /** Deduplicates concurrent ticks — a wake signal and the interval can land together. */
+    private ticking;
+    /** Serialises read-modify-write of the `_local/` document. */
+    private stateWrites;
+    /** Last state read, for {@link status} — reporting must not require a database round-trip. */
+    private snapshot;
+    constructor(host: SchedulerHost);
+    /**
+     * Begins scheduling, and evaluates once immediately.
+     *
+     * The immediate evaluation is the point: a client's most reliable clock signal is
+     * "the app just opened", not a timer that was frozen while it was closed.
+     */
+    start(options: SchedulerOptions): void;
+    /**
+     * Stops scheduling. Jobs already dispatched keep running — a hydrated `new Function`
+     * has no cancellation, and pretending otherwise would leave a `RUNNING` run behind.
+     */
+    stop(): void;
+    /** Whether {@link start} is in effect. */
+    get isRunning(): boolean;
+    /**
+     * Evaluates every allowed job and dispatches those that are due.
+     *
+     * Idempotent and safe to call from any wake signal. Concurrent calls share one
+     * evaluation. It returns once dispatch has *started*: a long job does not hold the
+     * tick open, because a tick that waits is a tick that stops the others.
+     */
+    tick(): Promise<TickReport>;
+    /** Resolves when every job this scheduler started has finished. For teardown and tests. */
+    drain(): Promise<void>;
+    /** What the scheduler believes, without touching the database. */
+    status(): {
+        running: boolean;
+        inFlight: string[];
+        jobs: Record<string, JobScheduleState>;
+    };
+    private runTick;
+    /** Runs one job and records what happened. Never throws: a tick outlives its jobs. */
+    private dispatch;
+    private recordOutcome;
+    /**
+     * Moves this device's abandoned runs to `CANCELED`.
+     *
+     * A `~JobRun` only changes status inside `Job.execute`'s `try`/`catch`, so a tab
+     * closed mid-run leaves one `RUNNING` for ever — and `hasRunningInstance` then skips
+     * that singleton job on this device permanently. Unattended execution turns that from
+     * a latent oddity into a job that silently stops working, so the sweep runs before
+     * every dispatch. `~JobRun` never replicates, so these are unambiguously *this*
+     * device's abandoned runs.
+     */
+    private sweepAbandonedRuns;
+    private readState;
+    private writeState;
+    /**
+     * Read-modify-write against the `_local/` document, serialised.
+     *
+     * Everything that touches the state document goes through here - tick evaluation
+     * and outcome recording alike - so within this instance no write can land between
+     * another's read and write. Two *instances* (two tabs) still contend; there the 409
+     * in {@link writeState} stands, logged, and the jobs' own idempotency is the answer,
+     * as the module docblock requires of them.
+     */
+    private withState;
+    private track;
+}
+export default JobScheduler;

package/lib/core/stack.d.ts

@@ -6,8 +6,10 @@ import { StackSyncHandle } from "./sync/index.js";
 import type { StackSyncOptions, SyncStatus } from "./sync/index.js";
 import type { SelectAST, UnionAST } from "./query-engine/index.js";
 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"];
@@ -144,6 +146,19 @@ declare class ClientStack extends Stack {
      * ```
      */
     jobEngine: JobEngine;
+    /**
+     * Decides when approved jobs run, and dispatches them.
+     *
+     * Constructed with the stack but deliberately **not started by it**: `~Job.content`
+     * is JavaScript that replicates, so which jobs may run with nobody watching is the
+     * application's decision, named at {@link JobScheduler.start}.
+     *
+     * @example
+     * ```typescript
+     * stack.jobScheduler.start({ jobs: ['Job-review-campaign'] });
+     * ```
+     */
+    jobScheduler: JobScheduler;
     /**
      * Engine for enforcing read/write access control policies.
      * Policies are evaluated based on user session and document content.
@@ -154,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.
@@ -507,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.
      *
@@ -518,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;
@@ -584,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>;
@@ -787,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.
@@ -886,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
@@ -1139,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.
      *