@docstack/client 0.1.5 → 0.1.8

package/lib/core/index.d.ts

@@ -3,8 +3,11 @@ 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';
+import type { DocStackSyncOptions } from './sync/index.js';
 /**
  * The main entry point for the DocStack client library.
  *
@@ -43,8 +46,120 @@ declare class DocStack extends EventTarget {
     private store;
     /** Array of all initialized ClientStack instances. */
     stacks: ClientStack[];
+    /**
+     * Stacks currently being opened, by name.
+     *
+     * `stacks` only gains an entry once `ClientStack.create` resolves, so it cannot answer
+     * "is this one already on its way?". Without that, {@link addStack}'s guard is a check
+     * followed by an `await` - not atomic - and two concurrent callers each open a handle
+     * on the same database. See ADR-0022.
+     */
+    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;
-    private addStack;
+    /**
+     * Splits a {@link StackConfig} into the connection string and the options a stack
+     * is created with.
+     *
+     * Everything the caller passed is forwarded - including `adapter` and any
+     * adapter-specific keys - so a stack can be opened on a transport other than the
+     * default one.
+     *
+     * @param config - A stack name, or a full configuration object.
+     * @returns The connection string and the resolved {@link StackOptions}.
+     */
+    private static resolveStackConfig;
+    /**
+     * Opens a stack and adds it to this instance.
+     *
+     * Public because an application's set of databases is not always known at startup:
+     * a workspace joined at runtime needs its own database, and its own replication
+     * pair, without tearing down the stacks already open. Adding a stack that is
+     * already open returns the existing instance rather than opening a second handle
+     * on the same database.
+     *
+     * Dispatches `stack-added` with the new stack in `detail`.
+     *
+     * @param config - A stack name, or a full configuration object.
+     * @returns The stack, initialized and ready.
+     *
+     * @example
+     * ```typescript
+     * const stack = await docstack.addStack({ name: `ws-${workspace.slug}`, patches });
+     * await stack.sync({ remote: () => driveFor(workspace) });
+     * ```
+     */
+    addStack: (config: StackConfig) => Promise<ClientStack>;
+    /**
+     * Closes a stack and drops it from this instance.
+     *
+     * Closing cancels the stack's replication and releases its listeners; the data on
+     * disk is left alone unless `destroy` is set, which is what leaving a workspace for
+     * good looks like.
+     *
+     * Dispatches `stack-removed` with the stack's name in `detail`.
+     *
+     * @param name - The stack name or connection string.
+     * @param options - `destroy: true` also deletes the underlying database.
+     * @returns `true` if a stack was removed, `false` if there was none by that name.
+     */
+    removeStack: (name: string, options?: {
+        destroy?: boolean;
+    }) => Promise<boolean>;
+    /**
+     * Starts replication for every open stack against one transport.
+     *
+     * The `remote` resolver is called once per stack, which is what makes a
+     * database-per-workspace application a single call rather than a loop the
+     * application has to keep in step with its own stack list.
+     *
+     * @param options - See {@link DocStackSyncOptions}. `stacks` narrows it to a subset.
+     * @returns A handle holding every stack's replication.
+     *
+     * @example
+     * ```typescript
+     * const sync = await docstack.sync({
+     *     remote: (stack) => new PouchDB(stack.name, { adapter: 'googledrive', accessToken }),
+     * });
+     * sync.addEventListener('status', () => render(sync.getStatus()));
+     * ```
+     */
+    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`.
+     */
+    getSyncHandle: () => DocStackSyncHandle | null;
+    /**
+     * Stops replication on every stack.
+     */
+    cancelSync: () => void;
     private initStacks;
     /**
      * Resets all initialized stacks.
@@ -184,5 +299,26 @@ declare class DocStack extends EventTarget {
  *
  * @module @docstack/client
  */
-export { ClientStack, Trigger, Class, Attribute, Domain, JobEngine };
+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";
+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";
+/**
+ * Key-identity helpers, for applications that re-key a database.
+ *
+ * `deriveKeyId` names a key the same way stored payloads do, so an application can tell
+ * which of its keys a field belongs to without holding any of them.
+ */
+export { deriveKeyId, isEncryptedPayload } from "./crypto-engine/index.js";
+export type { EncryptedPayload } from "./crypto-engine/index.js";
 export { DocStack };

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/policy-engine/index.d.ts

@@ -28,11 +28,35 @@ export type PolicyOperation = "read" | "write";
 export declare class PolicyEngine {
     /** Reference to the parent stack for database and session access. */
     private readonly stack;
+    /**
+     * Every `~Policy` document, loaded once and reused across evaluations.
+     *
+     * `isReadableDocument` runs once per document a read returns, and it used to re-fetch
+     * the policy list from the database each time - the dominant cost of every read path.
+     * The list is invalidated on any write that touches a `~Policy` document: the write
+     * path calls {@link invalidatePolicyCache} synchronously (see StackPlugin), and the
+     * stack's shared changes feed calls it again for out-of-band writes such as another
+     * tab's. `null` means not loaded.
+     */
+    private allPoliciesCache;
+    /**
+     * Compiled policy rules, keyed by their source text.
+     *
+     * A rule is evaluated once per policy per document, and `new Function` is a full
+     * compile each time. The source text is the key - not the policy id - so two policies
+     * sharing a rule share the compilation, and an edited rule is simply a new key.
+     */
+    private compiledRules;
     /**
      * Creates a new PolicyEngine instance.
      * @param stack - The parent ClientStack instance
      */
     constructor(stack: ClientStack);
+    /**
+     * Drops the cached policy list so the next evaluation re-reads it.
+     * Called by the write path and the changes feed whenever a `~Policy` document lands.
+     */
+    invalidatePolicyCache(): void;
     /**
      * Gets the current authentication session proof.
      * @returns The session proof, or undefined if not authenticated
@@ -61,6 +85,17 @@ export declare class PolicyEngine {
     private evaluateRule;
     private filterPoliciesForSession;
     private authorize;
+    /**
+     * Whether any policy applies to a class - i.e. whether reads of it are filtered.
+     *
+     * Lets the query engine know when a database-level LIMIT is safe: with no
+     * applicable policies, no row fetched within the limit can be dropped afterwards.
+     * Cheap once the policy list is cached.
+     *
+     * @param targetClass - The class name or id.
+     * @returns `true` if at least one policy targets the class.
+     */
+    hasPoliciesFor(targetClass: string): Promise<boolean>;
     /**
      * Ensures write access is allowed for a document of the given class.
      * Throws an error if no policy permits the write operation.

package/lib/core/query-engine/classes.d.ts

@@ -0,0 +1,24 @@
+import type { SelectAST, UnionAST } from "@docstack/shared";
+/**
+ * Collects the class names a parsed query reads.
+ *
+ * Deliberately generic: rather than enumerating the node types that can hold a nested
+ * query - `scalar_subquery`, `exists_expr`, the right-hand side of `IN` - it walks the
+ * whole graph and harvests every `select` node it finds. A new subquery form is then
+ * covered on the day it is added, rather than on the day someone notices a stale list.
+ *
+ * @param ast - The `ast` from {@link ClientStack.query}.
+ * @returns The class names read, or `null` when the query reads a source that is not a
+ * named class. That distinction is the contract: `[]` means *this query reads nothing* -
+ * `SELECT 1` - and it is safe to subscribe to nothing; `null` means *I cannot account for
+ * this*, and the caller should fail open rather than watch an incomplete set.
+ *
+ * @example
+ * ```typescript
+ * const { rows, ast } = await stack.query("SELECT * FROM Task JOIN Project ON …");
+ * collectQueryClasses(ast);         // ["Task", "Project"]
+ * collectQueryClasses([]);          // []   - reads nothing
+ * collectQueryClasses(null);        // null - unknown, fail open
+ * ```
+ */
+export declare const collectQueryClasses: (ast: (SelectAST | UnionAST)[] | null | undefined) => string[] | null;

package/lib/core/query-engine/executor.d.ts

@@ -12,3 +12,14 @@ import ClientStack from '../stack.js';
  * @throws {Error} If a table specified in the query is not found.
  */
 export declare function executePlan(stack: ClientStack, plan: any, params: any, outerRow?: any, outerAliases?: any): Promise<any>;
+/**
+ * Executes a plan as an async stream of rows.
+ *
+ * A single-table plan with no aggregation, DISTINCT, ORDER BY, or subqueries streams
+ * for real: rows ride `findDocumentsIterator`'s keyset pages, get the WHERE re-check
+ * and projection per row, and honor OFFSET/LIMIT by counting - peak memory is one
+ * batch regardless of result size, and a LIMIT stops the underlying scan early. Any
+ * other plan falls back to `executePlan` and yields from the materialized result, so
+ * the API is uniform even where streaming isn't.
+ */
+export declare function executePlanStream(stack: ClientStack, plan: any, params: any): AsyncGenerator<any, void, unknown>;

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

@@ -1,4 +1,5 @@
 export { parse } from "./parser.js";
 export type { SelectAST, UnionAST } from "@docstack/shared";
 export { createPlan } from "./planner.js";
-export { executePlan } from "./executor.js";
+export { executePlan, executePlanStream } from "./executor.js";
+export { collectQueryClasses } from "./classes.js";

package/lib/core/query-engine/planner.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Whether a column name is safe to hand to Mango - as a selector key, a sort field,
+ * or a projection field. See {@link PUSHABLE_COLUMN_RE} and {@link UNPUSHABLE_COLUMNS}.
+ */
+export declare function isPushableColumnName(name: any): boolean;
+/**
+ * Checks if a predicate is a simple binary expression that can be converted
+ * directly into a Mango selector by `buildSelector`.
+ *
+ * This is the single authority on pushability - `buildSelector` imports it and refuses
+ * predicates that fail it, so the planner and the executor cannot drift apart and a
+ * predicate classified as pushed can never be silently dropped.
+ *
+ * @param {object} predicate The predicate AST node.
+ * @returns {boolean} True if the predicate is simple enough for pushdown.
+ */
+export declare function isPushablePredicate(predicate: any): boolean;
 /**
  * Creates a logical query plan from a list of Abstract Syntax Trees (ASTs) for a UNION query.
  * @param {Array<object>} astList The list of ASTs generated by the parser.
@@ -18,10 +35,12 @@ export declare function createPlan(astList: any): {
     aggregation: any;
     orderBy: any;
     limit: any;
+    offset: any;
 } | {
     type: string;
     selectPlans: any[];
     unionOps: any[];
     orderBy: any;
     limit: any;
+    offset: any;
 };