@jarenjs/db 0.34.0

package/dist/types/query.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @file The query surface over one collection: the D2 provider
+ * (`execute(document, options)` — how a linq chain runs here with no
+ * import edge), the streaming cursor (`query`), and `explain()`.
+ *
+ * The statement cache is a CALLER of the core primitives:
+ * `createSemanticCache` keyed by the whole discriminating tuple —
+ * document plus collection, dialect, strictness, pushdown and profile.
+ * The identity is the tuple's COMPLETE serialization, never a
+ * fingerprint of it: a 32-bit content hash collides after tens of
+ * thousands of documents, and a collision here answers one query with
+ * another query's plan and rows. `store.stats()` exposes hits, misses
+ * and evictions so the cache is proven rather than assumed.
+ *
+ * Bind-time diversion: if any referenced external is missing or not a
+ * string or finite number, the call runs the always-compilable set
+ * residual over the full collection instead of the native statement —
+ * SQLite cannot bind a boolean, a `null` needs Jaren's semantics, and
+ * a missing external must raise the ENGINE's error, not a driver's.
+ */
+/**
+ * The store-wide query state shared by every collection's engine: one
+ * bounded statement cache, its counters, the UDF registration set, and
+ * the store's resolved registered operators (Ring 2 — `{ functions,
+ * extensions }` or `null`), threaded to every engine that builds a
+ * residual.
+ * @param {number} [bound]
+ * @param {{ functions?: any, extensions?: any } | null} [operators]
+ * @returns {any}
+ */
+export declare function createQueryState(bound?: number, operators?: {
+    functions?: any;
+    extensions?: any;
+} | null): any;
+/**
+ * The query engine for one collection.
+ * @param {{ connection: any, state: any, collection: any,
+ *   physicalPlan: any, profile?: any }} context - `collection` is the
+ *   normalized collection; `physicalPlan` is the DDL plan
+ *   (columns, indexes); `profile` is the store-level normalized
+ *   profile, if one was opened with
+ * @returns {{ execute: Function, query: Function, explain: Function }}
+ */
+export declare function createQueryEngine(context: {
+    connection: any;
+    state: any;
+    collection: any;
+    physicalPlan: any;
+    profile?: any;
+}): {
+    execute: Function;
+    query: Function;
+    explain: Function;
+};
+/** The default include depth bound (D14: printed, never silent). */
+export declare const INCLUDE_DEPTH_DEFAULT = 3;
+/**
+ * The store-level entity query engine: documents over the
+ * multi-entity root (`$.<Entity>[*]` bindings), planned to guarded
+ * selections and INNER equijoins, with the set residual running the
+ * whole document over the fetched root — the same honesty contract as
+ * phase A.
+ * @param {{ connection: any, entities: Map<string, any>, mapping: any,
+ *   state: any }} context
+ * @returns {any}
+ */
+export declare function createEntityQueryEngine(context: {
+    connection: any;
+    entities: Map<string, any>;
+    mapping: any;
+    state: any;
+}): any;
+/**
+ * The one-statement graph loader: `entity.load(spec)` compiles an
+ * include tree to correlated subqueries projected as JSON — one
+ * statement regardless of depth (asserted by a counting driver in the
+ * tests, because N+1 is a test, not a promise). Per-relation `where`,
+ * `orderBy` and `take` are applied INSIDE the subquery; depth is
+ * bounded with the default printed in the refusal; cycles in the
+ * specification are rejected; and keyset pagination is chosen over a
+ * growing OFFSET whenever the top-level ordering is a single unique
+ * column, with the choice reported by `explainLoad`.
+ * @param {{ connection: any, entities: Map<string, any>, mapping: any,
+ *   state: any }} context
+ * @param {string} entityName
+ * @returns {any}
+ */
+export declare function createLoadEngine(context: {
+    connection: any;
+    entities: Map<string, any>;
+    mapping: any;
+    state: any;
+}, entityName: string): any;
+export type ParamCollector = {
+    literal?: any;
+    external?: string;
+}[];
+/**
+ * @typedef {{ literal?: any, external?: string }[]} ParamCollector
+ */

package/dist/types/residual.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file Residual compilation: the part of a query that stays in
+ * JavaScript is a REAL compiled Jaren query — the same engine, the
+ * same semantics — never a reimplementation.
+ *
+ * Two modes (ARCHITECTURE.md):
+ *
+ * - `set` — the whole original document compiled once, run over the
+ *   materialized candidate array. Re-applying pushed conjuncts is
+ *   idempotent, so SQL-side narrowing never changes the answer.
+ * - `row` — only the projection stayed behind: each fetched row runs
+ *   `{ $for: { it: '$[*]' }, $return: [ <ret> ] }` over the one-row
+ *   array; the array wrapper packs the item sequence so an
+ *   array-VALUED item stays unambiguous, and the per-row results
+ *   concatenate in row order (streamable).
+ */
+/**
+ * Compile the whole document for set-mode evaluation. A profile's
+ * engine limits ride into the compilation so the JavaScript portion is
+ * bounded by the engine's own enforcement.
+ * @param {any} document
+ * @param {any} [limits]
+ * @param {{ functions?: any, extensions?: any } | null} [operators] -
+ *   the store's registered operators, so the residual can evaluate them
+ * @returns {(candidates: any[], externals: any) => any}
+ */
+export declare function compileSetResidual(document: any, limits?: any, operators?: {
+    functions?: any;
+    extensions?: any;
+} | null): (candidates: any[], externals: any) => any;
+/**
+ * Compile the per-row projection for row-mode evaluation.
+ * @param {any} returnExpression - The document's raw `$return` value
+ * @param {any} [limits]
+ * @param {{ functions?: any, extensions?: any } | null} [operators]
+ * @returns {(row: any, externals: any) => any[]} the row's items
+ */
+export declare function compileRowResidual(returnExpression: any, limits?: any, operators?: {
+    functions?: any;
+    extensions?: any;
+} | null): (row: any, externals: any) => any[];
+/**
+ * Map a flat item array onto the engine's result shape: an empty
+ * sequence is `undefined`, a singleton is the item, anything longer is
+ * the array (probed engine behaviour, pinned by the differential
+ * tests).
+ * @param {any[]} items
+ * @returns {any}
+ */
+export declare function sequenceResult(items: any[]): any;

package/dist/types/store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file The store: `openStore(model, options)` normalizes the model
+ * document, opens a database through the injected driver, applies (or
+ * verifies) the physical shape, and gives transactional,
+ * schema-validated reads and writes.
+ *
+ * The public surface is ASYNCHRONOUS — every method returns a promise
+ * — because the browser's OPFS story forces it regardless of any other
+ * backend. Where the driver is synchronous the same operations exist
+ * without the promise under `store.sync`, present only there — never a
+ * throwing stub — so portable code pays one declared microsecond and
+ * code that wants it back opts in knowingly. Internally everything
+ * composes through the sync-capable {@link chain}, so the async
+ * surface allocates exactly one promise per call, not one per step.
+ *
+ * Writes validate through an injected `compileSchema` hook with the
+ * `compileTypeTest` signature; absent, writes are unvalidated and
+ * `store.capabilities.validated === false` — a declared downgrade,
+ * never a silent one. `@jarenjs/validate` is never imported here.
+ */
+/** The model format version this store implements. */
+export declare const MODEL_VERSION = "0.1";
+/**
+ * Normalize and check a model document. Every failure is `JD0005` with
+ * a `docPath` into the model.
+ * @param {any} model
+ * @returns {Map<string, any>} collection name -> normalized collection
+ */
+export declare function normalizeModel(model: any): Map<string, any>;
+/**
+ * Open (or create) a store described by a model document.
+ * @param {any} model - A `jaren-model` document (the 0.1 subset)
+ * @param {{ driver: any, path?: string, compileSchema?: Function,
+ *   busyTimeout?: number, queueTimeout?: number, journalMode?: string,
+ *   statementCacheBound?: number, profile?: any, operators?: any,
+ *   functions?: any, extensions?: any,
+ *   readOnly?: boolean }} options
+ * @returns {Promise<any>}
+ */
+export declare function openStore(model: any, options: {
+    driver: any;
+    path?: string;
+    compileSchema?: Function;
+    busyTimeout?: number;
+    queueTimeout?: number;
+    journalMode?: string;
+    statementCacheBound?: number;
+    profile?: any;
+    operators?: any;
+    functions?: any;
+    extensions?: any;
+    readOnly?: boolean;
+}): Promise<any>;

package/dist/types/tracker.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file The unit of work (§11): copy-on-write change tracking and
+ * minimal writes. Materialised entities are plain, DEEP-FROZEN JSON —
+ * no proxies anywhere — and the tracker retains exactly ONE reference
+ * per tracked entity: the frozen document itself is the snapshot.
+ * Mutation is replacement (`put(next)`); `saveChanges()` diffs
+ * snapshot against current with the suite's own diff engine and plans
+ * the MINIMAL set of parameterised statements: scalar/epoch/foreign-
+ * key column writes, `jsonb_set`/`jsonb_remove` chains for document
+ * paths, join-table synchronisation for many-to-many members, and a
+ * counted whole-row fallback for anything untranslatable.
+ *
+ * Ordering never violates a foreign key mid-transaction: inserts run
+ * parent-first, deletes child-first, updates in between, join rows
+ * after both endpoints exist. A foreign-key cycle among the entities
+ * being inserted or deleted is `JD0040`, reported, never a deadlock.
+ * The whole save is one transaction; the tracker is mutated ONLY
+ * after commit, so a failed save leaves it exactly as it was and a
+ * retry is possible.
+ */
+/** Rows per batched INSERT: bounded by the portable parameter budget. */
+export declare const BATCH_PARAM_BUDGET = 900;
+export declare const BATCH_ROW_BOUND = 100;
+/**
+ * Deep-freeze a JSON value in place and return it. Idempotent; shared
+ * substructure (a graph load's children) freezes once.
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+export declare function deepFreeze<T>(value: T): T;
+/**
+ * The store-level unit of work.
+ * @param {{ connection: any, entities: Map<string, any>, mapping: any,
+ *   coreFor: (name: string) => any }} context
+ * @returns {any}
+ */
+export declare function createTracker(context: {
+    connection: any;
+    entities: Map<string, any>;
+    mapping: any;
+    coreFor: (name: string) => any;
+}): any;

package/dist/types/typed.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file The typed-store binding: a zero-cost identity whose ONLY job
+ * is carrying the generated `EntityMetaMap` into the type system —
+ * `typedStore<EntityMetaMap>(store)` narrows `entity(name)` to the
+ * generated document/input shapes and widens `load` results by their
+ * include specification. The runtime is the store it was given; every
+ * guarantee lives in `types/typed.d.ts` and the generated artifact.
+ */
+/**
+ * Bind a store to its generated entity metadata. Identity at runtime.
+ * @template E
+ * @param {any} store - an opened store whose model generated `E`
+ * @returns {any}
+ */
+export declare function typedStore<E>(store: any): any;

package/dist/types/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file Schema-derived path typing: the collection's JSON Schema is the
+ * planner's type source (there is no engine-side inference in this
+ * phase — the store's own contract carries the types). Where the
+ * schema says nothing, the answer is `'unknown'` and the planner emits
+ * the defensive form; the guards in the truth table make `'unknown'`
+ * safe, so typing here only ever IMPROVES a plan (column choice), it
+ * never weakens one.
+ */
+/**
+ * The planner-facing type of a member path.
+ * @param {any} schema - The collection's document schema
+ * @param {({ name: string } | { index: number })[]} segments
+ * @returns {'string' | 'integer' | 'number' | 'boolean' | 'unknown'}
+ */
+export declare function typeOfPath(schema: any, segments: ({
+    name: string;
+} | {
+    index: number;
+})[]): 'string' | 'integer' | 'number' | 'boolean' | 'unknown';
+/**
+ * Whether a planner type is numeric (SQL comparison family).
+ * @param {string} type
+ * @returns {boolean}
+ */
+export declare function isNumericType(type: string): boolean;

package/dist/types/udf.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @file The UDF escape hatch (capability-gated): between native SQL
+ * and pulling rows sits registering a compiled predicate conjunct as a
+ * DETERMINISTIC function used in the WHERE clause. Only fragments the
+ * analysis proves deterministic and side-effect-free qualify — no
+ * externals (their values change per call, and a deterministic
+ * function must not close over changing state), no host functions, no
+ * collations. Registration is keyed by the fragment's COLLISION-FREE
+ * structural identity, so identical fragments share one registration
+ * per store and different fragments never do. A fingerprint could not
+ * decide this: two colliding fragments would claim one SQL function
+ * name, the second would silently reuse the first's predicate, and the
+ * WHERE clause would filter on the wrong condition. The SQL identifier
+ * still derives from a short fingerprint — names must be short — but a
+ * fingerprint clash between DIFFERENT identities is disambiguated with
+ * a suffix rather than collapsed.
+ *
+ * WHERE-clause use only: an INDEX over a registered function would
+ * make the database unwritable from any connection that has not
+ * registered the identical function — that schema-dependency hazard is
+ * why the model format declares no UDF-expression indexes.
+ *
+ * Ring 3 extends the hatch to registry `pushable:'scalar'`
+ * operators: a predicate fragment that uses a registered scalar operator
+ * (`$sqrt`, `$pow`, …) compiles WITH the store's `{ functions,
+ * extensions }` and pushes as the same deterministic UDF — SQLite drives
+ * the row iteration and the operator runs inside the callback, instead
+ * of every candidate crossing into the residual. The determinism rule is
+ * unchanged (no externals, no collations); a registered operator the
+ * pack did NOT mark `pushable:'scalar'` (a whole-series `$npv`, an
+ * aggregate) stays the residual — Ring 2 keeps it correct.
+ */
+/**
+ * Decide whether a raw predicate fragment qualifies for the hatch, and
+ * build its registration if so.
+ * @param {any} fragment - The raw conjunct (a JSON query expression
+ *   over `$it`)
+ * @param {{ functions?: any, extensions?: any, pushableScalar?: Set<string> } | null}
+ *   [operators] - the store's registered operators (Ring 3); only its
+ *   `pushable:'scalar'` subset is admitted. `null`/absent keeps the
+ *   original engine-internal-only rule (no host function pushes).
+ * @returns {{ key: string, name: string,
+ *   compile: () => (docText: string) => number } | null}
+ */
+export declare function deterministicFragment(fragment: any, operators?: {
+    functions?: any;
+    extensions?: any;
+    pushableScalar?: Set<string>;
+} | null): {
+    key: string;
+    name: string;
+    compile: () => (docText: string) => number;
+} | null;
+/**
+ * Register a qualified fragment once per store, and answer the SQL name
+ * to call. Identity is the fragment's structural key, so the same
+ * fragment registers once and two different fragments always get two
+ * different functions — even when their short names fingerprint alike,
+ * which the suffix resolves.
+ * @param {any} connection
+ * @param {Map<string, string>} registered - The store's registrations,
+ *   fragment identity → the SQL function name it owns
+ * @param {{ key: string, name: string, compile: () => Function }} fragment
+ * @returns {string} the function name to call in the WHERE clause
+ */
+export declare function registerFragment(connection: any, registered: Map<string, string>, fragment: {
+    key: string;
+    name: string;
+    compile: () => Function;
+}): string;

package/dist/types/window.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file The maintained sorted window for `orderBy` (+ optional
+ * `limit`) live queries — LIVE-FORMAT §7's window row. The structure
+ * keeps EVERY matching row in sorted order (which is what makes a
+ * delete inside the visible window answerable without a re-query: the
+ * successor is already here), and the visible result is the first
+ * `limit` entries. Ties are broken by the collection key token,
+ * always ascending — the total order LIVE-FORMAT §9 promises.
+ *
+ * String comparison is CODEPOINT order (SQLite BINARY over UTF-8 —
+ * probed, never assumed), which `<` on JS strings gets wrong for
+ * astral-vs-BMP pairs; `compareCodepoint` walks code points.
+ */
+/**
+ * Compare two strings in Unicode code-point order.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export declare function compareCodepoint(a: string, b: string): number;
+export type WindowEntry = {
+    token: string;
+    sortValues: any[];
+    item: any;
+};
+/**
+ * @typedef {{ token: string, sortValues: any[], item: any }} WindowEntry
+ */
+/**
+ * A maintained sorted set of rows under the declared order terms plus
+ * the key-token tiebreaker.
+ * @param {{ desc: boolean, emptyGreatest: boolean }[]} terms
+ * @param {number | null} limit - visible size; `null` = everything
+ */
+export declare function createSortedWindow(terms: {
+    desc: boolean;
+    emptyGreatest: boolean;
+}[], limit: number | null): {
+    compare: (a: WindowEntry, b: WindowEntry) => number;
+    size: () => number;
+    /** The visible slice: the first `limit` entries (all, unbounded). */
+    visible: () => WindowEntry[];
+    /**
+     * Insert a row; the token MUST not be present.
+     * @param {string} token
+     * @param {any[]} sortValues
+     * @param {any} item
+     */
+    insert(token: string, sortValues: any[], item: any): void;
+    /** Remove a row by token; absent tokens are a no-op. */
+    remove(token: any): boolean;
+};

package/docs/JOBS-FORMAT.md

@@ -0,0 +1,218 @@
+# The Jaren jobs format — the durable queue
+
+This document is normative. The key words MUST, MUST NOT, SHOULD and
+MAY are to be interpreted as described in RFC 2119. Error codes join
+the package's single runtime table (MODEL-FORMAT §7); this order adds
+none — see §9.
+
+## 1. Scope
+
+A single-database job queue: enqueue, lease, execute, retry with
+backoff, dead-letter, and recover after a crash — the persistence,
+polling, locking, retries and recovery an adopter otherwise builds as
+infrastructure. It is enabled per store and lives in two internal
+tables beside the model's own:
+
+```js
+const store = await openStore(model, { driver: nodeDriver(), jobs: true });
+const id = await store.jobs.enqueue('welcome-mail', { userId: 'u1' });
+const worker = store.jobs.createWorker({
+  handlers: { 'welcome-mail': async (payload, context) => { /* … */ } },
+  concurrency: 2,
+});
+worker.start();
+```
+
+The queue composes with `@jarenjs/flow` checkpointed runs through §7
+— that composition, not the queue alone, is the reason this exists:
+a run that crashes resumes from its recorded nodes instead of
+restarting.
+
+## 2. The job record
+
+`_jaren_jobs`, one row per job, surfaced camel-cased and frozen:
+
+| column | meaning |
+|---|---|
+| `id` | TEXT primary key; caller-supplied or a UUID. **A caller-supplied id makes `enqueue` idempotent**: re-enqueueing an existing id changes nothing and answers the id — this is the idempotency key of §7 |
+| `kind` | the registered handler name (the suite's named-registry discipline) |
+| `payload` | the enqueue payload, JSON text; `null` stays null |
+| `state` | `pending` → `leased` → `done`, or `failed` (awaiting retry) → `dead` (attempts exhausted) |
+| `run_at` | epoch ms eligibility: scheduling and retry backoff are the same mechanism |
+| `attempts` | claims so far; incremented AT claim, so a crashed attempt counts |
+| `max_attempts` | per job, default 5 |
+| `lease_until`, `lease_owner` | the lease (§3); null unless leased |
+| `last_error` | the last failure's `message`, retained through retries and into `dead` |
+| `result` | the completion value, JSON text (§7 records the DAG output here) |
+| `created_at`, `updated_at` | epoch ms |
+
+`_jaren_job_checkpoints` holds `(run_id, node_id, value)` rows — the
+flow checkpoint store of §7, keyed by the JOB id (the run id IS the
+job id). Both tables are created on open when `jobs` is requested;
+neither appears in the model.
+
+## 3. Leasing and exactly-once execution
+
+Claiming is ONE guarded statement — one statement is one transaction,
+so two workers cannot claim the same job, without any distributed
+lock:
+
+```sql
+UPDATE "_jaren_jobs" SET state='leased', lease_owner=?, lease_until=?,
+  attempts=attempts+1, updated_at=?
+WHERE id = (SELECT id FROM "_jaren_jobs"
+  WHERE (state='pending' OR state='failed'
+         OR (state='leased' AND lease_until < ?))
+    AND run_at <= ? AND kind IN (…the worker's registered kinds…)
+  ORDER BY run_at, created_at, id LIMIT 1)
+RETURNING *
+```
+
+- The `kind IN` clause is the deploy-ordering protection: **a job
+  whose kind has no registered handler on this worker is simply never
+  claimed by it** — it stays `pending` and shows in `counts()`, it is
+  NOT dead-lettered by an accident of rollout order.
+- Every later transition is guarded by the lease:
+  `… WHERE id=? AND state='leased' AND lease_owner=?`. A worker whose
+  lease expired mid-run (a stall, a long GC, a laptop lid) finds its
+  completion matching ZERO rows and its result discarded — the job
+  belongs to whoever re-claimed it. Execution is therefore
+  AT-LEAST-ONCE; **completion is exactly-once**. Idempotency of side
+  effects is the handler's responsibility (§7).
+- Eligibility order is `run_at, created_at, id` — oldest first,
+  deterministic. There are no priority classes (§8).
+
+## 4. Retry and dead-lettering
+
+A failed attempt (the handler threw or rejected) records
+`last_error` and either:
+
+- `attempts < max_attempts` → `state='failed'`,
+  `run_at = now + backoff(attempts)` — the retry IS a scheduled job;
+- else → `state='dead'`, terminal. Dead jobs keep their `last_error`
+  and their checkpoint rows (a post-mortem can read exactly how far
+  the run got).
+
+Backoff is exponential with jitter:
+`min(cap, base × 2^(attempts−1)) × (0.5 + random()/2)`, defaults
+`base` 1 000 ms, `cap` 60 000 ms. `Math.random` is the runtime
+default; the `random` option injects a deterministic source and every
+test in this repository does.
+
+## 5. Recovery
+
+A worker that dies mid-job leaves a `leased` row whose `lease_until`
+passes; the claim statement (§3) treats an expired lease exactly like
+`pending`, so **recovery is not a separate sweeper — it is the next
+claim**. The reclaimed attempt re-runs the handler; a §7 DAG job
+resumes from its checkpoint rows rather than restarting. The lease
+duration (`leaseMs`, default 30 000 ms) is therefore the recovery
+latency ceiling: a handler that legitimately outlives its lease gets
+reclaimed — size `leaseMs` to the slowest honest handler.
+
+## 6. Workers and concurrency
+
+`createWorker({ handlers, concurrency, pollInterval, leaseMs, owner,
+maxAttempts, backoff, random })` returns `{ start(), stop(),
+stats() }`:
+
+- `concurrency` (default 1) independent claim-execute loops share one
+  worker registration;
+- an idle loop sleeps `pollInterval` (default 500 ms — at most
+  2 claims/s of idle cost per loop, stated). An `enqueue` on the SAME
+  store wakes every idle local loop immediately, so same-process
+  latency is not poll-bound; **cross-process wake-up is polling**,
+  plainly (§8);
+- `stop({ graceMs })` aborts in-flight handlers and resolves once they
+  settle **or** the grace period expires (default 5 s), answering
+  `{ drained, inFlight }` — see §6.1;
+- `stats()` reports claims, completions, failures, wakes, polls and the
+  in-flight handler count.
+
+### 6.1 A handler cannot break the loop, and cannot hold shutdown
+
+Two invariants a long-running process depends on.
+
+**No handler outcome rejects the claim-execute loop.** A handler is host
+code: it may resolve with something JSON cannot express (a `BigInt`, a
+cycle, a throwing `toJSON`) or reject with a value whose own `message`
+throws when read. Both are normalized totally and become an ordinary
+failed attempt — retried with backoff, dead-lettered at `maxAttempts`,
+recorded in `last_error`. The reason this matters more than it looks: a
+rejected loop stops claiming, and a queue that has silently stopped
+draining looks exactly like a queue with nothing to do.
+
+**Shutdown is bounded.** Handlers receive an `AbortSignal` alongside the
+job:
+
+```js
+handlers: {
+  sync: async (payload, { job, signal, checkpointsFor }) => {
+    const res = await fetch(url, { signal });   // cancelled on stop()
+    …
+  },
+}
+```
+
+`stop({ graceMs })` aborts the signal, waits up to `graceMs`, and then
+returns `{ drained, inFlight }` regardless. `store.close({ graceMs })`
+does the same and **closes the connection either way**, then reports
+`JD2062` when handlers were left running — a report, not a refusal: the
+handle really is released. A handler that ignores its signal therefore
+cannot hold the database file open for the life of the process, and the
+lease expiry (§5) lets another worker re-claim its job.
+
+## 7. The DAG composition
+
+```js
+import { compileDag } from '@jarenjs/flow';
+const runner = createDagJobRunner(store, {
+  compileDag,                      // INJECTED — db never imports flow
+  documents: { 'sync-report': dagDocument },
+  tasks: { fetch: async () => { /* … */ } },
+});
+runner.start();
+await store.jobs.enqueue('sync-report', { input: { day: '2026-08-05' } });
+```
+
+- The engine arrives as a capability (the D10 shape applied to flow);
+  `@jarenjs/db`'s manifest and import graph name `@jarenjs/flow`
+  nowhere, asserted by test.
+- The job id is the run id. Node values save into
+  `_jaren_job_checkpoints` as the run progresses; `complete` records
+  the DAG result AND marks the job `done` **in one guarded
+  statement** — one transaction, so a failure leaves neither, and the
+  checkpoint rows of a finished job are pruned in the same breath.
+- A reclaimed DAG job resumes: recorded nodes seed (FLOW-FORMAT
+  §7.6), the rest re-run. A task node with side effects MUST thread
+  an idempotency key (the job id is the natural one) into whatever it
+  touches; the queue cannot make a non-idempotent effect safe, and
+  does not pretend to.
+- The document belongs WITH the job kind at worker construction —
+  resuming under a different document is undefined (FLOW-FORMAT
+  §7.6), so deploys that change a dag document SHOULD drain old jobs
+  first or version the kind name.
+
+## 8. Non-goals
+
+- **One database, one machine.** Leasing coordinates workers on one
+  SQLite file. Over a network filesystem (NFS, SMB, many container
+  volume mounts) SQLite's locking is **not reliable — this queue is
+  NOT a safe cross-machine coordination substrate there**. Same-host
+  processes over WAL are the supported topology.
+- No priority classes in 0.1 (`run_at` ordering only), no cron or
+  recurring schedules (re-enqueue from a completed handler if
+  needed), no workflow-level compensation or sagas, no per-job abort
+  signal (the lease is the timeout story), no cross-process push —
+  wake-on-write is same-process; everything else polls.
+- Throughput is SQLite's single-writer throughput; the measured
+  numbers live in the execution notes, not in marketing.
+
+## 9. Errors
+
+This format adds NO codes. API misuse (a malformed handler map, a
+non-string kind, a worker started twice) is a `TypeError` at the
+call, matching the capture and live precedents; storage failures ride
+the existing `JD2005` wrap; a job's own failure is DATA — recorded in
+`last_error` and the state machine of §4 — because a queue that
+throws away its failure story has failed twice.