@docstack/client 0.1.6 → 0.2.0

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.
  *
@@ -296,6 +311,15 @@ export interface DocStackSyncOptions extends Omit<StackSyncOptions, "remote"> {
      * Which stacks to sync. Defaults to all of them.
      */
     stacks?: string[];
+    /**
+     * The tenant entitlement this replication serves, compiled into per-stack
+     * configuration by {@link deriveTenantScope}: stacks outside the scope are not
+     * synced at all - withheld structurally, not filtered - and stacks holding a mix of
+     * declarations get a class filter. Combines with `stacks` (which pre-narrows the
+     * candidates) but not with `classes`, whose slot the compiled rules occupy; narrow
+     * further with `filter`. See ADR-0030.
+     */
+    tenants?: string[];
 }
 /**
  * Every stack's replication under one object.
@@ -315,6 +339,13 @@ export declare class DocStackSyncHandle extends EventTarget {
     readonly handles: Map<string, StackSyncHandle>;
     /** @internal - use {@link DocStack.sync}. */
     add(name: string, handle: StackSyncHandle): void;
+    /** The stacks this handle covers. What is missing from this list is not
+     *  replicating - compare against `DocStack.getStacks()`, or use
+     *  `DocStack.getSyncCoverage()` which does exactly that. */
+    get names(): string[];
+    /** @internal - use {@link DocStack.removeStack}. Cancels and drops one stack's
+     *  replication; the rest are untouched. */
+    remove(name: string): boolean;
     /** Every stack's status, keyed by stack name. */
     getStatus(): Record<string, SyncStatus>;
     /**
@@ -331,4 +362,6 @@ export { createReplicationFilter, isInternalDoc, resolveInternalClasses, INTERNA
 export type { InternalDocFilterOptions } from "./internal-docs.js";
 export { createClassFilter, hasClassRules, DATA_MODEL_CLASSES } from "./class-filter.js";
 export type { ClassFilterOptions } from "./class-filter.js";
+export { deriveTenantScope, classTenants } from "./tenants.js";
+export type { TenantScope } from "./tenants.js";
 export { withFilterIdentity, describeFilter, composeFilterIdentity } from "./filter-identity.js";

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

@@ -0,0 +1,67 @@
+import type { ClassModel } from "@docstack/shared";
+import type { ClassFilterOptions } from "./class-filter.js";
+import type ClientStack from "../stack.js";
+/**
+ * Tenant scoping for replication channels.
+ *
+ * A tenant is a stack (ADR-0030). `Class.tenants` declares which tenant spaces a class
+ * belongs to - a static list, so partitioning and channel scopes are derivable before
+ * any data exists. This module compiles a channel's *entitlement* (the tenants it may
+ * see) into configuration the sync layer already understands: which stacks the channel
+ * is served at all, and a class filter for stacks holding a mix of declarations.
+ *
+ * The split matters (ADR-0030 §5): the *partition* is the datamodel's, but the
+ * *entitlement* is the serving side's to grant - it cannot come from the datamodel,
+ * because every application ships its own model and none is authoritative about the
+ * others' entitlements. Enforcement then rides the existing filter chain, which is a
+ * conjunction: a derived filter can only narrow what the declarations admit.
+ *
+ * The strongest grant here is the one that is not a filter at all: a stack outside the
+ * scope is simply never served, so its namespace is unreachable rather than filtered.
+ *
+ * @module
+ */
+/** A channel's entitlement, compiled into sync configuration. */
+export interface TenantScope {
+    /**
+     * Stacks this entitlement is served at all. A stack not listed is withheld
+     * structurally - no replication is started against it, which is a stronger grant
+     * than any filter.
+     */
+    stacks: string[];
+    /**
+     * Class rules per served stack, present only where the stack needs them: an
+     * `exclude` where classes declared for other tenants share an entitled stack, an
+     * `include` where a stack is served only because entitled classes live in it.
+     */
+    classes: Record<string, ClassFilterOptions>;
+}
+/**
+ * Normalizes a class model's tenant declaration.
+ *
+ * @param model - Any object carrying (or omitting) a `tenants` declaration.
+ * @returns The declared tenant names; empty for a tenant-neutral class.
+ */
+export declare const classTenants: (model: Partial<Pick<ClassModel, "tenants">> | null | undefined) => string[];
+/**
+ * Compiles an entitlement into the stacks it reaches and the class rules it needs.
+ *
+ * A stack is served when its name is an entitled tenant - a tenant *is* a stack - or
+ * when it holds at least one class declared for an entitled tenant. Within a served
+ * stack:
+ *
+ * - classes declared for an entitled tenant travel;
+ * - tenant-neutral classes follow their stack: they travel when the stack itself is the
+ *   entitled tenant, which is what keeps a datamodel with no declarations at today's
+ *   behavior exactly;
+ * - classes declared only for other tenants are excluded.
+ *
+ * Resolved once per call, the way the sync layer resolves ephemeral classes when a
+ * replication starts (ADR-0028): a declaration that changes later takes effect on the
+ * next `sync()`, never silently mid-stream.
+ *
+ * @param stacks - The candidate stacks, typically every open stack.
+ * @param entitlement - The tenant names this channel may see.
+ * @returns Which stacks to serve, and per-stack class rules where needed.
+ */
+export declare const deriveTenantScope: (stacks: ClientStack[], entitlement: string[]) => Promise<TenantScope>;

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;
+}

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

@@ -0,0 +1,26 @@
+import Class from "../class.js";
+import type ClientStack from "../stack.js";
+import { TransactionStage, StagedEntry } from "./stage.js";
+/**
+ * Resolves a class from the transaction's own stage: the ADR-0043 rule
+ * (the batch outranks the store - it is what is about to be committed) applied to
+ * staging. A patch chain's job can create documents of a class an earlier patch
+ * staged (ADR-0044), and the sweep must judge them by that staged model, not by a
+ * committed predecessor or a not-found. Built DETACHED - `Class.get` + `setModel`,
+ * never `buildFromModel`, which writes rev-less models (ADR-0043).
+ */
+export declare const classFromStage: (stack: ClientStack, stage: TransactionStage, className: string) => Class | null;
+/**
+ * The validation sweep - the transaction's atomicity boundary in practice.
+ *
+ * Runs read-only checks against public stack APIs: it decides whether a document
+ * *could* be written, and touches nothing. Stage time runs it so a bad write fails at
+ * the call site with zero consequences; commit re-runs it so the batch is judged
+ * against the world as it stands at commit. The commit-time pipeline (the plugin's
+ * `bulkDocs`) remains the sole authority - this sweep is a deliberate subset, and a
+ * document it passes can still be refused there, atomically for the whole batch.
+ */
+export declare const sweepEntry: (stack: ClientStack, stage: TransactionStage, entry: StagedEntry, options?: {
+    allowClassModels?: boolean;
+    skipPolicy?: boolean;
+}) => Promise<void>;

package/lib/index.d.ts

@@ -1,5 +1,16 @@
 import { DocStack } from "./core/index.js";
 export { ClientStack, Class, Domain, Attribute, Trigger, DocStack } from "./core/index.js";
+/**
+ * Running jobs unattended.
+ *
+ * `JobEngine` executes a job when asked; `JobScheduler` decides when to ask, under the
+ * constraints a client imposes — an app that is closed most of the time, timers that
+ * freeze, several devices holding replicas of the same `~Job`, and job content that
+ * replicates and is executable. It is mounted at `stack.jobScheduler` and started by the
+ * application, which names the jobs allowed to run with nobody watching.
+ */
+export { JobEngine, JobScheduler, JOB_SCHEDULE_DOC_ID, parseSchedule, nextOccurrence } from "./core/index.js";
+export type { SchedulerOptions, SchedulerHost, JobScheduleState, TickReport, SkipReason, ParsedSchedule, } from "./core/index.js";
 /**
  * The sync layer: lifecycle, filtering, convergence state and the schema gate.
  *
@@ -7,15 +18,25 @@ export { ClientStack, Class, Domain, Attribute, Trigger, DocStack } from "./core
  * application hands over, so DocStack never learns about Google Drive, Firestore or
  * anything else, and no consumer pays for a transport it does not use.
  */
-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, StackWriteGuardError, StackLockedError, deriveKeyId, isEncryptedPayload, } from "./core/index.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, StackWriteGuardError, StackLockedError, deriveKeyId, isEncryptedPayload, deriveTenantScope, classTenants, } from "./core/index.js";
 export { SYSTEM_SEEDED_DOC_IDS, collectQueryClasses } from "./core/index.js";
 export type { EncryptedPayload, ClassBuildOptions } from "./core/index.js";
+/**
+ * Named write transactions (ADR-0039).
+ *
+ * Opt-in per stack via `transactions: true`. A handle stages validated writes in
+ * memory and reads its own staged state overlaid on committed state; `commit`
+ * flushes the journal as one batch through the full authoring pipeline, and the
+ * report states the storage adapter's honest atomicity guarantee.
+ */
+export { TransactionEngine, TransactionHandle, TransactionDb, TransactionsDisabledError, TransactionStateError, TransactionValidationError, TransactionConflictError, TransactionUnsupportedDocError, } from "./core/index.js";
+export type { TransactionCommitReport, TransactionStatus } from "./core/index.js";
 /**
  * Moving application content between stacks, without the datamodel that describes it.
  */
 export { CONTENT_EXPORT_FORMAT, META_CLASSES, isContentClassName, isContentDocument, isContentRelation, } from "./core/index.js";
 export type { ContentExport, ContentExportOptions, ContentImportOptions, ContentImportReport, ContentImportIssue, } from "./core/index.js";
-export type { SyncDirection, SyncState, SyncStatus, StackSyncOptions, DocStackSyncOptions, RemoteResolver, SyncMetaDoc, InternalDocFilterOptions, ClassFilterOptions, } from "./core/index.js";
+export type { SyncDirection, SyncState, SyncStatus, StackSyncOptions, DocStackSyncOptions, RemoteResolver, SyncMetaDoc, InternalDocFilterOptions, ClassFilterOptions, TenantScope, } from "./core/index.js";
 /**
  * Document-modelling types, re-exported from `@docstack/shared`.
  *
@@ -26,5 +47,5 @@ export type { SyncDirection, SyncState, SyncStatus, StackSyncOptions, DocStackSy
  * Note that `Document` shadows the DOM's global `Document` in whichever module imports
  * it; alias it (`import type { Document as DocStackDocument }`) in code that needs both.
  */
-export type { AttributeType, AttributeTypeConfig, AttributeModel, ClassModel, DomainModel, TriggerModel, Document, RelationDocument, Patch, SelectAST, UnionAST, ClientCredentials, DocstackReady, StackConfig, StackOptions, } from "@docstack/shared";
+export type { AttributeType, AttributeTypeConfig, AttributeModel, ClassModel, DomainModel, TriggerModel, Document, RelationDocument, Patch, PatchJob, SelectAST, UnionAST, ClientCredentials, DocstackReady, StackConfig, StackOptions, } from "@docstack/shared";
 export default DocStack;