@jarenjs/db 0.34.0

package/dist/types/jobs.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @file The durable job queue (JOBS-FORMAT): enqueue, the
+ * single-statement guarded claim (§3 — one statement is one
+ * transaction, so no double-claim without any distributed lock),
+ * retry with exponential backoff and jitter (§4), recovery as
+ * re-claim of expired leases (§5), polling workers with same-process
+ * wake-on-enqueue (§6), and the per-job flow checkpoint store the DAG
+ * composition binds (§7) — completion marks the job done and records
+ * the result in ONE guarded transaction.
+ *
+ * Every worker transition is guarded by `state='leased' AND
+ * lease_owner=?`: execution is at-least-once, completion is
+ * exactly-once. `now` and `random` are injectable — the runtime
+ * defaults are the clock and `Math.random`; every test injects.
+ *
+ * The worker LIFECYCLE holds two invariants that a long-running process
+ * depends on, and neither is a detail:
+ *
+ *  - **No handler value can break the loop.** A handler is host code and
+ *    may resolve with something JSON cannot express, or reject with a
+ *    value whose own `message` throws when read. Both are normalized
+ *    totally, and `runOne` is isolated inside the loop, so the worst a
+ *    single job can do is fail its own attempt. A rejected claim-execute
+ *    loop would stop draining the queue silently.
+ *  - **Shutdown is bounded.** Handlers receive an `AbortSignal` and
+ *    `stop()` takes a deadline, so a handler that never settles cannot
+ *    hold `stop()` — and therefore `store.close()`, and therefore the
+ *    database file — open forever.
+ */
+export declare const JOBS_TABLE = "_jaren_jobs";
+export declare const JOB_CHECKPOINTS_TABLE = "_jaren_job_checkpoints";
+/** §4 defaults, all overridable per worker. */
+export declare const JOB_DEFAULTS: Readonly<{
+    maxAttempts: 5;
+    leaseMs: 30000;
+    pollInterval: 500;
+    backoffBase: 1000;
+    backoffCap: 60000;
+    /** How long `stop()` waits for in-flight handlers after signalling
+     * abort, before it stops waiting and reports what is still running.
+     * Bounded on purpose: an unbounded wait makes one stuck handler
+     * indistinguishable from a hung process. */
+    stopGraceMs: 5000;
+}>;
+/**
+ * A diagnostic string for ANY value, including ones that fight back — a
+ * getter that throws, a null-prototype object, a revoked proxy, a
+ * symbol. Total by construction: an error report is never the thing that
+ * fails.
+ * @param {any} value
+ * @returns {string}
+ */
+export declare function describeValue(value: any): string;
+/**
+ * JSON text for a job result, or `null` when the value cannot be
+ * expressed — a BigInt, a cycle, a `toJSON` that throws. The caller
+ * treats that as a failed attempt, never as a broken worker.
+ * @param {any} value
+ * @returns {{ text: string | null } | { reason: string }}
+ */
+export declare function serializeResult(value: any): {
+    text: string | null;
+} | {
+    reason: string;
+};
+/**
+ * The queue engine over one open connection.
+ * @param {{ connection: any, now?: () => number,
+ *   random?: () => number,
+ *   defaults?: Partial<typeof JOB_DEFAULTS> }} options
+ */
+export declare function createJobEngine(options: {
+    connection: any;
+    now?: () => number;
+    random?: () => number;
+    defaults?: Partial<typeof JOB_DEFAULTS>;
+}): {
+    ready: any;
+    enqueue: (kind: any, payload: any, enqueueOptions: any) => any;
+    get: (id: any) => any;
+    counts: () => any;
+    claim: (claimOptions: {
+        kinds: string[];
+        owner: string;
+        leaseMs?: number;
+    }) => any;
+    complete: (id: any, owner: any, result: any) => any;
+    fail: (id: any, owner: any, error: any, workerDefaults: any) => any;
+    checkpointsFor: (job: {
+        id: string;
+        leaseOwner: string | null;
+    }) => {
+        load: (runId: any) => any;
+        save: (runId: any, nodeId: any, value: any) => any;
+        complete: (runId: any, result: any) => any;
+    };
+    createWorker: (workerOptions: {
+        handlers: Record<string, Function>;
+        concurrency?: number;
+        pollInterval?: number;
+        leaseMs?: number;
+        owner?: string;
+        backoffBase?: number;
+        backoffCap?: number;
+    }) => {
+        stats: () => {
+            claims: number;
+            completions: number;
+            failures: number;
+            polls: number;
+            wakes: number;
+            inFlight: number;
+        };
+        start(): /*elided*/ any;
+        /**
+         * Stop claiming, signal in-flight handlers to abort, and wait for
+         * the loops — but only up to `graceMs`. A handler that ignores its
+         * signal cannot hold the process open; the resolved record says so
+         * instead, and the lease expiry (§5) lets another worker re-claim.
+         * @param {{ graceMs?: number }} [stopOptions]
+         * @returns {Promise<{ drained: boolean, inFlight: number }>}
+         */
+        stop(stopOptions?: {
+            graceMs?: number;
+        }): Promise<{
+            drained: boolean;
+            inFlight: number;
+        }>;
+    };
+    /** Stop every worker, bounded. Resolves to the per-worker outcome so
+     * `close()` can report a handler it could not wait out rather than
+     * hanging on it. */
+    stopAll: (stopOptions: any) => Promise<any[]>;
+};

package/dist/types/live.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @file Live queries (LIVE-FORMAT §§7–12): a registered query document
+ * whose result is maintained as capture records arrive, emitting
+ * RFC 6902 patches against its own `{ rows }` result document.
+ *
+ * The CLASSIFIER implements §7's normative table and nothing more —
+ * it unwraps the one-element array pack and literal `$subsequence`
+ * windows the same way the planner does, then reads the compiled
+ * plan: translated filters, order terms and aggregates are exactly
+ * the planner's, never a re-implementation. Everything outside the
+ * table re-runs on invalidation with the reason named (`live.mode`).
+ *
+ * Maintenance is synchronous inside capture delivery (§8): inserts
+ * carry their document in the patch, updates point-read the touched
+ * row, deletes are answered from maintained state. Per-row semantics
+ * reuse the ENGINE via packed one-row compilation (the residual
+ * discipline) — a live row evaluates exactly as the query would.
+ */
+/** The store-level live bounds and their defaults (§12: printed,
+ * never silent). */
+export declare const LIVE_DEFAULTS: Readonly<{
+    maxQueries: 64;
+    maxMaintained: 10000;
+}>;
+/**
+ * Classify a collection query document against §7's table. Pure —
+ * given the document and the collection's planner shape, returns the
+ * strategy description, or a re-run description with the reason.
+ * @param {any} document
+ * @param {any} queryShape - the planner shape (collection, schema,
+ *   columnByCanonical)
+ * @param {boolean} keyed - whether documents carry their key (a
+ *   declared key pointer); unkeyed rows cannot be tracked by key
+ * @returns {any}
+ */
+export declare function classifyLiveQuery(document: any, queryShape: any, keyed: boolean): any;
+/**
+ * Diff two row arrays into sequential add/remove/replace ops under
+ * `/rows`, relying on REFERENCE identity for unchanged rows (the §9
+ * sharing contract makes identity the equality that matters). A
+ * working copy is replayed op by op, so the emitted patch transforms
+ * the old array into the new one BY CONSTRUCTION; a remove re-filled
+ * at the same index merges into a replace.
+ * @param {any[]} oldRows
+ * @param {any[]} newRows
+ * @returns {any[]} ops
+ */
+export declare function diffRows(oldRows: any[], newRows: any[]): any[];
+/**
+ * The store-level live-query registry: registration against the §12
+ * bounds, capture-record delivery in commit order, lifecycle.
+ * @param {{ maxQueries: number, maxMaintained: number }} bounds
+ */
+export declare function createLiveRegistry(bounds: {
+    maxQueries: number;
+    maxMaintained: number;
+}): {
+    register: (definition: any) => any;
+    count: () => number;
+    deliver(record: any): void;
+    closeAll(): void;
+};

package/dist/types/migrate.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @file Document migrations (D12): two model documents diff into a
+ * migration document whose steps are rendered DDL, JSLT data
+ * transforms and query assertions; the migration replays on a shadow
+ * database first; a history table records what ran with a
+ * signature-grade checksum. This is the phase-A payoff for storing
+ * documents rather than rows: a shape change is a transformation of
+ * VALUES, not a table rebuild.
+ *
+ * Identity is a hash, not a version number: `from`/`to` are
+ * `hashContent(canonicalizeJson(model))` — the identity of a SHAPE,
+ * which nobody has to remember to bump. The checksum discipline is
+ * D12's: `canonicalizeJson` + `hashContent` (signature-grade — throws
+ * on the unserializable), never the memo-grade `contentKey`.
+ *
+ * Like the query emitter, this module is part of the emitter layer:
+ * the structural SQL it composes (the history table's statements, the
+ * batched row walk) is built from dialect primitives, and every
+ * planner-produced statement is rendered by the dialect into the
+ * migration DOCUMENT — shown before it is ever executed.
+ */
+/** The migration format version. */
+export declare const MIGRATION_VERSION = "0.1";
+/** The history table name (outside the model's identifier namespace
+ * conventions on purpose — a collection cannot collide with it). */
+export declare const HISTORY_TABLE = "_jaren_migrations";
+/**
+ * The signature-grade identity of a model SHAPE.
+ * @param {any} model - A jaren-model document
+ * @returns {string}
+ */
+export declare function shapeHash(model: any): string;
+/**
+ * The signature-grade checksum of a migration document.
+ * @param {any} migration
+ * @returns {string}
+ */
+export declare function migrationChecksum(migration: any): string;
+/**
+ * Plan a migration between two model documents. The planner diffs the
+ * PHYSICAL plans (columns, indexes) and renders DDL through the
+ * dialect; a changed schema gets a DRAFT identity transform that
+ * refuses to run until the author fills it in — the planner cannot
+ * infer a data transform and does not pretend to. Renames are declared
+ * (`x-rename` on the target collection), never guessed.
+ * @param {any} fromModel
+ * @param {any} toModel
+ * @param {{ id?: string, dialect?: any }} [options]
+ * @returns {{ migration: any, report: {
+ *   renamed: { from: string, to: string }[],
+ *   added: string[], removed: string[],
+ *   schemaChanged: string[], drafts: string[],
+ *   destructive: boolean } }}
+ */
+export declare function planMigration(fromModel: any, toModel: any, options?: {
+    id?: string;
+    dialect?: any;
+}): {
+    migration: any;
+    report: {
+        renamed: {
+            from: string;
+            to: string;
+        }[];
+        added: string[];
+        removed: string[];
+        schemaChanged: string[];
+        drafts: string[];
+        destructive: boolean;
+    };
+};
+/** `planMigration` handles the whole model — collections AND entities
+ * — since the relational order; this name says so. */
+export declare const planModelMigration: typeof planMigration;
+/**
+ * Create a model's WHOLE physical shape on a connection: collections,
+ * entity tables and join tables, exactly as `openStore` would. Used
+ * by the shadow baseline, the fresh reference database that shape
+ * equality compares against, and the tests.
+ * @param {any} connection
+ * @param {any} model
+ * @returns {any} value-or-promise
+ */
+export declare function createModelShape(connection: any, model: any): any;
+/**
+ * The declared schema of a database, normalized for comparison: every
+ * object carrying SQL text (tables, indexes), whitespace-collapsed,
+ * history table excluded, sorted. Shape equality after a migration —
+ * this dump versus a fresh {@link createModelShape} — is the
+ * acceptance criterion for every rebuild.
+ * @param {any} connection
+ * @returns {any} value-or-promise of `{ type, name, owner, sql }[]`
+ */
+export declare function schemaShapeOf(connection: any): any;
+/**
+ * Compare a migrated database's schema against the shape a fresh
+ * `createModelShape(model)` produces, via a throwaway reference
+ * database. Returns `null` when equal, or a one-line difference.
+ * @param {any} driver
+ * @param {any} connection - the migrated database
+ * @param {any} model - the target model
+ * @param {((connection: any) => any) | undefined} registerFunctions
+ * @returns {any} value-or-promise of `string | null`
+ */
+export declare function compareShapeToModel(driver: any, connection: any, model: any, registerFunctions: ((connection: any) => any) | undefined): any;
+/**
+ * Report a database's migration state without touching it: what is
+ * applied, what is pending, whether an applied migration was edited,
+ * and — once the chain is fully applied — whether the physical shape
+ * DRIFTED from the model (someone changed the database by hand, §12).
+ * @param {{ driver: any, path?: string }} target
+ * @param {any[]} migrations - the full ordered list
+ * @param {{ baseline: any, model?: any,
+ *   registerFunctions?: (connection: any) => any }} options
+ * @returns {Promise<{ applied: string[], pending: string[],
+ *   drift: string | null, upToDate: boolean }>}
+ */
+export declare function migrationStatus(target: {
+    driver: any;
+    path?: string;
+}, migrations: any[], options: {
+    baseline: any;
+    model?: any;
+    registerFunctions?: (connection: any) => any;
+}): Promise<{
+    applied: string[];
+    pending: string[];
+    drift: string | null;
+    upToDate: boolean;
+}>;
+/**
+ * Apply pending migrations to a database.
+ *
+ * The contract: `migrations` is the FULL ordered list (applied and
+ * pending — the migrations directory); `baseline` is the model the
+ * store was first created with (the chain's anchor and the shadow's
+ * starting shape); `model` is the target model the code now carries.
+ * Each pending migration runs in ONE exclusive transaction with a
+ * savepoint per step; a failing step rolls the whole migration back.
+ * The whole chain replays on a `:memory:` shadow before the real
+ * store is touched.
+ *
+ * @param {{ driver: any, path?: string, busyTimeout?: number }} target
+ * @param {any[]} migrations
+ * @param {{ baseline: any, model?: any, compileSchema?: Function,
+ *   dryRun?: boolean, batchSize?: number, onProgress?: Function,
+ *   shadow?: boolean, shadowPath?: string }} options
+ * @returns {Promise<any>}
+ */
+export declare function migrate(target: {
+    driver: any;
+    path?: string;
+    busyTimeout?: number;
+}, migrations: any[], options: {
+    baseline: any;
+    model?: any;
+    compileSchema?: Function;
+    dryRun?: boolean;
+    batchSize?: number;
+    onProgress?: Function;
+    shadow?: boolean;
+    shadowPath?: string;
+}): Promise<any>;

package/dist/types/model.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file The entity model walk: `x-entity` normalization with a CLOSED
+ * vocabulary, relation resolution with inverse agreement, and
+ * `explainMapping` — the derived physical shape as plain data, so the
+ * hybrid mapping rule is golden-testable rather than folklore.
+ *
+ * THE DESCENT DECISION (recorded here because TODO's D22 demands it
+ * be explicit): six copies of the `properties`/`prefixItems`/`items`/
+ * `allOf` descent spine exist in this repository, and this walk was
+ * the candidate seventh. It is NOT one. The entity walk is
+ * deliberately ONE level deep — it enumerates the TOP-LEVEL
+ * properties of an entity schema, resolves `$ref` and shallow-merges
+ * `allOf` at each property through the resolvers
+ * `@jarenjs/validate/normalize` exports for exactly this purpose, and
+ * never recurses further, because the mapping rule sends every nested
+ * shape to the JSONB document wholesale. A consumer with no recursion
+ * has no descent spine to share, so the shared-enumerator question
+ * (three different termination strategies across the six copies)
+ * stays open for the first consumer that actually recurses. No
+ * seventh copy was added.
+ */
+/**
+ * Normalize the `entities` member of a model document.
+ * @param {any} model
+ * @returns {Map<string, any>} entity name -> normalized entity
+ */
+export declare function normalizeEntities(model: any): Map<string, any>;
+/**
+ * The hybrid mapping, derived mechanically from §9.3's table and
+ * returned as DATA: per entity, the columns (name, type, source),
+ * the checks, the foreign keys, the indexes, and which properties
+ * live in the JSONB document.
+ * @param {any} model - a model document with `entities`
+ * @returns {any}
+ */
+export declare function explainMapping(model: any): any;

package/dist/types/patch-sql.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file RFC 6902 → dialect JSON-set primitives, so a one-field update
+ * does not rewrite a large document. The translation is decided
+ * AGAINST THE LIVE DOCUMENT: an RFC 6901 pointer cannot say whether
+ * `/a/0` names an array position or an object member called `"0"`, so
+ * each segment is discriminated by walking the document the patch was
+ * validated against, and the walked state is advanced op by op so a
+ * later operation sees what the earlier ones produced.
+ *
+ * Translatable in 0.1: `replace` anywhere, `add` of an object member,
+ * `add` at an array's end (`/-` or the index equal to its length), and
+ * `remove`. Everything else — `test`, `move`, `copy`, a mid-array
+ * insert (the shift has no single JSON-function spelling) — returns
+ * `null` and the store falls back to a whole-document write. The
+ * fallback is counted and exposed by the store, measured rather than
+ * assumed.
+ */
+export type JsonPathSegment = import('./dialect.js').JsonPathSegment;
+/**
+ * Translate a whole patch into a dialect expression builder, or `null`
+ * when any operation needs the whole-document fallback. The caller has
+ * already applied the patch in memory (the copy-on-write engine
+ * validates the RESULT); this translation only decides how the same
+ * outcome reaches the database.
+ * @param {any[]} ops - RFC 6902 operations, already known applicable
+ * @param {any} doc - The stored document the patch applies to
+ * @param {any} dialect
+ * @returns {{ build: (docColumnSql: string,
+ *   parameterIndexBase: number) => { expression: string,
+ *   params: string[] } } | null}
+ */
+export declare function translatePatch(ops: any[], doc: any, dialect: any): {
+    build: (docColumnSql: string, parameterIndexBase: number) => {
+        expression: string;
+        params: string[];
+    };
+} | null;

package/dist/types/plan.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @file AST → Plan. The planner walks the engine's PUBLISHED normalized
+ * AST (never the raw document), dispatches EXHAUSTIVELY on node kind —
+ * an unrecognised kind is an internal error naming the kind and the
+ * `AST_VERSION`, never a silent residual — and promotes constructs to
+ * native form strictly residual-by-default: everything starts as a
+ * residual and earns native status only where the equivalence proof
+ * exists (the truth table in ARCHITECTURE.md, pinned by the
+ * differential tests).
+ *
+ * The outcome of planning one document:
+ *
+ *   { plan, mode: 'native' | 'row' | 'set', reasons, rowReturn }
+ *
+ * - `native` — everything translated; the plan alone answers.
+ * - `row`    — predicates, ordering and window pushed; only the
+ *   projection runs in the engine, per fetched row (streams).
+ * - `set`    — the pushed conjuncts narrow candidates; the WHOLE
+ *   compiled document runs over the materialized candidates.
+ *
+ * `reasons` names every construct that forced work off the database,
+ * with reason text drawn from the deliberate-residual table.
+ */
+/**
+ * Assert a node kind is one this planner has decided. Called on every
+ * dispatch; the throw names the kind and the AST version so a language
+ * change breaks the build instead of becoming an accidental residual.
+ * Exported so the throw itself is pinned by a test.
+ * @param {any} node
+ */
+export declare function assertDecidedKind(node: any): void;
+/**
+ * Plan a whole document against one collection. The store's registered
+ * operators (Ring 2) ride in `shape.operators` — the planner recognises
+ * them as vocabulary but keeps them in the residual, and names them in
+ * the reasons when it does.
+ * @param {any} document - The raw query document (kept beside the AST
+ *   for residual construction — the AST has no unparser)
+ * @param {any} shape - { collection, schema, columnByCanonical, operators? }
+ * @param {{ udf?: (fragment: any) => { name: string, key: string } | null }} [options]
+ * @returns {{
+ *   analysis: any,
+ *   plan: import('./algebra.js').Plan | null,
+ *   mode: 'native' | 'row' | 'set',
+ *   reasons: { construct: string, reason: string }[],
+ *   rowReturn: any,
+ *   udfs: string[],
+ * }}
+ */
+export declare function planQuery(document: any, shape: any, options?: {
+    udf?: (fragment: any) => {
+        name: string;
+        key: string;
+    } | null;
+}): {
+    analysis: any;
+    plan: import('./algebra.js').Plan | null;
+    mode: 'native' | 'row' | 'set';
+    reasons: {
+        construct: string;
+        reason: string;
+    }[];
+    rowReturn: any;
+    udfs: string[];
+};
+/**
+ * Build the planner shape for one entity: canonical top-level paths
+ * map to REAL columns (flavor `entity-column`), epoch date columns to
+ * their derived integer twins (flavor `entity-epoch`), and everything
+ * else stays a document path over the entity's JSONB column (the
+ * phase-A guarded forms).
+ * @param {any} entity - normalized entity (model.js)
+ * @param {any} entityMapping - explainMapping(...).entities[name]
+ * @returns {any}
+ */
+export declare function entityShape(entity: any, entityMapping: any): any;
+/**
+ * Resolve a singular member path on an entity binding to a flavored
+ * PlanRef.
+ * @param {any} node - a path AST node
+ * @param {number} slot
+ * @param {any} shape - from {@link entityShape}
+ * @returns {any | null}
+ */
+export declare function entityPathRef(node: any, slot: number, shape: any): any | null;
+/**
+ * Plan one predicate over an entity binding: the same operator
+ * grammar as phase A, with entity-flavored refs. Reuses
+ * {@link planPredicate} for the recognition, then re-resolves refs
+ * through the flavor table.
+ * @param {any} node
+ * @param {number} slot
+ * @param {any} shape
+ * @returns {{ pred: any } | { refusal: { construct: string, reason: string } }}
+ */
+export declare function planEntityPredicate(node: any, slot: number, shape: any): {
+    pred: any;
+} | {
+    refusal: {
+        construct: string;
+        reason: string;
+    };
+};
+/**
+ * Plan an ENTITY query document (one planner, two document kinds). The
+ * store's registered operators (Ring 2) are recognised as vocabulary and
+ * kept in the set residual over the fetched root, named in the reasons.
+ * @param {any} document
+ * @param {Map<string, any>} entities - normalized entities
+ * @param {any} mapping - explainMapping result
+ * @param {{ functions?: any, extensions?: any } | null} [operators]
+ * @returns {any}
+ */
+export declare function planEntityQuery(document: any, entities: Map<string, any>, mapping: any, operators?: {
+    functions?: any;
+    extensions?: any;
+} | null): any;
+/** The entity names a document's root paths reference (`$.Name[*]`). */
+export declare function collectEntityRoots(document: any, entities: any): Set<any>;

package/dist/types/profile.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file The safe execution profile (D15): a query document that arrives
+ * from a tenant, a remote client or a language model can reach a
+ * database, and injection being structurally impossible (parameter
+ * binding) says nothing about resource exhaustion or cross-tenant
+ * reads. A profile composes four INDEPENDENT bounds:
+ *
+ *  1. engine limits — `{sequenceItems, resultItems, steps, depth}`
+ *     wired into every residual compilation, so the JavaScript
+ *     portion of a query is bounded by the engine's own enforcement;
+ *  2. the mandatory row bound — every non-aggregate fetch carries a
+ *     LIMIT of `maxRows + 1`, and fetching more than `maxRows` rows is
+ *     the coded `JD2007`, never a silent truncation (D14);
+ *  3. reference containment — undeclared externals, host functions,
+ *     collations or collections are the compile error `JD0011`; no UDF
+ *     registration happens under a profile; optionally, a plan whose
+ *     database narrative shows a full-table SCAN is refused;
+ *  4. mandatory predicates — a per-collection predicate conjoined into
+ *     EVERY plan at its root, after translation, so no document shape
+ *     can produce a fetch without it.
+ *
+ * The non-claims are part of the contract and live in
+ * MODEL-FORMAT.md §8: no statement timeout exists on the SQLite
+ * drivers (the capability slot is empty), so a long-running native
+ * aggregate is bounded by nothing here; the row bound covers fetched
+ * rows, not database-internal work.
+ */
+/** The `'safe'` profile: the documented defaults. */
+export declare const SAFE_PROFILE: Readonly<{
+    limits: Readonly<{
+        sequenceItems: 100000;
+        resultItems: 10000;
+        steps: 1000000;
+        depth: 32;
+    }>;
+    maxRows: 1000;
+    externals: readonly never[];
+    functions: readonly never[];
+    collations: readonly never[];
+    collections: null;
+    predicates: Readonly<{}>;
+    refuseFullScan: false;
+}>;
+/**
+ * Normalize a profile option: the string `'safe'` is the default
+ * table; an object overrides individual members over those defaults
+ * (limits merge member-wise). The result is plain JSON — cacheable by
+ * content key — and frozen.
+ * @param {any} profile - `'safe'` or a partial profile object
+ * @returns {any}
+ */
+export declare function normalizeProfile(profile: any): any;
+/**
+ * Translate a profile's mandatory predicate for one collection into a
+ * plan predicate. The predicate is HOST-authored configuration, so a
+ * predicate that does not translate natively is a host programming
+ * error (TypeError), not a coded document failure — there is no
+ * residual to hide it in: the whole point is that it binds the
+ * database-side fetch.
+ * @param {any} expression - A query expression over `$it`
+ * @param {any} shape - The collection's plan shape
+ * @returns {import('./algebra.js').PlanPredicate}
+ */
+export declare function translateProfilePredicate(expression: any, shape: any): import('./algebra.js').PlanPredicate;
+/**
+ * Conjoin a mandatory predicate into a plan's root filter.
+ * @param {import('./algebra.js').Plan} plan
+ * @param {import('./algebra.js').PlanPredicate | null} predicate
+ * @returns {import('./algebra.js').Plan}
+ */
+export declare function applyMandatoryPredicate(plan: import('./algebra.js').Plan, predicate: import('./algebra.js').PlanPredicate | null): import('./algebra.js').Plan;
+/**
+ * Cap a plan's window at the profile's detection bound
+ * (`maxRows + 1`): a result crossing `maxRows` is detected and
+ * refused, never silently truncated. Aggregates are exempt (one row).
+ * @param {import('./algebra.js').Plan} plan
+ * @param {number} maxRows
+ * @returns {import('./algebra.js').Plan}
+ */
+export declare function applyRowBound(plan: import('./algebra.js').Plan, maxRows: number): import('./algebra.js').Plan;