@docstack/client 0.2.0 → 0.3.1

package/README.md

@@ -1,5 +1,5 @@
 [![npm](https://img.shields.io/npm/v/@docstack/client)](https://www.npmjs.com/package/@docstack/client)
-[![Docs](https://img.shields.io/badge/docs-onyx--og.github.io-blue)](https://onyx-og.github.io/docstack/)
+[![Docs](https://img.shields.io/badge/docs-onyx.ac-blue)](https://onyx.ac/products/docstack/docs)
 [![License](https://img.shields.io/badge/license-CC--BY--SA--4.0-lightgrey)](https://github.com/onyx-og/docstack/blob/main/LICENSE.md)
 [![Donate](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://www.paypal.com/donate/?hosted_button_id=4QSQ8L9AK2C74)
 
@@ -7,7 +7,7 @@
 
 **One does not simply stack documents.**
 
-An **offline-first embedded database for the browser**, built on PouchDB and IndexedDB. It brings the things you would otherwise build yourself — **schema validation, a SQL query engine, triggers, background jobs, role-based access policies, field-level encryption, versioned migrations and named write transactions** — into the client, where your application actually runs. When a connection exists, everything replicates to any PouchDB- or CouchDB-compatible remote, including the user's own Google Drive.
+An **offline-first embedded database for the browser**, built on PouchDB and IndexedDB. It brings the things you would otherwise build yourself — **schema validation, a SQL query engine, triggers, background jobs, cryptographic access scopes, field-level encryption, versioned migrations and named write transactions** — into the client, where your application actually runs. When a connection exists, everything replicates to any PouchDB- or CouchDB-compatible remote, including the user's own Google Drive.
 
 No server required. No network round trip on the read path. TypeScript throughout.
 
@@ -24,7 +24,7 @@ No server required. No network round trip on the read path. TypeScript throughou
 ### What it means for you building it
 
 * **Skip the backend for a whole class of app.** Validation, access control, migrations and background work usually justify a server. Here they are engine features, so a genuinely useful application can ship with no backend to run, secure, scale or pay for.
-* **Logic as data.** Triggers, jobs and policies are documents. Change a validation rule or a business process by writing a document — no redeploy, and the change replicates to every device like any other data.
+* **Logic as data.** Triggers, jobs, migrations and access scopes are documents. Change a validation rule or a business process by writing a document — no redeploy, and the change replicates to every device like any other data.
 * **Migrations you can trust.** Schema changes are declarative patch documents with a semver ledger: applied exactly once, all-or-nothing, and gated at sync so a device with an older model cannot pull documents its schema can't describe.
 * **Encryption you don't have to hand-roll.** Mark an attribute `encrypted` and it is ciphertext on disk and on the remote, transparently decrypted on read for the session that holds the key.
 * **SQL instead of map/reduce.** Joins, aggregation, subqueries and pagination against local documents, with index pushdown where the planner can prove it is safe.
@@ -35,7 +35,7 @@ No server required. No network round trip on the read path. TypeScript throughou
 npm install @docstack/client pouchdb-browser pouchdb-find
 ```
 
-`pouchdb-browser` and `pouchdb-find` are **peer dependencies** — DocStack does not bundle the storage layer, so you control its version.
+`pouchdb-browser` and `pouchdb-find` are **peer dependencies** — DocStack does not bundle the storage layer, so you control its version. `@docstack/abe`, the CP-ABE primitive behind access scopes, is installed as a dependency and loaded lazily, only when a stack declares scopes.
 
 ## ⚡ Quick start
 
@@ -95,7 +95,7 @@ const { rows: busy } = await stack.query(`
 `);
 ```
 
-`WHERE`, `ORDER BY … LIMIT` and range predicates push down into the index where the planner can prove the result is identical; encryption and policies are consulted first, because a filter applied to ciphertext would answer the wrong question.
+`WHERE`, `ORDER BY … LIMIT` and range predicates push down into the index where the planner can prove the result is identical; encryption is consulted first, because a filter applied to ciphertext would answer the wrong question.
 
 For results too large to materialise, stream them — the scan pages by keyset and stops early when a `LIMIT` is satisfied:
 
@@ -164,8 +164,8 @@ const handle = await stack.sync({
     classes: { exclude: ['Draft'] },         // what travels
 });
 
-handle.addEventListener('sync-status', () => {
-    const status = stack.getSyncStatus();
+handle.addEventListener('status', (event) => {
+    const status = event.detail;   // also `stack.getSyncStatus()`, or `sync-status` on the stack
     // `lastConvergedAt` is the honest "last synced": a cycle finished with nothing
     // left to send. `lastActiveAt` only says documents moved.
     render(status.state, status.lastConvergedAt);
@@ -210,7 +210,7 @@ try {
 }
 ```
 
-A write that fails validation, policy or the locked-stack check stages nothing, and a batch with one bad document unwinds entirely. Commit re-runs that sweep against the current world and refuses with `TransactionConflictError` if a document changed underneath — persisting nothing and leaving the transaction open to retry.
+A write that fails validation or the locked-stack check stages nothing, and a batch with one bad document unwinds entirely. Commit re-runs that sweep against the current world and refuses with `TransactionConflictError` if a document changed underneath — persisting nothing and leaving the transaction open to retry.
 
 **Atomicity is reported, not assumed.** Every commit report carries the storage adapter's honest answer in `adapter.atomicBatch`: adapters that commit a batch as one storage transaction report `true`; on IndexedDB, results are per-document, and a revision pre-flight shrinks — but does not eliminate — the window. A partial commit leaves `status: "partial"` with only the failed entries retained, so a raced document conflicts on retry instead of being silently overwritten.
 
@@ -236,6 +236,16 @@ console.log(post.slug); // 'hello-world'
 `JobEngine` executes a job when asked. `JobScheduler` decides when to ask, under the constraints a client actually imposes — an app that is closed most of the time, timers that freeze, and several devices holding replicas of the same job.
 
 ```typescript
+const content = `
+    async function execute(stack, params) {
+        const { rows } = await stack.query("SELECT _id FROM Task WHERE isComplete = true");
+        return { metadata: { archivedCount: rows.length } };
+    }
+`;
+// `hash` is mandatory: the SHA-256 of `content`, verified before every run.
+const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(content));
+const hash = Array.from(new Uint8Array(digest), b => b.toString(16).padStart(2, '0')).join('');
+
 await stack.db.bulkDocs([{
     _id: 'Job-ArchiveOldTasks',
     '~class': '~Job',
@@ -243,12 +253,8 @@ await stack.db.bulkDocs([{
     type: 'user',
     workerPlatform: 'client',
     isEnabled: true,
-    content: `
-        async function execute(stack, params) {
-            const { rows } = await stack.query("SELECT _id FROM Task WHERE isComplete = true");
-            return { metadata: { archivedCount: rows.length } };
-        }
-    `,
+    content,
+    hash,
 }]);
 
 // Run it now
@@ -264,29 +270,36 @@ stack.jobScheduler.start({
 
 There is deliberately no "run everything": job content replicates and is executable, so unattended execution is an allow-list. `pinnedHashes` lets the application pin the code it expects a job to have.
 
-### 7. Access policies
+### 7. Access scopes
 
-Rule-based read and write control, evaluated per session against the document in question.
+Access is a property of the ciphertext, not a rule that runs. Content belongs to a **scope** whose content key is sealed under an **attribute policy** (CP-ABE, the AC17 scheme, through [`@docstack/abe`](https://github.com/onyx-og/docstack/blob/main/packages/abe/README.md)). A device whose attribute key satisfies the policy opens the scope; one whose key does not holds the same ciphertext and reads `null`. There is no client-side check to bypass, so the guarantee holds against the device owner too.
 
 ```typescript
-await stack.db.bulkDocs([
-    {
-        _id: 'Policy-Article-EditorsWrite',
-        '~class': '~Policy',
-        targetClass: ['Class-Article'],
-        groupId: 'Group-Editors',
-        rule: `return session && session.sessionStatus === 'active';`,
-    },
-    {
-        _id: 'Policy-Article-PublicRead',
-        '~class': '~Policy',
-        targetClass: ['Class-Article'],
-        rule: `if (document.status === 'published') return true;`,
-    },
-]);
+// Authority side — your server, an admin ceremony. Master keys never reach a device.
+import { setup, keygen } from '@docstack/abe';
+
+const { pk, msk } = await setup();
+const hrScope = await ClientStack.buildAccessScope({
+    scopeId: 'hr',
+    policyString: '"role:hr" or "clearance:exec"',
+    pk,
+});
+const aliceKey = await keygen(msk, ['role:hr']);
+// Ship `hrScope` in an application patch; hand `aliceKey` to Alice's devices.
+
+// Device side.
+const stack = await ClientStack.create('my-app', {
+    documentKey,
+    accessKeys: { attributeKey: aliceKey },   // or later: await stack.unlockScopes(aliceKey)
+});
+
+await salaryClass.add({ who: 'alice', amount: '100000', '~scope': 'hr' });   // seals under hr's key
+stack.isScopeLocked('hr');   // false for Alice; true for a device whose key does not satisfy the policy
 ```
 
-Because policies are documents scoped by group and user, one database can serve multiple tenants without per-tenant application code — and the query engine consults them before deciding whether a filter can be pushed down.
+A document joins a scope with the reserved `~scope` field, or inherits its class's `defaultScope`. The scope decides *under which key* the class's `encrypted: true` attributes seal; the schema still decides *which* attributes. Writing into a scope the session cannot open throws `StackLockedError` with `scopeId` set, and a write whose label disagrees with its payload's key is refused with `StackScopeMismatchError` rather than re-sealed. Revoking a member is publishing a new scope version with a policy the departed key no longer satisfies.
+
+Conditional access is write-time labeling ("published means public" is the write choosing the scope), and behavioural rules stay application code. The formula language, the guarantees and the limits, stated plainly, are in the [access control](https://onyx.ac/products/docstack/docs/concepts/access-control/) section of the documentation.
 
 ### 8. Field-level encryption
 
@@ -294,7 +307,7 @@ Because policies are documents scoped by group and user, one database can serve
 await Attribute.create(userClass, 'socialSecurityNumber', 'string', 'SSN', { encrypted: true });
 ```
 
-The value is encrypted with a document key (PBKDF2-derived, AES-GCM) before it reaches storage. It is ciphertext on disk **and on every remote it replicates to** — decrypted only on the way out, for a session holding the key.
+The value is AES-GCM ciphertext before it reaches storage, under the stack's document key or, for a document labeled with a scope, that scope's key. It is ciphertext on disk **and on every remote it replicates to** — decrypted only on the way out, for a session holding the key.
 
 DocStack never invents that key: one generated per session could not outlive it, and a second device would generate a different one. Supply it at open time, or open **locked** and unlock later:
 
@@ -373,7 +386,7 @@ Against raw PouchDB — the honest baseline, since DocStack is built on it:
 | Querying | Mango selectors, hand-written map/reduce | ✅ SQL — joins, aggregation, subqueries, pushdown |
 | Business logic on write | application code | ✅ triggers, stored as data |
 | Background work | application code | ✅ job engine + unattended scheduler |
-| Access control | none | ✅ policy engine, per class and session |
+| Access control | none | ✅ cryptographic scopes: attribute policies enforced by decryption |
 | Field-level encryption | build it | ✅ transparent, opaque to the remote |
 | Schema migrations | build it | ✅ versioned patches with a ledger and a sync gate |
 | Multi-document atomicity | none | ✅ staged transactions, with reported guarantees |
@@ -382,7 +395,7 @@ Against raw PouchDB — the honest baseline, since DocStack is built on it:
 
 What distinguishes DocStack is a narrower bet than "a better local database":
 
-* **Logic as data.** Triggers, jobs and policies are documents that replicate and can change at runtime, rather than code compiled into a release. Behaviour ships like data.
+* **Logic as data.** Triggers, jobs, migrations and scopes are documents that replicate and can change at runtime, rather than code compiled into a release. Behaviour ships like data.
 * **Encryption the remote cannot read.** Field-level encryption is applied before storage and before replication, so the sync target is a place to keep bytes, not a party you trust.
 * **Bring your own remote.** Replication targets any PouchDB-compatible database — including a folder in the end user's own Drive, which makes "we don't hold your data" an architecture rather than a promise.
 
@@ -396,12 +409,12 @@ Pick accordingly: these are different bets, not rankings.
 | **Schema Engine** | Zod-backed validation, class hydration, schema propagation |
 | **Query Engine** | SQL parser, planner and executor |
 | **Job Engine** | Background jobs, runs, and the unattended scheduler |
-| **Crypto Engine** | PBKDF2 key derivation and AES-GCM field encryption |
-| **Policy Engine** | Read/write rules per class, group and session |
+| **Crypto Engine** | AES-GCM field encryption under a keyring: the document key, retired keys and admitted scope keys |
+| **Access scopes** | CP-ABE-sealed content keys (`@docstack/abe`), attribute-key admission, per-scope locks |
 | **Transaction Engine** | Staged writes, overlay reads, one-batch commit |
 | **Sync Layer** | Lifecycle, replication filters, convergence state, schema gate |
 
-Every one of these is pinned by the Playwright suite in [`src-test/`](https://github.com/onyx-og/docstack/tree/main/packages/client/src-test) — transactions and their overlay, crypto-aware queries, policy enforcement, subqueries, replication filters, late-joining stacks, patch chains.
+Every one of these is pinned by the Playwright suite in [`src-test/`](https://github.com/onyx-og/docstack/tree/main/packages/client/src-test) — transactions and their overlay, crypto-aware queries, access scopes, subqueries, replication filters, late-joining stacks, patch chains.
 
 ## 💾 Storage and sync transports
 
@@ -428,7 +441,7 @@ await docstack.sync({
 
 ## 📖 Documentation
 
-* [Full documentation](https://onyx-og.github.io/docstack/) — architecture, guides, API reference
+* [Full documentation](https://onyx.ac/products/docstack/docs) — architecture, guides, API reference
 * [Architecture decisions](https://github.com/onyx-og/docstack/tree/main/specs/adr) — why the engine is shaped this way
 * [Changelog](https://github.com/onyx-og/docstack/blob/main/packages/client/CHANGELOG.md)
 * [Contributing](https://github.com/onyx-og/docstack/blob/main/CONTRIBUTING.md)

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

@@ -312,7 +312,7 @@ 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";
 /**

package/lib/core/stack.d.ts

@@ -1,13 +1,12 @@
 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";
@@ -163,7 +162,15 @@ 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.
@@ -325,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.
      *
@@ -487,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.
@@ -600,6 +656,15 @@ declare class ClientStack extends Stack {
      * 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.
@@ -805,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.
      */

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

@@ -22,5 +22,4 @@ export declare const classFromStage: (stack: ClientStack, stage: TransactionStag
  */
 export declare const sweepEntry: (stack: ClientStack, stage: TransactionStage, entry: StagedEntry, options?: {
     allowClassModels?: boolean;
-    skipPolicy?: boolean;
 }) => Promise<void>;

package/lib/index.d.ts

@@ -18,7 +18,7 @@ export type { SchedulerOptions, SchedulerHost, JobScheduleState, TickReport, Ski
  * 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, 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 { 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, StackScopeMismatchError, 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";
 /**