@jarenjs/db 0.46.5 → 0.56.0

package/dist/types/emit-model.d.ts

@@ -1,44 +0,0 @@
-/**
- * @file Entity types from models (D17): build an EMIT MODEL DOCUMENT
- * — the published contract from EMIT-FORMAT.md — that renders entity
- * interfaces, input variants and the typed-store metadata from the
- * same model document the runtime validates against.
- *
- * The seam (EMIT-FORMAT §4.1, recorded here as the order demanded):
- * the schema compiler is INJECTED (`options.compile` is
- * `compileEmitModel` from `@jarenjs/emit`), called with
- * `extensions: ['x-entity']` so the vocabulary rides the member nodes
- * verbatim; this module then post-processes the MODEL DOCUMENT —
- * replacing relation member types with references, flipping
- * optionality, adding declarations — and never renders a character of
- * TypeScript itself. Emit stays database-free, db stays
- * renderer-free, and the injection keeps `@jarenjs/emit` out of db's
- * dependency graph (the generator script wires the two).
- *
- * What the artifact says, deliberately:
- * - entity interfaces are CLOSED objects (excess-property checking is
- *   the point of generated types; the runtime validator stays
- *   authoritative for what a database accepts);
- * - relation members are optional references — present only when a
- *   graph load included them; `date-time`/`date` strings carry the
- *   `DateTime` brand so the linq date operators light up;
- * - the `<Name>Input` variant makes defaulted and generated members
- *   optional, drops to-one/to-many relation members (`create`/`add`
- *   refuse them), and types many-to-many members as key-or-document
- *   arrays (what `add()` accepts);
- * - `EntityMetaMap` carries doc/input/key/relations per entity — the
- *   generic typed-store surface (`@jarenjs/db/typed`) binds to it.
- */
-/**
- * Build the emit-model document for a model's entities.
- * @param {any} model - a jaren-model document with `entities`
- * @param {{ compile: (schema: any, options?: any) => any,
- *   source?: string, reserved?: string[] }} options - `compile` is
- *   `compileEmitModel` (injected; see the header)
- * @returns {any} an EMIT-FORMAT `0.1` model document
- */
-export declare function entityEmitModel(model: any, options: {
-    compile: (schema: any, options?: any) => any;
-    source?: string;
-    reserved?: string[];
-}): any;

package/dist/types/emit.d.ts

@@ -1,75 +0,0 @@
-/**
- * @file Plan → SQL through a dialect. This is the query layer's shared
- * emitter, the same division of labour as `createDialect`'s DDL/DML
- * builders: structural SQL composition lives here, every
- * dialect-varying spelling (identifiers, parameters, string literals,
- * JSON access, `json_type`, `typeof`, string-operator forms, NULLS
- * placement, EXPLAIN phrasing) comes from the dialect. Values are
- * NEVER interpolated into the text: every literal and every external
- * becomes an ordered parameter slot, which is what makes injection
- * structurally impossible.
- *
- * Every emitted predicate is TOTAL (two-valued) by construction — the
- * `json_type` guards from the truth table in ARCHITECTURE.md — so
- * `NOT`/`AND`/`OR` compose classically and SQL's three-valued NULL
- * logic never decides a row.
- */
-export type ParamSlot = {
-    external: string;
-} | {
-    literal: unknown;
-} | {
-    derived: {
-        kind: 'bboxAxis';
-        external: string;
-        axis: 'w' | 's' | 'e' | 'n';
-    };
-};
-/**
- * Emit one plan as SQL plus its ordered parameter slots.
- * @param {import('./algebra.js').Plan} plan
- * @param {any} dialect
- * @param {{ table: string, keyColumn: string, docColumn: string }} physical
- * @returns {{ sql: string, slots: ParamSlot[] }}
- */
-export declare function emitPlan(plan: import('./algebra.js').Plan, dialect: any, physical: {
-    table: string;
-    keyColumn: string;
-    docColumn: string;
-}): {
-    sql: string;
-    slots: ParamSlot[];
-};
-/**
- * The entity predicate emitters, shared by the entity plan emitter
- * and the graph-load builder: given an alias and its document column,
- * emit one predicate with the flavor-correct forms.
- * @param {any} dialect
- * @param {(slot: ParamSlot) => string} param
- * @returns {{ emitPred: (aliasSql: string, docSql: string, pred: any) => string }}
- */
-export declare function createEntityPredicateEmitters(dialect: any, param: (slot: ParamSlot) => string): {
-    emitPred: (aliasSql: string, docSql: string, pred: any) => string;
-};
-/**
- * Emit an entity plan (`entity-select` or `entity-join`) as SQL plus
- * ordered parameter slots. Entity-COLUMN refs compare real typed
- * columns with TOTAL forms and no `json_type` guard — a column-mapped
- * property has no present-`null` (§9.3), so presence IS `IS NOT
- * NULL`; entity-EPOCH refs compare the derived integer column against
- * a plan-time epoch translation; entity-DOC refs ride the phase-A
- * guarded truth table over the entity's JSONB column. Join emission
- * appends BOTH bindings' row identities in binding order, which is
- * exactly the engine's nested-loop order — determinism the oracle
- * depends on.
- * @param {any} plan - from `planEntityQuery`
- * @param {any} dialect
- * @param {(entity: string) => { table: string }} physicalOf
- * @returns {{ sql: string, slots: ParamSlot[] }}
- */
-export declare function emitEntityPlan(plan: any, dialect: any, physicalOf: (entity: string) => {
-    table: string;
-}): {
-    sql: string;
-    slots: ParamSlot[];
-};

package/dist/types/entity.d.ts

@@ -1,23 +0,0 @@
-/**
- * @file Entity sets: create / read by key / update / delete over the
- * hybrid mapping. The physical row is the mapped scalar columns, the
- * foreign-key columns, and one JSONB `doc` column for everything
- * else; a write SPLITS the completed document along the mapping and a
- * read MERGES it back. Defaults apply in JavaScript before validation
- * — the value the application sees and the value stored are the same
- * — and identity follows the declared strategy (caller, uuid, auto).
- *
- * Epoch date columns are DERIVED: the document keeps the RFC 3339
- * string, the column carries `getEpochOf…RFC3339(value)` so range
- * predicates are index-friendly; reads take the string from the
- * document and skip the derived column.
- */
-/**
- * The write/read machinery for one entity, prepared once.
- * @param {any} connection
- * @param {any} entity - the normalized entity (model.js)
- * @param {any} entityMapping - `explainMapping(...).entities[name]`
- * @param {((doc: any) => any) | null} validate
- * @returns {any}
- */
-export declare function entityCore(connection: any, entity: any, entityMapping: any, validate: ((doc: any) => any) | null): any;

package/dist/types/errors.d.ts

@@ -1,167 +0,0 @@
-/**
- * @file Error types for @jarenjs/db, built on `@jarenjs/core`'s coded
- * contract: every failure carries a stable `code` (JD0xxx compile-time,
- * JD2xxx runtime), a bare `reason`, a composed `message`, and — where a
- * position in the model document exists — a `docPath`. Runtime errors
- * additionally carry the `collection` and, where one exists, the `key`
- * as own properties. Database errors are wrapped, never leaked raw: the
- * reason keeps the original text, `cause` keeps the original error. The
- * normative table lives in docs/MODEL-FORMAT.md §7, proven in sync with
- * `DB_CODES` below by a test.
- */
-import { CodedError } from '@jarenjs/core/errors';
-/**
- * The runtime code table (the `CSV_CODES` shape): one entry per code
- * this package can raise, proven in sync with MODEL-FORMAT.md §7's
- * normative table by a test.
- */
-export declare const DB_CODES: Readonly<{
-    JD0001: "the SQLite library is below the supported floor";
-    JD0002: "the declared model disagrees with the existing database";
-    JD0003: "the driver binding is unavailable on this runtime";
-    JD0004: "a declared index cannot be mapped to a column";
-    JD0005: "the model document is invalid";
-    JD0010: "strict mode refused a residual";
-    JD0011: "the profile refused the document";
-    JD0012: "work waited too long for the open transaction to settle";
-    JD0030: "an unknown x-entity member was declared";
-    JD0031: "relation declarations contradict each other";
-    JD0032: "the include specification is invalid";
-    JD0040: "the save spans a relation cycle";
-    JD0050: "live queries require change capture";
-    JD0051: "the demanded live mode is unavailable";
-    JD0052: "the live-query bound was reached";
-    JD0020: "the migration's from-shape does not match the database";
-    JD0021: "the migration is missing a required data transform";
-    JD0022: "an applied migration disagrees with the history record";
-    JD0023: "a migration step failed";
-    JD2001: "insert found the key already present";
-    JD2002: "a usable key could not be resolved for the write";
-    JD2003: "the write failed schema validation";
-    JD2004: "an undeclared collection was requested";
-    JD2005: "a database operation failed";
-    JD2006: "patch found no document at the key";
-    JD2007: "the result exceeded the profile row bound";
-    JD2040: "the row changed under an optimistic update";
-    JD2050: "a changeset could not be decoded";
-    JD2051: "the change log is not enabled";
-    JD2060: "the maintained live state exceeded its bound";
-    JD2061: "another context owns the database";
-    JD2062: "the store closed with job handlers still in flight";
-}>;
-/**
- * A defect found while opening a store — in the model document, the
- * declared indexes, the driver binding, or the database's agreement
- * with the declaration. Codes:
- *
- *  - `JD0001` — the SQLite library reported a version below the
- *    supported floor; the reason names the version found
- *  - `JD0002` — a declared collection already exists in the database
- *    with a different shape; nothing was altered — changing shape is
- *    the migration story, a later capability
- *  - `JD0003` — the runtime builtin behind a driver could not be
- *    loaded here (Node cannot resolve `bun:`; Bun ships no
- *    `node:sqlite`), or an injected handle is missing
- *  - `JD0004` — a declared index cannot be mapped to a column: its
- *    path does not select exactly one member (wildcards, slices,
- *    filters and descendants are not indexable), or its `derive`
- *    declaration is not one the storage vocabulary carries; the reason
- *    names the expression or the member and `docPath` points at it
- *  - `JD0005` — the model document is invalid; `docPath` points at
- *    the offending member
- *  - `JD0010` — `strict: true` and part of the query would have run
- *    outside the database; the reason names the forcing construct
- *  - `JD0011` — the active profile refused the document before any
- *    execution: an undeclared external, host function, collation or
- *    collection, or a refused full-table scan; the reason names it
- *  - `JD0030` — an unknown member inside an `x-entity` block; a
- *    silently ignored mapping directive is a data-loss bug waiting
- *  - `JD0031` — two relation declarations whose inverses contradict
- *    (different `via`, impossible `many` pairings)
- *  - `JD0032` — a graph-load include specification is invalid: an
- *    unknown relation, a cycle, an untranslatable filter, or the
- *    depth bound exceeded (the bound is printed, never silent)
- *  - `JD0040` — `saveChanges()` cannot order its statements: the
- *    entities being inserted or deleted form a foreign-key cycle
- *    (self-references included); break the save in two
- *  - `JD0050` — a live query was registered on a store opened without
- *    `capture`; the patch stream is the invalidation source
- *  - `JD0051` — `mode: 'incremental'` was demanded but the document
- *    classifies as re-run; the reason names the forcing construct
- *  - `JD0052` — registering would exceed the store's `live.maxQueries`
- *    bound; the bound is printed, never silent
- *  - `JD0020` — a migration's `from` hash does not match the
- *    database's recorded shape; running it would corrupt
- *  - `JD0021` — a draft transform was not filled in, or a document no
- *    longer validates after the migration (a narrowing without an
- *    adequate transform)
- *  - `JD0022` — the migration list disagrees with the applied history
- *    (an edited file, a missing file, a reordered sequence)
- *  - `JD0023` — a step failed: an assertion returned rows, DDL was
- *    rejected, or a transform produced an unstorable value
- */
-export declare class DbCompileError extends CodedError {
-    /**
-     * @param {string} code
-     * @param {string} reason - The bare reason; `message` is composed per
-     *   the coded contract.
-     * @param {string} [docPath] - JSON Pointer into the model document,
-     *   where one exists.
-     * @param {Error} [cause]
-     */
-    constructor(code: string, reason: string, docPath?: string, cause?: Error);
-}
-/**
- * A failure while reading or writing an open store. Codes:
- *
- *  - `JD2001` — `insert` hit a document already stored under the key
- *  - `JD2002` — the declared key pointer resolved to nothing or to a
- *    non-scalar, or an explicit key argument is not a string or number
- *  - `JD2003` — the injected validation hook rejected the document
- *    that a write would have stored; `errors` carries the hook's
- *    findings when it produced any
- *  - `JD2004` — `collection()` named a collection the model does not
- *    declare
- *  - `JD2005` — the database rejected an operation for a reason that
- *    is not a duplicate key; the original error is the `cause`
- *  - `JD2006` — `patch` addressed a key with no stored document
- *  - `JD2007` — a fetch crossed the profile's `maxRows` bound; the
- *    result is refused whole, never silently truncated
- *  - `JD2040` — an optimistic update or delete matched no row: the
- *    declared version changed under the save (or the row is gone);
- *    the error names the entity and key, and the whole save rolled
- *    back
- *  - `JD2050` — a session changeset carried bytes this decoder does
- *    not recognise (a future SQLite format change would land here)
- *  - `JD2051` — `changesSince` was called on a store whose capture
- *    has no persisted log
- *  - `JD2060` — maintenance crossed the live query's `maxMaintained`
- *    bound; the query delivered this error and closed rather than
- *    degrade
- *  - `JD2061` — a second context tried to open a database whose
- *    storage grants one context exclusive access (the owner topology
- *    of LIVE-FORMAT §11); connect to the owner instead
- */
-export declare class DbRuntimeError extends CodedError {
-    collection: string | undefined;
-    key: string | number | undefined;
-    errors: unknown[] | undefined;
-    /**
-     * @param {string} code
-     * @param {string} reason - The bare reason; `message` is composed per
-     *   the coded contract.
-     * @param {{ docPath?: string, collection?: string,
-     *   key?: string | number, errors?: unknown[], cause?: unknown }} [details]
-     *   - `docPath` points into the model document (the collection the
-     *   failure belongs to); `collection`/`key` are installed as own
-     *   properties; `errors` carries validation findings; `cause` follows
-     *   the coded contract's `hasOwn` form.
-     */
-    constructor(code: string, reason: string, details?: {
-        docPath?: string;
-        collection?: string;
-        key?: string | number;
-        errors?: unknown[];
-        cause?: unknown;
-    });
-}

package/dist/types/graph.d.ts

@@ -1,28 +0,0 @@
-/**
- * @file Row → entity-graph reconstruction. One place owns the merge
- * discipline (§9.3): mapped scalar columns fold back into the JSONB
- * document's parse (booleans un-integer, SQL NULL reads back ABSENT,
- * derived epoch columns are skipped because the string never left the
- * document), foreign-key columns fold in the same way, and — for the
- * one-statement graph loads — projected relation JSON parses
- * recursively into child arrays or single children.
- */
-/**
- * Merge one database row back into its entity document.
- * @param {any} entityMapping - `explainMapping(...).entities[name]`
- * @param {any} row - a row carrying the entity's columns plus the
- *   rendered document text
- * @param {string} [docField] - the column the document text rides in
- * @returns {any}
- */
-export declare function mergeEntityRow(entityMapping: any, row: any, docField?: string): any;
-/**
- * Parse one graph-load row: the root entity's merge plus every
- * included relation's projected JSON, recursively.
- * @param {any} node - the include-plan node
- *   `{ entityMapping, includes: { name, field, many, count, child }[] }`
- * @param {any} row
- * @param {string} docField
- * @returns {any}
- */
-export declare function parseGraphRow(node: any, row: any, docField?: string): any;

package/dist/types/index.d.ts

@@ -1,37 +0,0 @@
-/**
- * @file @jarenjs/db — document storage over SQLite through two seams:
- * a driver (how a connection is made: `@jarenjs/db/node`, `/bun`, or
- * `/wasm` with an injected handle) and a dialect (how SQL is spelled).
- * This root subpath never touches a runtime builtin — a browser
- * bundler resolves it clean; the bindings live behind their own
- * subpaths and load their builtin lazily inside `open()`.
- */
-export { openStore, normalizeModel, MODEL_VERSION } from './store.js';
-export { createDialect } from './dialect.js';
-export { sqliteDialect } from './dialects/sqlite.js';
-export { SQLITE_FLOOR, chain, toPromise, isThenable, compareVersions, openConnection, wrapStatement, lazyOpen, } from './driver.js';
-export { planCollection, compileIndexPath, schemaTypeAt, KEY_COLUMN, DOC_COLUMN, normalizeDeclaredSql, comparableDeclaredSql, } from './ddl.js';
-export { planQuery, assertDecidedKind, entityShape, entityPathRef, planEntityPredicate, planEntityQuery, } from './plan.js';
-export { emitPlan, createEntityPredicateEmitters, emitEntityPlan } from './emit.js';
-export { mergeEntityRow, parseGraphRow } from './graph.js';
-export { selectPlan, conjoin, assertNoSqlText, PLAN_VERSION } from './algebra.js';
-export { typeOfPath, isNumericType } from './types.js';
-export { compileSetResidual, compileRowResidual, sequenceResult } from './residual.js';
-export { deterministicFragment, registerFragment } from './udf.js';
-export { DERIVE_KINDS, DERIVE_MAPPING, PHYSICAL_KINDS, BBOX_COMPONENTS, BBOX_INDEX_ORDER, PRECISION_MIN, PRECISION_MAX, DIMS_MIN, DIMS_MAX, deriveGeohash, deriveBboxEdge, deriveVector, derivedValue, derivedMappingFor, memberAt, storedMemberForm, registerDeriveFunctions, probeVector, columnScore, } from './derive.js';
-export { KNN_MARGIN, IDENTITY_CHUNK, cutCandidates, identityBatches } from './knn.js';
-export { createQueryEngine, createQueryState, createEntityQueryEngine, createLoadEngine, INCLUDE_DEPTH_DEFAULT, } from './query.js';
-export { normalizeProfile, SAFE_PROFILE, translateProfilePredicate, applyMandatoryPredicate, applyRowBound, } from './profile.js';
-export { translatePatch } from './patch-sql.js';
-export { normalizeEntities, explainMapping } from './model.js';
-export { planEntity, planJoinTable } from './ddl.js';
-export { entityCore } from './entity.js';
-export { entityEmitModel } from './emit-model.js';
-export { parseChangeset, translateOperations, keyToken, createCaptureEngine, CHANGES_TABLE, DEFAULT_RETENTION, } from './capture.js';
-export { createTracker, deepFreeze, BATCH_PARAM_BUDGET, BATCH_ROW_BOUND, } from './tracker.js';
-export { planMigration, planModelMigration, migrate, migrationStatus, shapeHash, migrationChecksum, createModelShape, schemaShapeOf, compareShapeToModel, MIGRATION_VERSION, HISTORY_TABLE, } from './migrate.js';
-export { DbCompileError, DbRuntimeError, DB_CODES } from './errors.js';
-export { classifyLiveQuery, createLiveRegistry, diffRows, LIVE_DEFAULTS } from './live.js';
-export { createSortedWindow, compareCodepoint } from './window.js';
-export { createJobEngine, JOBS_TABLE, JOB_CHECKPOINTS_TABLE, JOB_DEFAULTS, describeValue, serializeResult, } from './jobs.js';
-export { createDagJobRunner } from './dag-job.js';

package/dist/types/jobs.d.ts

@@ -1,140 +0,0 @@
-/**
- * @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. A loop the deadline could not drain
- *    is CANCELLED, not merely left behind: when its handler finally
- *    settles it exits without another claim, store write or poll
- *    timer, and its abandoned job recovers by lease expiry (§5).
- */
-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.
-         * A loop the grace period could not drain is cancelled outright:
-         * when its handler finally settles it exits without another
-         * claim, store write or poll timer.
-         * @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/knn.d.ts

@@ -1,69 +0,0 @@
-/**
- * @file The candidate cut of a k-nearest plan: the arithmetic between
- * the scores a statement fetched and the row identities the engine
- * will decide over. No vector arithmetic lives here — a score is
- * `derive.js`'s, through `@jarenjs/core/vector` — and no SQL: the
- * fetch of the winners is the dialect's. This is the one place the
- * margin is applied and the one place candidate identities are
- * batched for it.
- */
-/**
- * The inclusive score margin of the cut. The column's score is a dot
- * product over binary32-normalized forms; the engine's key is the
- * cosine of the raw doubles; measured, the two differ by at most
- * ~1e-8. Any margin of at least twice that makes the engine's top
- * `offset + limit` a SUBSET of the candidates: were a row the engine
- * ranks inside the window cut, some candidate the engine ranks outside
- * it would have to score higher by the column and lower by the engine,
- * which two scores within half the margin of each other cannot do.
- * This is a hundred times that bound — it admits, in practice, only
- * true ties, and those the engine breaks by the document's own keys.
- */
-export declare const KNN_MARGIN = 0.000001;
-/**
- * The most identities one fetch statement binds: under the parameter
- * cap of every SQLite build the store runs on. A guard, not a design —
- * a k-nearest window is a handful of rows, and this only matters for a
- * collection of many exact duplicates.
- */
-export declare const IDENTITY_CHUNK = 512;
-/**
- * The rows a k-nearest window can contain, from the scored fetch.
- *
- * `m = offset + limit` rows are needed. When at least `m` rows scored,
- * the candidates are every scored row within `margin` of the m-th best
- * score — ties at the boundary included by construction. When fewer
- * did, the window reaches the unrankable tail (NULL columns, or a
- * collection smaller than the window), which only the documents can
- * order: every row is then a candidate, and the collection is no
- * larger than the window.
- * @param {{ identity: any, score: number | null }[]} rows - one per
- *   fetched row; `score` is `null` where the column held no vector
- * @param {number} m - `offset + limit`
- * @param {number} margin
- * @returns {{ identities: any[], scored: number, full: boolean }} the
- *   candidate identities in ascending identity order — the
- *   collection's own order, which a stable sort over the candidates
- *   must see — with how many rows scored and whether every row was
- *   taken
- */
-export declare function cutCandidates(rows: {
-    identity: any;
-    score: number | null;
-}[], m: number, margin: number): {
-    identities: any[];
-    scored: number;
-    full: boolean;
-};
-/**
- * The identities sliced into fetch batches: at most `IDENTITY_CHUNK`
- * each, and each padded with `null` to the next power of two — a NULL
- * in an IN list matches no row — so a handful of prepared statements
- * serve every candidate count instead of one per count seen.
- * @param {any[]} identities - in the order they should be fetched
- * @returns {{ size: number, params: any[] }[]}
- */
-export declare function identityBatches(identities: any[]): {
-    size: number;
-    params: any[];
-}[];

package/dist/types/live.d.ts

@@ -1,62 +0,0 @@
-/**
- * @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;
-};