@docstack/client 0.1.8 → 0.3.0

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

@@ -42,6 +42,18 @@ export declare class CryptoEngine {
      * interrupted, and resumed.
      */
     private retiredKeys;
+    /**
+     * Scope CEKs admitted by {@link admitScopeKey}, by key id (ADR-0045).
+     *
+     * The keyring the single document key generalizes into: reads dispatch by a
+     * payload's `kid` across the legacy key, retired keys, and these; writes
+     * into a scope-labeled document select through {@link scopeWriteKeys}. A
+     * scope whose CEK is absent here is simply LOCKED - its payloads stay
+     * sealed, which is the access decision.
+     */
+    private scopeKeys;
+    /** The read-write entry per scope id - the CEK that seals new writes. */
+    private scopeWriteKeys;
     private readonly logger;
     /** Reference to the parent stack. */
     private readonly stack;
@@ -106,6 +118,37 @@ export declare class CryptoEngine {
      * @returns Key identifiers; empty when no key is held.
      */
     getReadableKeyIds(): string[];
+    /**
+     * Admits a scope's CEK into the keyring after its canary verified
+     * (spec 02 §2.1 - admission is the caller's `verifyScopeCek` first, this
+     * second). The winning version of a scope enters read-write and becomes
+     * the key new writes into the scope seal under; older versions enter
+     * read-only, the retired-keys discipline applied per scope.
+     *
+     * @returns The admitted key's id.
+     */
+    admitScopeKey(scopeId: string, cekHex: string, version: number, mode: "read-write" | "read-only"): Promise<string>;
+    /**
+     * Tests a candidate CEK against a scope's canary WITHOUT admitting it -
+     * the ADR-0018 admission discipline per scope: a corrupted or
+     * rotated-away ciphertext is an error at unlock, not garbage later. The
+     * marker's AAD binds it to the scope and key it was minted for.
+     */
+    verifyScopeCek(scopeId: string, cekHex: string, marker: unknown): Promise<boolean>;
+    /** Whether new writes into this scope can seal - a read-write CEK is held. */
+    isScopeWritable(scopeId: string): boolean;
+    /** Scope ids holding a read-write CEK. */
+    unlockedScopeIds(): string[];
+    /** The key id new writes into a scope seal under, when the scope is open. */
+    getScopeWriteKeyId(scopeId: string): string | undefined;
+    /** The scope a held key id belongs to, if it is a scope key. */
+    scopeOfKid(kid: string): string | undefined;
+    /**
+     * Drops every admitted scope CEK - the session's material is gone, the
+     * scopes are locked again. Mirrors what clearing the document key does for
+     * the legacy path.
+     */
+    dropScopeKeys(): void;
     /**
      * Generates a cryptographically secure random string.
      * Useful for generating salts or nonces.
@@ -160,15 +203,23 @@ export declare class CryptoEngine {
     unwrapAndStoreDocumentKey(wrappedDocumentKey?: string | null, derivedKey?: string | null): Promise<string>;
     private getCryptoKey;
     /**
-     * Chooses the key that can open a payload.
+     * Chooses the keyring entry that can open a payload.
      *
      * A payload names its key, so an old field found mid-re-key is decrypted with the key
      * it was actually written under instead of failing against the current one. Payloads
-     * from before identifiers existed name nothing, and are tried against the current key
-     * - which is what they meant when only one key could exist.
+     * from before identifiers existed name nothing, and are tried against the LEGACY
+     * document key only (spec 02 §3): under multiple keys, falling back to "whatever is
+     * current" would silently mis-route - a scope key never answers for an unnamed
+     * payload.
      */
-    private resolveKeyFor;
+    private resolveEntryFor;
     private encryptValue;
+    /**
+     * @param label - The document's `~scope` at read time. A scope-sealed
+     * payload authenticates against it (AAD, spec 02 §2.3 rule 3): a tampered
+     * or stripped label fails the GCM authentication and the payload stays
+     * sealed - the mismatch is detected, never silently honored.
+     */
     private decryptValue;
     /**
      * Identifies which document keys contain encrypted data.
@@ -187,7 +238,14 @@ export declare class CryptoEngine {
      * @param document - The document to encrypt
      * @param classObj - The class defining which fields to encrypt
      */
-    encryptDocument(document: Document, classObj: Class): Promise<void>;
+    /**
+     * @param scopeId - The document's resolved scope label. When present, the
+     * scope's read-write CEK seals every attribute (stamped with its `kid`,
+     * bound to the label via AAD); the caller has already refused the write if
+     * the scope is not open. Absent, the legacy document key path applies
+     * unchanged.
+     */
+    encryptDocument(document: Document, classObj: Class, scopeId?: string): Promise<void>;
     /**
      * Decrypts encrypted fields in a document after retrieval.
      * Modifies the document in place.

package/lib/core/crypto-engine/utils.d.ts

@@ -44,8 +44,16 @@ export declare const isEncryptedPayload: (value: unknown) => value is EncryptedP
  * ```
  */
 export declare const deriveKeyId: (hexKey: string) => Promise<string>;
-export declare const encryptWithAesGcm: (plaintext: string, key: CryptoKey, kid?: string) => Promise<EncryptedPayload>;
-export declare const decryptWithAesGcm: (payload: EncryptedPayload, key: CryptoKey) => Promise<string>;
+/**
+ * The additional-authenticated-data string binding a scope-sealed payload to
+ * its label (spec 02 §2.3 rule 3): decryption derives it from the DOCUMENT's
+ * `~scope` at read time, so a tampered or stripped label does not merely look
+ * inconsistent - the GCM authentication fails and the payload stays sealed.
+ * Legacy-key payloads pass no AAD, keeping pre-scope ciphertext readable.
+ */
+export declare const scopeAad: (scopeId: string, kid: string) => string;
+export declare const encryptWithAesGcm: (plaintext: string, key: CryptoKey, kid?: string, aad?: string) => Promise<EncryptedPayload>;
+export declare const decryptWithAesGcm: (payload: EncryptedPayload, key: CryptoKey, aad?: string) => Promise<string>;
 export declare const wrapDocumentKey: (documentKey: string, derivedKeyHex: string) => Promise<string>;
 export declare const unwrapDocumentKey: (wrappedDocumentKey: string, cryptoKey: CryptoKey, derivedKeyHex: string) => Promise<string>;
 /**

package/lib/core/index.d.ts

@@ -304,7 +304,7 @@ 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, 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 { 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";
@@ -312,7 +312,9 @@ export type { ContentExport, ContentExportOptions, ContentImportOptions, Content
 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 { StackLockedError, StackScopeMismatchError } 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/stack.d.ts

@@ -1,14 +1,14 @@
 import Class from "./class.js";
 import Domain from "./domain.js";
 import { Stack, StackOptions, AuthSessionProof, ClientCredentials, CachedClass, ClassModelPropagationStart, ClassModelPropagationComplete, CachedDomain, DomainModel, ChangesSubscription } from "@docstack/shared";
-import { SystemDoc, Patch, ClassModel, Document, RelationDocument } from "@docstack/shared";
+import { SystemDoc, Patch, ClassModel, Document, RelationDocument, AccessScopeModel } from "@docstack/shared";
 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"];
@@ -162,12 +162,25 @@ declare class ClientStack extends Stack {
      * Engine for enforcing read/write access control policies.
      * Policies are evaluated based on user session and document content.
      */
-    policyEngine: PolicyEngine;
+    /**
+     * The access-scope registry: every `~AccessScope` document, grouped by
+     * `scopeId` (ADR-0045). Built from the database, independent of which CEKs
+     * the keyring actually holds - the registry knows a scope's key ids even
+     * when the session cannot open them, which is what the label↔kid mismatch
+     * guard needs (spec 02 §2.3 rule 2).
+     */
+    private accessScopeRegistry;
+    private accessScopeRegistryDirty;
     /**
      * Engine for field-level encryption and decryption.
      * 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.
@@ -319,6 +332,56 @@ declare class ClientStack extends Stack {
      * ```
      */
     unlock(documentKey: string): Promise<this>;
+    /**
+     * The access-scope registry, loaded from `~AccessScope` documents and
+     * refreshed whenever one is written (ADR-0045). Raw read: scope docs are
+     * the machinery that DECIDES readability - they cannot sit behind it.
+     */
+    private getAccessScopeRegistry;
+    /**
+     * The scope a document's write seals under: its own `~scope` label, else
+     * its class's `defaultScope` (spec 02 §2.2 - the document's value wins).
+     */
+    resolveScopeLabel(doc: unknown, classModel?: {
+        defaultScope?: string;
+    } | null): string | undefined;
+    /** Every key id belonging to a scope, across rotation versions - or null for an unknown scope. */
+    getAccessScopeKids(scopeId: string): Promise<Set<string> | null>;
+    /** Whether a declared scope's CEK is absent from the keyring - its content is sealed. */
+    isScopeLocked(scopeId: string): boolean;
+    /** Declared scopes whose CEK the keyring lacks. Loaded scopes only - call after open. */
+    lockedScopeIds(): Promise<string[]>;
+    /**
+     * Attempts every declared access scope with the session's attribute key
+     * (ADR-0045): the ABE decryption either yields a scope's CEK - verified
+     * against the scope's canary, then admitted to the keyring - or fails,
+     * and the scope stays locked. There is no gate to ask; this IS the access
+     * decision. Idempotent: a later call with better material unlocks more.
+     * Deferred patches that were waiting on a scope replay after.
+     */
+    unlockScopes(attributeKey: string): Promise<{
+        unlocked: string[];
+        locked: string[];
+    }>;
+    /**
+     * AUTHORITY-side helper: assembles a complete `~AccessScope` document from
+     * a fresh (or supplied) CEK - ABE-sealing it under the policy, stamping the
+     * kid, minting the per-scope canary. Runs wherever the application controls
+     * (its server, an admin ceremony, tests); it needs the authority PUBLIC key
+     * only, never the master secret. The document is returned, not written -
+     * publishing it (and distributing attribute keys) is the consumer's act.
+     */
+    static buildAccessScope(input: {
+        scopeId: string;
+        policyString: string;
+        /** The authority public key (`@docstack/abe` setup().pk). */
+        pk: string;
+        /** 32-byte CEK as hex; minted when absent. */
+        cekHex?: string;
+        version?: number;
+    }): Promise<AccessScopeModel & {
+        _id: string;
+    }>;
     /**
      * Encrypts bootstrap documents that were seeded before this stack had a key.
      *
@@ -481,7 +544,6 @@ declare class ClientStack extends Stack {
      * ```
      */
     importContent: (payload: ContentExport, options?: ContentImportOptions) => Promise<ContentImportReport>;
-    private ensureDefaultPolicyForClass;
     /**
      * Creates and initializes a new ClientStack instance.
      * This is the primary way to instantiate a stack - the constructor is private.
@@ -521,7 +583,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,8 +651,20 @@ 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.
      */
+    /**
+     * The deferral barrier, generalized per scope (spec 02 §5): a patch is
+     * blocked when the legacy half applies (stack locked and the patch needs
+     * the document key) OR any document it carries writes into a declared
+     * scope whose CEK the keyring lacks - sealing under the wrong key is never
+     * a fallback, so the patch waits for `unlockScopes` exactly as key-needing
+     * patches wait for `unlock`.
+     */
+    private patchBlockedByLock;
     private patchNeedsDocumentKey;
     /**
      * Authenticates a user and establishes a session.
@@ -598,6 +729,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>;
@@ -711,10 +870,13 @@ declare class ClientStack extends Stack {
     /**
      * Whether a database-level `limit` returns the same rows as limiting in memory.
      *
-     * `findDocuments` filters per document *after* the query - policy checks drop
-     * unreadable documents, and a locked crypto engine drops documents whose visible
-     * fields are all encrypted. A limit applied before either would under-fill. The
-     * query engine asks this before pushing a SQL LIMIT into the fetch.
+     * `findDocuments` drops a document whose visible fields are all sealed - a
+     * locked legacy key, or a scope the keyring cannot open. A limit applied
+     * before that filter would under-fill. So pushdown is allowed exactly when
+     * no row of this class can drop: the class has no encrypted attributes, or
+     * every key that might seal one is held (the legacy key, and every declared
+     * scope - a document may carry any label). The query engine asks this
+     * before pushing a SQL LIMIT into the fetch.
      *
      * @param className - The class being queried.
      */
@@ -801,6 +963,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 +1083,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 +1356,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);
+}