@docstack/client 0.1.6 → 0.1.8

package/lib/core/guarded-db.d.ts

@@ -49,4 +49,5 @@ export declare const createGuardedDb: <T extends {}>(db: PouchDB.Database<T>) =>
 export declare const createReplicationDb: <T extends {}>(db: PouchDB.Database<T>, pristine: {
     bulkDocs: Function;
     bulkGet: Function;
+    get: Function;
 }) => PouchDB.Database<T>;

package/lib/core/index.d.ts

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

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

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

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

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

package/lib/core/stack.d.ts

@@ -6,6 +6,7 @@ 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 type { ContentExport, ContentExportOptions, ContentImportOptions, ContentImportReport } from "./content-transfer.js";
@@ -144,6 +145,19 @@ declare class ClientStack extends Stack {
      * ```
      */
     jobEngine: JobEngine;
+    /**
+     * Decides when approved jobs run, and dispatches them.
+     *
+     * Constructed with the stack but deliberately **not started by it**: `~Job.content`
+     * is JavaScript that replicates, so which jobs may run with nobody watching is the
+     * application's decision, named at {@link JobScheduler.start}.
+     *
+     * @example
+     * ```typescript
+     * stack.jobScheduler.start({ jobs: ['Job-review-campaign'] });
+     * ```
+     */
+    jobScheduler: JobScheduler;
     /**
      * Engine for enforcing read/write access control policies.
      * Policies are evaluated based on user session and document content.

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

@@ -296,6 +296,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 +324,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 +347,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/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,7 +18,7 @@ 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, 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";
 /**
@@ -15,7 +26,7 @@ export type { EncryptedPayload, ClassBuildOptions } from "./core/index.js";
  */
 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`.
  *