@camstack/system 1.2.390 → 1.2.392

package/dist/builtins/sqlite-storage/sqlite-settings.addon.d.ts

@@ -1,62 +1,63 @@
-import { ProviderRegistration, BaseAddon } from '@camstack/types';
-import { SqliteSettingsBackend } from './sqlite-settings-backend.js';
-import { SqliteVecVectorIndex } from './vector-index-vec.js';
+import type { ProviderRegistration } from "@camstack/types";
+import { BaseAddon } from "@camstack/types";
+import { SqliteSettingsBackend } from "./sqlite-settings-backend.js";
+import { SqliteVecVectorIndex } from "./vector-index-vec.js";
 /**
- * SQLite Settings addon — the relational ENGINE behind the data door.
- *
- * Capability: `data-store-provider` (collection, internal). It does not
- * serve `settings-store`: that is the public door, owned by
- * storage-orchestrator, which dispatches here
- * ([D44](../../../../../docs/decisions/adr-0044.md)). Callers reach this
- * engine only through the door — which is the point, because it is what
- * makes the engine replaceable.
- *
- * It also serves `database-snapshot` (singleton, internal): the verified copy
- * of its database that the nightly backup archives in place of the live files
- * (D693).
- *
- * It ALSO serves `vector-store` (singleton, internal), from the same database
- * file and the same open handle. That capability first shipped as its own addon
- * and the separation cost two round trips per write — caller → door → engine —
- * plus a runner process, to reach a database this addon already has open. The
- * capability is what keeps the backend swappable; the package never was.
- */
+* SQLite Settings addon — the relational ENGINE behind the data door.
+*
+* Capability: `data-store-provider` (collection, internal). It does not
+* serve `settings-store`: that is the public door, owned by
+* storage-orchestrator, which dispatches here
+* ([D44](../../../../../docs/decisions/adr-0044.md)). Callers reach this
+* engine only through the door — which is the point, because it is what
+* makes the engine replaceable.
+*
+* It also serves `database-snapshot` (singleton, internal): the verified copy
+* of its database that the nightly backup archives in place of the live files
+* (D693).
+*
+* It ALSO serves `vector-store` (singleton, internal), from the same database
+* file and the same open handle. That capability first shipped as its own addon
+* and the separation cost two round trips per write — caller → door → engine —
+* plus a runner process, to reach a database this addon already has open. The
+* capability is what keeps the backend swappable; the package never was.
+*/
 export declare class SqliteSettingsAddon extends BaseAddon {
-    private backend;
-    private vectorIndex;
-    private walMaintenance;
-    private walCheckpointer;
-    private shmLockCanary;
-    constructor();
-    /**
-     * The engine behind `settings-store` cannot read that door during
-     * `initialize()`. `BaseAddon` always `await`s `resolveConfig()` first;
-     * on an isolated sqlite that round-trip is a UDS call to the parent,
-     * and the parent is waiting for THIS child's post-init handshake before
-     * it builds the door (D233). Live 1.2.152: 30 s hang, timeout, every
-     * in-process builtin skipped, then this addon finished one second later.
-     * Constructor defaults (`{}`) are the whole config this addon has.
-     */
-    protected resolveConfig(): Promise<void>;
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    protected onShutdown(): Promise<void>;
-    getBackend(): SqliteSettingsBackend | null;
-    /**
-     * Build the vector index.
-     *
-     * ONE implementation, deliberately. A second backend behind a flag means two
-     * code paths that can disagree, two sets of gotchas, and a silent fallback
-     * that turns "the extension is missing" into "search is mysteriously slow" —
-     * the failure this codebase keeps paying for. The capability is the swap
-     * point: another provider replaces this one wholesale, it does not hide
-     * inside it.
-     *
-     * So a failed extension load THROWS. A node without the native binary must
-     * fail at boot with a message naming sqlite-vec, not serve degraded results
-     * nobody knows are degraded.
-     */
-    private createVectorIndex;
-    /** Exposed for tests; null before `onInitialize`. */
-    getVectorIndex(): SqliteVecVectorIndex | null;
+	private backend;
+	private vectorIndex;
+	private walMaintenance;
+	private walCheckpointer;
+	private shmLockCanary;
+	constructor();
+	/**
+	* The engine behind `settings-store` cannot read that door during
+	* `initialize()`. `BaseAddon` always `await`s `resolveConfig()` first;
+	* on an isolated sqlite that round-trip is a UDS call to the parent,
+	* and the parent is waiting for THIS child's post-init handshake before
+	* it builds the door (D233). Live 1.2.152: 30 s hang, timeout, every
+	* in-process builtin skipped, then this addon finished one second later.
+	* Constructor defaults (`{}`) are the whole config this addon has.
+	*/
+	protected override resolveConfig(): Promise<void>;
+	protected onInitialize(): Promise<ProviderRegistration[]>;
+	protected onShutdown(): Promise<void>;
+	getBackend(): SqliteSettingsBackend | null;
+	/**
+	* Build the vector index.
+	*
+	* ONE implementation, deliberately. A second backend behind a flag means two
+	* code paths that can disagree, two sets of gotchas, and a silent fallback
+	* that turns "the extension is missing" into "search is mysteriously slow" —
+	* the failure this codebase keeps paying for. The capability is the swap
+	* point: another provider replaces this one wholesale, it does not hide
+	* inside it.
+	*
+	* So a failed extension load THROWS. A node without the native binary must
+	* fail at boot with a message naming sqlite-vec, not serve degraded results
+	* nobody knows are degraded.
+	*/
+	private createVectorIndex;
+	/** Exposed for tests; null before `onInitialize`. */
+	getVectorIndex(): SqliteVecVectorIndex | null;
 }
 export default SqliteSettingsAddon;

package/dist/builtins/sqlite-storage/sqlite-snapshot-protocol.d.ts

@@ -1,49 +1,54 @@
-import { DatabaseSnapshotTable } from '@camstack/types';
+/**
+* The messages between `SqliteSnapshotter` (the runner's main thread) and the
+* snapshot worker thread (D693). Pure: no driver, no kernel — the worker bundle
+* imports it, and so does the main thread.
+*/
+import type { DatabaseSnapshotTable } from "@camstack/types";
 /** `workerData` of one snapshot thread. The `kind` tells it apart from any other worker. */
 export interface SnapshotWorkerData {
-    readonly kind: 'sqlite-snapshot';
-    /** The live database — opened read-only, through this thread's own connection. */
-    readonly livePath: string;
-    /** Where the copy is written. Lives in a work directory nothing else uses. */
-    readonly copyPath: string;
-    /** Pages per backup step. Every step reads the same pinned transaction. */
-    readonly pagesPerStep: number;
+	readonly kind: "sqlite-snapshot";
+	/** The live database — opened read-only, through this thread's own connection. */
+	readonly livePath: string;
+	/** Where the copy is written. Lives in a work directory nothing else uses. */
+	readonly copyPath: string;
+	/** Pages per backup step. Every step reads the same pinned transaction. */
+	readonly pagesPerStep: number;
 }
 /** What a copy that passed every check holds. */
 export interface VerifiedCopy {
-    readonly takenAt: number;
-    readonly tables: readonly DatabaseSnapshotTable[];
-    readonly pageCount: number;
-    readonly pageSize: number;
-    readonly copyMs: number;
-    readonly verifyMs: number;
+	readonly takenAt: number;
+	readonly tables: readonly DatabaseSnapshotTable[];
+	readonly pageCount: number;
+	readonly pageSize: number;
+	readonly copyMs: number;
+	readonly verifyMs: number;
 }
 /**
- * Why a copy was refused:
- * - `integrity` — `PRAGMA integrity_check` on the copy answered anything but `ok`;
- * - `row-count` — a table of the copy holds a different number of rows than the
- *   pinned source did, or the table sets differ;
- * - `failed` — the copy could not be taken at all (open, I/O, busy, deadline);
- * - `no-space` — the live database's disk cannot take the copy and keep its
- *   reserve, or its free space could not be measured (decided before the
- *   thread starts, by the snapshotter).
- */
-export type SnapshotRefusalReason = 'integrity' | 'row-count' | 'failed' | 'no-space';
+* Why a copy was refused:
+* - `integrity` — `PRAGMA integrity_check` on the copy answered anything but `ok`;
+* - `row-count` — a table of the copy holds a different number of rows than the
+*   pinned source did, or the table sets differ;
+* - `failed` — the copy could not be taken at all (open, I/O, busy, deadline);
+* - `no-space` — the live database's disk cannot take the copy and keep its
+*   reserve, or its free space could not be measured (decided before the
+*   thread starts, by the snapshotter).
+*/
+export type SnapshotRefusalReason = "integrity" | "row-count" | "failed" | "no-space";
 export interface SnapshotDone {
-    readonly kind: 'done';
-    readonly copy: VerifiedCopy;
+	readonly kind: "done";
+	readonly copy: VerifiedCopy;
 }
 export interface SnapshotRefused {
-    readonly kind: 'refused';
-    readonly reason: SnapshotRefusalReason;
-    readonly detail: string;
+	readonly kind: "refused";
+	readonly reason: SnapshotRefusalReason;
+	readonly detail: string;
 }
 export type SnapshotWorkerMessage = SnapshotDone | SnapshotRefused;
 /** Thrown inside the worker by a check that refuses the copy. */
 export declare class SnapshotRefusedError extends Error {
-    readonly reason: SnapshotRefusalReason;
-    readonly detail: string;
-    constructor(reason: SnapshotRefusalReason, detail: string);
+	readonly reason: SnapshotRefusalReason;
+	readonly detail: string;
+	constructor(reason: SnapshotRefusalReason, detail: string);
 }
 export declare function isSnapshotWorkerData(value: unknown): value is SnapshotWorkerData;
 export declare function isSnapshotWorkerMessage(value: unknown): value is SnapshotWorkerMessage;

package/dist/builtins/sqlite-storage/sqlite-snapshot-worker.d.ts

@@ -1,33 +1,33 @@
-import { DatabaseSnapshotTable } from '@camstack/types';
-import { default as Database } from 'better-sqlite3';
-import { SnapshotWorkerData, VerifiedCopy } from './sqlite-snapshot-protocol.js';
+import type { DatabaseSnapshotTable } from "@camstack/types";
+import Database from "better-sqlite3";
+import { type SnapshotWorkerData, type VerifiedCopy } from "./sqlite-snapshot-protocol.js";
 /** The pinned half: when it was taken, what it holds, how long it took. */
 export interface PinnedCopy {
-    readonly takenAt: number;
-    readonly tables: readonly DatabaseSnapshotTable[];
-    readonly copyMs: number;
+	readonly takenAt: number;
+	readonly tables: readonly DatabaseSnapshotTable[];
+	readonly copyMs: number;
 }
 /** The checked half. */
 export interface CopyCheck {
-    readonly pageCount: number;
-    readonly pageSize: number;
-    readonly verifyMs: number;
+	readonly pageCount: number;
+	readonly pageSize: number;
+	readonly verifyMs: number;
 }
 /**
- * Copy `source` into `copyPath` from ONE read transaction. `onStep` observes
- * each backup step (a spec interleaves writes there).
- */
+* Copy `source` into `copyPath` from ONE read transaction. `onStep` observes
+* each backup step (a spec interleaves writes there).
+*/
 export declare function copyPinned(source: Database.Database, copyPath: string, pagesPerStep: number, onStep?: () => void): Promise<PinnedCopy>;
 /**
- * The answer of `PRAGMA journal_mode = DELETE` must be `delete`. SQLite answers
- * the mode it is IN, so a switch it could not make comes back as `wal` with no
- * error — and a copy left in WAL needs sidecars that will not travel with it.
- */
+* The answer of `PRAGMA journal_mode = DELETE` must be `delete`. SQLite answers
+* the mode it is IN, so a switch it could not make comes back as `wal` with no
+* error — and a copy left in WAL needs sidecars that will not travel with it.
+*/
 export declare function requireRollbackJournal(answer: unknown): void;
 /**
- * Check a copy against what the pinned source held. Makes the copy one
- * self-contained file first. Throws {@link SnapshotRefusedError}.
- */
+* Check a copy against what the pinned source held. Makes the copy one
+* self-contained file first. Throws {@link SnapshotRefusedError}.
+*/
 export declare function verifyCopy(copyPath: string, expected: readonly DatabaseSnapshotTable[]): CopyCheck;
 /** The whole job: open the live database read-only, copy it pinned, check the copy. */
 export declare function takeVerifiedCopy(data: SnapshotWorkerData): Promise<VerifiedCopy>;

package/dist/builtins/sqlite-storage/sqlite-snapshotter.d.ts

@@ -1,98 +1,98 @@
-import { DatabaseSnapshotResult, IScopedLogger } from '@camstack/types';
-import { SnapshotWorkerData } from './sqlite-snapshot-protocol.js';
+import { type DatabaseSnapshotResult, type IScopedLogger } from "@camstack/types";
+import { type SnapshotWorkerData } from "./sqlite-snapshot-protocol.js";
 /**
- * Pages per backup step. Every step reads the same pinned transaction, so the
- * size only trades yields against per-step overhead: 1024 pages is 4 MiB at the
- * default page size.
- */
+* Pages per backup step. Every step reads the same pinned transaction, so the
+* size only trades yields against per-step overhead: 1024 pages is 4 MiB at the
+* default page size.
+*/
 export declare const SNAPSHOT_PAGES_PER_STEP = 1024;
 /**
- * How long the snapshot thread may run before it is terminated. A minute under
- * the capability's own timeout, so the runner gives up — and says why — before
- * the caller's call does.
- */
+* How long the snapshot thread may run before it is terminated. A minute under
+* the capability's own timeout, so the runner gives up — and says why — before
+* the caller's call does.
+*/
 export declare const SNAPSHOT_DEADLINE_MS: number;
 /** The least headroom left on the disk AFTER the copy, whatever the database's size. */
 export declare const SNAPSHOT_MIN_RESERVE_BYTES: number;
 /**
- * Free bytes a snapshot needs before it may start: the copy (at most the
- * database plus its WAL), then a reserve the size of the database (at least
- * {@link SNAPSHOT_MIN_RESERVE_BYTES}) for the live writes and the WAL growth
- * the pinned read causes while the copy runs.
- */
+* Free bytes a snapshot needs before it may start: the copy (at most the
+* database plus its WAL), then a reserve the size of the database (at least
+* {@link SNAPSHOT_MIN_RESERVE_BYTES}) for the live writes and the WAL growth
+* the pinned read causes while the copy runs.
+*/
 export declare function snapshotSpaceNeeded(databaseBytes: number, walBytes: number): number;
 /** The `statfs` fields the space check reads. */
 export interface DiskSpace {
-    readonly bavail: number | bigint;
-    readonly bsize: number | bigint;
+	readonly bavail: number | bigint;
+	readonly bsize: number | bigint;
 }
 export type StatfsFn = (dir: string) => Promise<DiskSpace>;
 /**
- * Where the built worker entry lives: `dist/sqlite-snapshot-worker.js` at the
- * package root, next to `wal-checkpoint-worker.js` (see `wal-checkpointer.ts`
- * for why it resolves through the package's own `package.json`).
- */
+* Where the built worker entry lives: `dist/sqlite-snapshot-worker.js` at the
+* package root, next to `wal-checkpoint-worker.js` (see `wal-checkpointer.ts`
+* for why it resolves through the package's own `package.json`).
+*/
 export declare function defaultSnapshotWorkerPath(): string;
 /**
- * The members of a snapshot thread this class uses. Structural, so a spec can
- * hand in a thread whose `terminate()` never settles — the stall a native call
- * that never returns would cause.
- */
+* The members of a snapshot thread this class uses. Structural, so a spec can
+* hand in a thread whose `terminate()` never settles — the stall a native call
+* that never returns would cause.
+*/
 export interface SnapshotWorkerHandle {
-    onMessage(listener: (message: unknown) => void): void;
-    onError(listener: (err: Error) => void): void;
-    onExit(listener: (code: number) => void): void;
-    terminate(): Promise<unknown>;
+	onMessage(listener: (message: unknown) => void): void;
+	onError(listener: (err: Error) => void): void;
+	onExit(listener: (code: number) => void): void;
+	terminate(): Promise<unknown>;
 }
 export type SnapshotWorkerFactory = (data: SnapshotWorkerData) => SnapshotWorkerHandle;
 export interface SqliteSnapshotterOptions {
-    /** The live database this process owns. */
-    readonly livePath: string;
-    readonly logger: IScopedLogger;
-    readonly pagesPerStep?: number;
-    /** Overrides the built entry — a spec points this at the TypeScript source. */
-    readonly workerPath?: string;
-    /** Extra `execArgv` for the thread — a spec passes a loader here. */
-    readonly workerExecArgv?: readonly string[];
-    /** Overrides {@link SNAPSHOT_DEADLINE_MS}. */
-    readonly deadlineMs?: number;
-    /** Overrides `fs.statfs` — a spec answers the space question here. */
-    readonly statfs?: StatfsFn;
-    /** Overrides the thread itself — a spec hands in one that never terminates. */
-    readonly spawnWorker?: SnapshotWorkerFactory;
-    /** Overrides the directory fsync — a spec makes it fail. */
-    readonly syncDirectory?: (dir: string) => Promise<void>;
+	/** The live database this process owns. */
+	readonly livePath: string;
+	readonly logger: IScopedLogger;
+	readonly pagesPerStep?: number;
+	/** Overrides the built entry — a spec points this at the TypeScript source. */
+	readonly workerPath?: string;
+	/** Extra `execArgv` for the thread — a spec passes a loader here. */
+	readonly workerExecArgv?: readonly string[];
+	/** Overrides {@link SNAPSHOT_DEADLINE_MS}. */
+	readonly deadlineMs?: number;
+	/** Overrides `fs.statfs` — a spec answers the space question here. */
+	readonly statfs?: StatfsFn;
+	/** Overrides the thread itself — a spec hands in one that never terminates. */
+	readonly spawnWorker?: SnapshotWorkerFactory;
+	/** Overrides the directory fsync — a spec makes it fail. */
+	readonly syncDirectory?: (dir: string) => Promise<void>;
 }
 export declare class SqliteSnapshotter {
-    private readonly livePath;
-    private readonly logger;
-    private readonly pagesPerStep;
-    private readonly deadlineMs;
-    private readonly statfs;
-    private readonly spawnWorker;
-    private readonly syncDirectory;
-    private inFlight;
-    /**
-     * Set while a thread the deadline gave up on is still being terminated. A
-     * native SQLite call cannot be interrupted, so `terminate()` may take as long
-     * as that call — or never settle. Until it does, a new snapshot is refused
-     * at once (never joined, never started beside a thread that may still hold
-     * a pinned read), and the work directory stays until nobody writes into it.
-     */
-    private draining;
-    constructor(options: SqliteSnapshotterOptions);
-    /** The database this snapshotter copies, absolute. */
-    get database(): string;
-    /** Write `<db>.backup-snapshot`. Joins a snapshot already running. */
-    write(): Promise<DatabaseSnapshotResult>;
-    /**
-     * Remove a snapshot nobody collected and a work directory a crash left.
-     * Called at boot; {@link write} does the same before it starts.
-     */
-    sweep(): Promise<void>;
-    private refuse;
-    /** Refuses with `no-space` unless the disk can take the copy and keep its reserve. */
-    private checkSpace;
-    private run;
-    private runWorker;
+	private readonly livePath;
+	private readonly logger;
+	private readonly pagesPerStep;
+	private readonly deadlineMs;
+	private readonly statfs;
+	private readonly spawnWorker;
+	private readonly syncDirectory;
+	private inFlight;
+	/**
+	* Set while a thread the deadline gave up on is still being terminated. A
+	* native SQLite call cannot be interrupted, so `terminate()` may take as long
+	* as that call — or never settle. Until it does, a new snapshot is refused
+	* at once (never joined, never started beside a thread that may still hold
+	* a pinned read), and the work directory stays until nobody writes into it.
+	*/
+	private draining;
+	constructor(options: SqliteSnapshotterOptions);
+	/** The database this snapshotter copies, absolute. */
+	get database(): string;
+	/** Write `<db>.backup-snapshot`. Joins a snapshot already running. */
+	write(): Promise<DatabaseSnapshotResult>;
+	/**
+	* Remove a snapshot nobody collected and a work directory a crash left.
+	* Called at boot; {@link write} does the same before it starts.
+	*/
+	sweep(): Promise<void>;
+	private refuse;
+	/** Refuses with `no-space` unless the disk can take the copy and keep its reserve. */
+	private checkSpace;
+	private run;
+	private runWorker;
 }

package/dist/builtins/sqlite-storage/statement-shape.d.ts

@@ -1,64 +1,64 @@
 /**
- * A stable, low-cardinality name for the SHAPE of a SQL statement.
- *
- * ## Why the profiler needs this
- *
- * `SqliteOpProfiler` aggregated on `(op, collection)`, and that pair is not an
- * identity — it is a table. On 2026-08-25 the busiest line of a 90 s operator
- * stall read `query pipeline-analytics:tracks — 1005 calls, 2694 ms,
- * max 1615 ms, 17981 rows`, and there was no way to tell from it WHICH of the
- * eleven distinct reads that addon issues against that one table had spent the
- * second and a half. Every one of them was equally accused; the aggregate could
- * not clear a single one.
- *
- * The shape is the missing half. It is derived from the statement the engine
- * actually prepared, so it cannot drift from the code the way a hand-passed
- * label would, and it collapses to exactly one string per call site — which is
- * what makes it safe as part of an aggregate key.
- *
- * ## What is thrown away, and why
- *
- * - **The projection.** `queryDeclared` always selects every column, so the
- *   `SELECT` list is the table's schema restated — pure noise, and the single
- *   longest part of the statement.
- * - **The table name.** It is already the `collection` field of the report.
- * - **The width of an `IN` list.** `IN (?, ?, … ×500)` and `IN (?)` are the
- *   same call site; keeping the literal placeholders would make every page of
- *   a chunked read its own aggregate row. The COUNT is kept (`IN (?×500)`)
- *   because it is the difference between "reads one row" and "reads five
- *   hundred", which is the whole question being asked.
- *
- * Bound values are never included. They are not needed to name a call site, and
- * a statement's parameters routinely carry device ids, keys and user data — a
- * profiler line is not a place to put them.
- */
+* A stable, low-cardinality name for the SHAPE of a SQL statement.
+*
+* ## Why the profiler needs this
+*
+* `SqliteOpProfiler` aggregated on `(op, collection)`, and that pair is not an
+* identity — it is a table. On 2026-08-25 the busiest line of a 90 s operator
+* stall read `query pipeline-analytics:tracks — 1005 calls, 2694 ms,
+* max 1615 ms, 17981 rows`, and there was no way to tell from it WHICH of the
+* eleven distinct reads that addon issues against that one table had spent the
+* second and a half. Every one of them was equally accused; the aggregate could
+* not clear a single one.
+*
+* The shape is the missing half. It is derived from the statement the engine
+* actually prepared, so it cannot drift from the code the way a hand-passed
+* label would, and it collapses to exactly one string per call site — which is
+* what makes it safe as part of an aggregate key.
+*
+* ## What is thrown away, and why
+*
+* - **The projection.** `queryDeclared` always selects every column, so the
+*   `SELECT` list is the table's schema restated — pure noise, and the single
+*   longest part of the statement.
+* - **The table name.** It is already the `collection` field of the report.
+* - **The width of an `IN` list.** `IN (?, ?, … ×500)` and `IN (?)` are the
+*   same call site; keeping the literal placeholders would make every page of
+*   a chunked read its own aggregate row. The COUNT is kept (`IN (?×500)`)
+*   because it is the difference between "reads one row" and "reads five
+*   hundred", which is the whole question being asked.
+*
+* Bound values are never included. They are not needed to name a call site, and
+* a statement's parameters routinely carry device ids, keys and user data — a
+* profiler line is not a place to put them.
+*/
 /**
- * Longest fingerprint kept, in characters.
- *
- * A shape is a log field printed five to a line; past this it stops being
- * readable and starts pushing the numbers off the end. Every real statement in
- * this engine fits well inside it — the cap exists for the pathological
- * `whereIn` with forty distinct fields, not for the normal case.
- */
+* Longest fingerprint kept, in characters.
+*
+* A shape is a log field printed five to a line; past this it stops being
+* readable and starts pushing the numbers off the end. Every real statement in
+* this engine fits well inside it — the cap exists for the pathological
+* `whereIn` with forty distinct fields, not for the normal case.
+*/
 export declare const SQL_SHAPE_MAX_LENGTH = 220;
 /** Appended when a shape is cut at {@link SQL_SHAPE_MAX_LENGTH}. */
-export declare const SQL_SHAPE_ELLIPSIS = "\u2026";
+export declare const SQL_SHAPE_ELLIPSIS = "…";
 /**
- * How many distinct raw statements the memo holds before it is dropped.
- *
- * The engine prepares its SQL fresh on every call, so without a memo this runs
- * a handful of regexes per statement at a few hundred statements a second.
- * With one, it runs them once per call site. The bound exists because the raw
- * key is unbounded in principle (an `IN` list of a new width mints a new
- * entry): at the cap the memo is cleared rather than grown, which costs one
- * re-derivation per shape and cannot leak.
- */
+* How many distinct raw statements the memo holds before it is dropped.
+*
+* The engine prepares its SQL fresh on every call, so without a memo this runs
+* a handful of regexes per statement at a few hundred statements a second.
+* With one, it runs them once per call site. The bound exists because the raw
+* key is unbounded in principle (an `IN` list of a new width mints a new
+* entry): at the cap the memo is cleared rather than grown, which costs one
+* re-derivation per shape and cannot leak.
+*/
 export declare const SQL_SHAPE_MEMO_MAX_ENTRIES = 512;
 /**
- * Name the shape of `sql`, whose table is `collection`.
- *
- * Memoised on the raw statement — see {@link SQL_SHAPE_MEMO_MAX_ENTRIES}.
- */
+* Name the shape of `sql`, whose table is `collection`.
+*
+* Memoised on the raw statement — see {@link SQL_SHAPE_MEMO_MAX_ENTRIES}.
+*/
 export declare function sqlShape(sql: string, collection: string): string;
 /** Test seam: forget every memoised shape. */
 export declare function resetSqlShapeMemo(): void;