@camstack/system 1.2.318 → 1.2.319

package/dist/builtins/composer/composer.d.ts

@@ -47,10 +47,8 @@ export declare class Composer {
     private live;
     /** The composed devices of `new`-target blocks, and the rows that exist. */
     private readonly composed;
-    /** Consecutive applies refused because `core_blocks` had not loaded: warned once per run. */
-    private storeWaitApplies;
-    /** Consecutive applies refused because the Blocks integration had not reconciled: warned once per run. */
-    private integrationWaitApplies;
+    /** The store / integration preconditions every apply waits on first (D49, R2). */
+    private readonly waits;
     private readonly gate;
     private readonly claimGate;
     private readonly targets;
@@ -84,27 +82,17 @@ export declare class Composer {
     /** Run `work` after every apply already queued, whether that settled or failed. */
     private chained;
     private applyNow;
-    private waiting;
     private plan;
     private rebuildRuntimes;
     private ungraftGone;
-    /** Where a block's runtime writes: its composed device, or a claim-backed target on the existing device. */
-    private writerFor;
     /** C-1/N-1: the tracker follows the block's OWN claim as the hub answers it; every answer re-reads the native once. */
     private onClaimEvent;
     private heldFieldsFor;
-    private newRuntime;
     private applyName;
     private syncSources;
     /** A failed sync leaves the tracker as it was: the runtimes read what it holds. */
     private syncTracker;
-    /**
-     * Rule 3: the claims every live customization WANTS this apply; everything
-     * else the gate knows is a release candidate, handed back once two applies
-     * agree. A block that cannot plan — waiting, unreadable, failed, or with its
-     * target gone — HOLDS its claims (rule 4, rule 5): they are wanted as they
-     * are. A disabled block wants none (rule 7).
-     */
+    /** Rule 3: release what no live customization wants, once two applies agree (`wantedClaims`). */
     private reconcileClaims;
     private release;
     /**

package/dist/builtins/sqlite-storage/shm-lock-canary.d.ts

@@ -0,0 +1,60 @@
+import { IScopedLogger } from '@camstack/types';
+/** `UNIX_SHM_DMS`: the byte of the `-shm` a live connection holds shared. */
+export declare const SQLITE_SHM_DMS_BYTE = 128;
+/** How often the canary looks, in ms. One small procfs read. */
+export declare const SHM_LOCK_CANARY_INTERVAL_MS: number;
+/** One HELD lock from `/proc/locks`. Waiters (`->` lines) are not locks. */
+export interface ProcLock {
+    readonly pid: number;
+    /** The inode, as the decimal string procfs prints — never rounded through a double. */
+    readonly inode: string;
+    readonly start: number;
+    /** `null` = to end of file (`EOF`). */
+    readonly end: number | null;
+}
+/**
+ * Parse `/proc/locks`. Line shape:
+ * `1: POSIX  ADVISORY  READ 3490531 08:31:3769403373 128 128`
+ * (`id: TYPE MODE ACCESS PID MAJ:MIN:INODE START END`). A blocked waiter is
+ * printed as `1: -> POSIX …` and holds nothing, so it is skipped; a line that
+ * does not parse is skipped rather than guessed at.
+ */
+export declare function parseProcLocks(text: string): readonly ProcLock[];
+/** Does a lock owned by `pid` on `inode` cover the DMS byte? */
+export declare function holdsDmsLock(locks: readonly ProcLock[], pid: number, inode: string): boolean;
+/**
+ * `unavailable` = this platform has no `/proc/locks` (said once, then the
+ * canary stops). `unreadable` = Linux, but this look failed (the `-shm` absent,
+ * procfs unreadable) — a different fact, and on the hub a worrying one.
+ */
+export type ShmLockState = 'held' | 'missing' | 'unavailable' | 'unreadable';
+/** The canary's impure edges, injectable so a spec drives them. */
+export interface ShmLockCanaryDeps {
+    readonly platform: NodeJS.Platform;
+    readonly pid: number;
+    /** The `-shm` inode as a decimal string; throws when the file is absent. */
+    readonly shmInode: (shmPath: string) => string;
+    readonly readProcLocks: () => string;
+}
+export interface ShmLockCanaryOptions {
+    readonly dbPath: string;
+    readonly logger: IScopedLogger;
+    readonly intervalMs?: number;
+    readonly deps?: Partial<ShmLockCanaryDeps>;
+}
+export declare class ShmLockCanary {
+    private readonly shmPath;
+    private readonly logger;
+    private readonly intervalMs;
+    private readonly deps;
+    private timer;
+    private last;
+    private lastError;
+    constructor(options: ShmLockCanaryOptions);
+    start(): void;
+    stop(): void;
+    /** One look. Logs only a change of state. Public for the spec. */
+    check(): ShmLockState;
+    private observe;
+    private report;
+}

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

@@ -22,6 +22,7 @@ export declare class SqliteSettingsAddon extends BaseAddon {
     private vectorIndex;
     private walMaintenance;
     private walCheckpointer;
+    private shmLockCanary;
     constructor();
     /**
      * The engine behind `settings-store` cannot read that door during

package/dist/builtins/sqlite-storage/wal-checkpoint-policy.d.ts

@@ -33,22 +33,64 @@
  *
  * The auto-checkpoint's own rule: fold when 1000 frames are pending. The
  * point of moving the checkpoint is to change WHO waits on the disk, not how
- * often the disk is asked to sync — a worker that checkpointed every second
- * would multiply the fsync count by ten on a drive the media plane already
- * saturates. The threshold is read from the wal-index header (`mxFrame`,
- * `nBackfill`), which costs a 136-byte read and no lock; when that read is
- * unavailable the worker falls back to a fixed interval, so an unreadable
- * header can never mean "nothing to do".
+ * often the disk is asked to sync — a worker that folded every second would
+ * multiply the fsync count on a drive the media plane already saturates.
+ *
+ * ## How the worker knows how much is pending — and how it must NOT learn it
+ *
+ * Until 2026-09-29 the worker read the wal-index header straight out of the
+ * `-shm` file, once a second, with `openSync` / `readSync` / `closeSync`. That
+ * `closeSync` was the SIGBUS of D468 (corrected by D679): on POSIX, closing
+ * ANY descriptor of a file drops EVERY fcntl lock the process holds on that
+ * file — including the shared lock on `-shm` byte 128 (the "DMS" lock) that
+ * SQLite takes for the life of a connection and that tells every OTHER
+ * process "a live connection is using this wal-index, do not rebuild it". With
+ * the lock gone, the next process to open the database believed it was
+ * first, truncated and re-initialised the `-shm` under the runner's mappings,
+ * and the runner's next write past a 32 KiB wal-index region hit a page
+ * beyond end-of-file.
+ *
+ * So the worker never touches a SQLite file except through its connection.
+ * What it knows about the WAL it learns from the checkpoint it just ran:
+ * `PRAGMA wal_checkpoint(PASSIVE)` answers `log` (frames in the WAL) and
+ * `checkpointed` (frames now backfilled). Two consecutive answers give the
+ * frames appended between them, hence a rate, hence WHEN the next 1000 frames
+ * will have accumulated. The next checkpoint is scheduled for then —
+ * {@link nextCheckpointPlan} — clamped between the worker's poll interval and
+ * {@link WAL_CHECKPOINT_MAX_DELAY_MS}. A PASSIVE with nothing to fold performs
+ * no fsync (the copy and both syncs sit behind `nBackfill < mxFrame` in
+ * `wal.c`), so the clamp costs a quiet database nothing, and it bounds how
+ * long a burst that follows a quiet spell goes unseen.
  */
 /** The engine's own `wal_autocheckpoint` default, in frames. Reproduced, not changed. */
 export declare const WAL_CHECKPOINT_THRESHOLD_FRAMES = 1000;
 /**
- * Longest the worker lets pending frames sit before folding them, in ms. A
- * quiet database (a developer machine, an agent with little to persist) still
- * gets its WAL folded and its pages made durable within a minute.
+ * Longest the worker waits between two checkpoints, in ms, whatever the
+ * measured rate says. It is the bound on how late a burst after a steady or
+ * quiet spell is noticed, and it is sized against the engine's own fallback
+ * (`SQLITE_WAL_AUTOCHECKPOINT_BOUND_PAGES` = 10 000 frames), which runs INSIDE
+ * a settings-thread commit — the stall D452 moved off that thread. No burst
+ * rate has been measured on the hub (D452's 54 frames/s is the steady rate),
+ * so the design point is 1 000 frames/s, ~18× steady: 8 s of it is 8 000
+ * frames, under the fallback, so the worker looks before the engine has to.
+ * A pass that finds more than {@link WAL_CHECKPOINT_LARGE_PASS_FRAMES} is
+ * reported so this number can be tuned from the field.
+ *
+ * The cost, stated against D452: at the steady 54 frames/s the threshold
+ * would fold every ~18.5 s; this clamp folds every 8 s, ~2.3× the fsync pairs
+ * (≈ 432 frames per fold instead of 1 000). They are paid on the WORKER, a
+ * thread nobody waits on — the settings thread's commits stay appends. A pass
+ * with nothing pending does no fsync at all.
+ */
+export declare const WAL_CHECKPOINT_MAX_DELAY_MS = 8000;
+/**
+ * A pass that folded more than this many appended frames is reported (WARN,
+ * sampled: the first of each summary window, the rest counted). Half the
+ * engine's fallback bound: a gap that let this much accumulate was within 2×
+ * of handing the checkpoint back to the settings thread.
  */
-export declare const WAL_CHECKPOINT_MAX_INTERVAL_MS = 60000;
-/** How often the worker looks at the wal-index, in ms. A 136-byte read. */
+export declare const WAL_CHECKPOINT_LARGE_PASS_FRAMES = 5000;
+/** Shortest gap between two checkpoints, in ms — the worker's poll interval. */
 export declare const WAL_CHECKPOINT_POLL_MS = 1000;
 /**
  * A checkpoint that took this long is reported at WARN with its numbers.
@@ -56,38 +98,74 @@ export declare const WAL_CHECKPOINT_POLL_MS = 1000;
  * the profiler used to file as a slow `set`, now on the thread that paid it.
  */
 export declare const WAL_CHECKPOINT_SLOW_MS = 1000;
-/** The two wal-index counters the judgement reads, or `null` when unreadable. */
-export interface WalIndexCounters {
-    /** Frames in the WAL that are valid for the current cycle. */
-    readonly mxFrame: number | null;
-    /** Frames already copied back into the database file. */
-    readonly nBackfill: number | null;
+/** What one `PRAGMA wal_checkpoint(PASSIVE)` answered, and when. */
+export interface CheckpointObservation {
+    /** ms epoch at which the checkpoint returned. */
+    readonly at: number;
+    /** `log`: frames in the WAL when the checkpoint ran. */
+    readonly walFrames: number;
+    /** `checkpointed`: frames backfilled into the database file. */
+    readonly checkpointedFrames: number;
 }
-export interface CheckpointDecisionInput extends WalIndexCounters {
-    readonly sinceLastRunMs: number;
+/**
+ * Frames appended to the WAL between two checkpoints.
+ *
+ * When the previous checkpoint backfilled EVERYTHING, the next writer restarts
+ * the WAL from frame 1, so every frame now in it is new. When it did not (a
+ * reader pinned a snapshot), the WAL kept growing and the difference is what
+ * was added — unless it shrank, which only a restart can do.
+ *
+ * An IDLE WAL is the exception to "complete means restarted": the WAL restarts
+ * only at the next write, so a fully checkpointed WAL nobody writes answers
+ * the same `log == checkpointed` pass after pass. Identical answers after a
+ * complete checkpoint are therefore 0 appended, not the whole WAL again —
+ * otherwise an idle node would be scheduled at the poll interval forever and
+ * every summary would count the same frames once per pass. (A restart that
+ * appended exactly as many frames as the previous cycle is read as idle too;
+ * it is scheduled at the max delay, which is the bounded case anyway.)
+ *
+ * The one remaining ambiguity — a complete checkpoint followed by writes the
+ * writer could NOT restart the WAL for — counts old frames as new, which
+ * over-estimates the rate and checkpoints EARLY: the safe direction. `-1`
+ * (not a WAL database, or a busy pass) reads as 0.
+ */
+export declare function framesAppendedBetween(previous: CheckpointObservation, current: CheckpointObservation): number;
+/**
+ * What the worker "saw" before its first checkpoint: nothing, at the moment it
+ * started. Against it, the first checkpoint counts every frame then in the WAL
+ * as appended since the start — which over-estimates the rate when the WAL
+ * held older frames, and so schedules the second checkpoint EARLY: the safe
+ * direction, and the second one measures the real rate.
+ */
+export declare function workerStartObservation(at: number): CheckpointObservation;
+export type CheckpointReason = 'first' | 'scheduled';
+export interface CheckpointPlan {
+    /** Frames appended since the previous checkpoint (or the worker's start). */
+    readonly appendedFrames: number;
+    /** How long until the next checkpoint, in ms. */
+    readonly nextDelayMs: number;
 }
-export type CheckpointReason = 'threshold' | 'interval' | 'unknown-interval' | 'below-threshold' | 'unknown-below-interval' | 'nothing-pending';
-export interface CheckpointDecision {
-    readonly run: boolean;
-    readonly reason: CheckpointReason;
-    readonly pendingFrames: number | null;
+export interface CheckpointPlanInput {
+    readonly previous: CheckpointObservation;
+    readonly current: CheckpointObservation;
+    readonly minDelayMs: number;
+    readonly maxDelayMs: number;
 }
-/** Should the worker run `wal_checkpoint(PASSIVE)` now? */
-export declare function decideCheckpoint(input: CheckpointDecisionInput): CheckpointDecision;
-/** Bytes needed to read both fields. */
-export declare const WAL_INDEX_HEADER_READ_BYTES: number;
 /**
- * `mxFrame` and `nBackfill` from the first {@link WAL_INDEX_HEADER_READ_BYTES}
- * of the `-shm` file, or `null` when the buffer is short or the two header
- * copies disagree (a writer was updating them — SQLite's own readers retry on
- * exactly that comparison; this caller simply waits for the next poll).
+ * When to run the next checkpoint: the moment the measured rate says
+ * {@link WAL_CHECKPOINT_THRESHOLD_FRAMES} more frames will be pending,
+ * clamped to `[minDelayMs, maxDelayMs]`. Nothing appended since the last one
+ * is `maxDelayMs`.
  */
-export declare function parseWalIndexHeader(buffer: Buffer): WalIndexCounters | null;
+export declare function nextCheckpointPlan(input: CheckpointPlanInput): CheckpointPlan;
 /** What the worker tells the parent after one checkpoint. */
 export interface CheckpointReport {
     readonly kind: 'checkpointed';
     readonly reason: CheckpointReason;
-    readonly pendingFrames: number | null;
+    /** Frames appended since the previous checkpoint (or the worker's start). */
+    readonly appendedFrames: number;
+    /** When the worker will checkpoint next, in ms. */
+    readonly nextDelayMs: number;
     /** `PRAGMA wal_checkpoint` row: frames in the WAL, frames now backfilled, busy flag. */
     readonly walFrames: number;
     readonly checkpointedFrames: number;
@@ -108,7 +186,10 @@ export interface WorkerStop {
 /** What the worker is started with. */
 export interface WalCheckpointWorkerData {
     readonly dbPath: string;
+    /** Shortest gap between two checkpoints. */
     readonly pollMs: number;
+    /** Longest gap between two checkpoints. */
+    readonly maxDelayMs: number;
 }
 /** Narrow a message off the worker port without a cast. */
 export declare function isWorkerMessage(value: unknown): value is WorkerMessage;

package/dist/builtins/sqlite-storage/wal-checkpointer.d.ts

@@ -10,6 +10,10 @@ export interface WalCheckpointStats {
     readonly maxMs: number;
     readonly totalMs: number;
     readonly busy: number;
+    /** Passes that folded more than `WAL_CHECKPOINT_LARGE_PASS_FRAMES` appended frames. */
+    readonly large: number;
+    /** The most appended frames one pass found. */
+    readonly maxAppended: number;
 }
 /**
  * The members of a `Worker` this class touches. Structural, so the unit spec
@@ -35,6 +39,7 @@ export interface WalCheckpointerOptions {
     readonly dbPath: string;
     readonly logger: IScopedLogger;
     readonly pollMs?: number;
+    readonly maxDelayMs?: number;
     readonly slowMs?: number;
     readonly summaryIntervalMs?: number;
     /** Overrides the built entry — a spec points this at the TypeScript source. */
@@ -47,6 +52,7 @@ export declare class WalCheckpointer {
     private readonly dbPath;
     private readonly logger;
     private readonly pollMs;
+    private readonly maxDelayMs;
     private readonly slowMs;
     private readonly summaryIntervalMs;
     private readonly spawn;

package/dist/builtins/system-backup/system-backup.service.d.ts

@@ -160,20 +160,6 @@ export declare class SystemBackupService {
         signal?: AbortSignal;
         onArchiveBytes?: (bytesWritten: number) => void;
     }): Promise<CreateArchiveResult>;
-    /**
-     * Best-effort `wal_checkpoint(TRUNCATE)` on every live SQLite database
-     * under the locations about to be archived. Discovers a DB by its
-     * `-wal` sidecar (only WAL-mode DBs have one, and only those need
-     * folding), opens a short-lived second connection — SQLite permits
-     * concurrent connections, and a checkpoint is a supported concurrent
-     * operation against the hub's live writer — checkpoints, and closes.
-     *
-     * Every failure is swallowed: a `SQLITE_BUSY`, a locked file, a
-     * missing native binding, or a non-DB `.db` file must not fail the
-     * backup. A residual WAL still restores correctly; the checkpoint is a
-     * consistency *improvement*, not a precondition.
-     */
-    private checkpointDatabasesUnder;
     /**
      * without extracting payload files. Streams the tar.gz, parses the
      * one entry we care about, then aborts.
@@ -213,9 +199,8 @@ export declare class SystemBackupService {
     private getRestoreMarkerPath;
     /**
      * Absolute-path form of {@link isExcludedFromBackup}, anchored on
-     * this service's dataDir. Shared by the manifest walk, the location
-     * stats and the WAL-checkpoint scan so all three agree with the tar
-     * filter about what a backup contains.
+     * this service's dataDir. Shared by the manifest walk and the location
+     * stats so both agree with the tar filter about what a backup contains.
      */
     private exclusionPredicate;
 }

package/dist/wal-checkpoint-policy-BahrTtyD.mjs

@@ -0,0 +1,186 @@
+//#region src/builtins/sqlite-storage/wal-checkpoint-policy.ts
+/**
+* When the checkpoint worker folds the WAL — the judgement, pure.
+*
+* ## Why a worker checkpoints at all
+*
+* `hub/sqlite-settings` is one JS thread with a synchronous binding, and every
+* configuration read in the cluster queues behind whatever statement it is
+* inside. With `journal_mode = WAL` and the build default `synchronous =
+* NORMAL`, an ordinary commit is an append to the WAL with NO fsync. The
+* fsyncs — the only thing in a one-row write that can take seconds — happen
+* at the CHECKPOINT: the WAL is synced before the pages are copied, the
+* database file after. And SQLite runs the auto-checkpoint (1000 pages)
+* INSIDE the commit of whichever writer crosses the threshold.
+*
+* Measured on the hub, 2026-09-11 10:45–10:55 CEST, from outside the process
+* (`/proc/<pid>/syscall` at 10 Hz + the wal-index header at 1 Hz, D452): the
+* WAL refilled at ~54 frames/s, the auto-checkpoint fired every 12–25 s (42
+* in 9.5 min), and every D-state run on the settings thread that sat in a
+* syscall sat in `fsync` (74), each within ±2 s of a checkpoint event —
+* 12.6 s of the 569 s window, all of it inside writers' commits. In the two
+* saturated bursts earlier that morning (08:35–08:40, 09:30–09:39) the same
+* fsync took 1–10 s, once per checkpoint, and the profiler filed each as a
+* slow `set`. `synchronous` was never the lever: it was already NORMAL, and
+* `sqlite-pragmas.ts` had said so since 2026-08-08.
+*
+* So the checkpoint runs on a worker thread, over its own connection. The
+* settings thread's commits stay appends. What stays on the settings thread
+* is the WAL-header sync SQLite performs when a WAL is reused after a
+* completed checkpoint — one small fsync per cycle — and that residual is
+* named here so nobody reads "no fsync on the settings thread" into this.
+*
+* ## The rule this file reproduces
+*
+* The auto-checkpoint's own rule: fold when 1000 frames are pending. The
+* point of moving the checkpoint is to change WHO waits on the disk, not how
+* often the disk is asked to sync — a worker that folded every second would
+* multiply the fsync count on a drive the media plane already saturates.
+*
+* ## How the worker knows how much is pending — and how it must NOT learn it
+*
+* Until 2026-09-29 the worker read the wal-index header straight out of the
+* `-shm` file, once a second, with `openSync` / `readSync` / `closeSync`. That
+* `closeSync` was the SIGBUS of D468 (corrected by D679): on POSIX, closing
+* ANY descriptor of a file drops EVERY fcntl lock the process holds on that
+* file — including the shared lock on `-shm` byte 128 (the "DMS" lock) that
+* SQLite takes for the life of a connection and that tells every OTHER
+* process "a live connection is using this wal-index, do not rebuild it". With
+* the lock gone, the next process to open the database believed it was
+* first, truncated and re-initialised the `-shm` under the runner's mappings,
+* and the runner's next write past a 32 KiB wal-index region hit a page
+* beyond end-of-file.
+*
+* So the worker never touches a SQLite file except through its connection.
+* What it knows about the WAL it learns from the checkpoint it just ran:
+* `PRAGMA wal_checkpoint(PASSIVE)` answers `log` (frames in the WAL) and
+* `checkpointed` (frames now backfilled). Two consecutive answers give the
+* frames appended between them, hence a rate, hence WHEN the next 1000 frames
+* will have accumulated. The next checkpoint is scheduled for then —
+* {@link nextCheckpointPlan} — clamped between the worker's poll interval and
+* {@link WAL_CHECKPOINT_MAX_DELAY_MS}. A PASSIVE with nothing to fold performs
+* no fsync (the copy and both syncs sit behind `nBackfill < mxFrame` in
+* `wal.c`), so the clamp costs a quiet database nothing, and it bounds how
+* long a burst that follows a quiet spell goes unseen.
+*/
+/** The engine's own `wal_autocheckpoint` default, in frames. Reproduced, not changed. */
+var WAL_CHECKPOINT_THRESHOLD_FRAMES = 1e3;
+/**
+* Longest the worker waits between two checkpoints, in ms, whatever the
+* measured rate says. It is the bound on how late a burst after a steady or
+* quiet spell is noticed, and it is sized against the engine's own fallback
+* (`SQLITE_WAL_AUTOCHECKPOINT_BOUND_PAGES` = 10 000 frames), which runs INSIDE
+* a settings-thread commit — the stall D452 moved off that thread. No burst
+* rate has been measured on the hub (D452's 54 frames/s is the steady rate),
+* so the design point is 1 000 frames/s, ~18× steady: 8 s of it is 8 000
+* frames, under the fallback, so the worker looks before the engine has to.
+* A pass that finds more than {@link WAL_CHECKPOINT_LARGE_PASS_FRAMES} is
+* reported so this number can be tuned from the field.
+*
+* The cost, stated against D452: at the steady 54 frames/s the threshold
+* would fold every ~18.5 s; this clamp folds every 8 s, ~2.3× the fsync pairs
+* (≈ 432 frames per fold instead of 1 000). They are paid on the WORKER, a
+* thread nobody waits on — the settings thread's commits stay appends. A pass
+* with nothing pending does no fsync at all.
+*/
+var WAL_CHECKPOINT_MAX_DELAY_MS = 8e3;
+/**
+* A pass that folded more than this many appended frames is reported (WARN,
+* sampled: the first of each summary window, the rest counted). Half the
+* engine's fallback bound: a gap that let this much accumulate was within 2×
+* of handing the checkpoint back to the settings thread.
+*/
+var WAL_CHECKPOINT_LARGE_PASS_FRAMES = 5e3;
+/** Shortest gap between two checkpoints, in ms — the worker's poll interval. */
+var WAL_CHECKPOINT_POLL_MS = 1e3;
+/**
+* A checkpoint that took this long is reported at WARN with its numbers.
+* Matched to `SQLITE_SLOW_CALL_MS`: it is the same "the disk held us" event
+* the profiler used to file as a slow `set`, now on the thread that paid it.
+*/
+var WAL_CHECKPOINT_SLOW_MS = 1e3;
+/**
+* Frames appended to the WAL between two checkpoints.
+*
+* When the previous checkpoint backfilled EVERYTHING, the next writer restarts
+* the WAL from frame 1, so every frame now in it is new. When it did not (a
+* reader pinned a snapshot), the WAL kept growing and the difference is what
+* was added — unless it shrank, which only a restart can do.
+*
+* An IDLE WAL is the exception to "complete means restarted": the WAL restarts
+* only at the next write, so a fully checkpointed WAL nobody writes answers
+* the same `log == checkpointed` pass after pass. Identical answers after a
+* complete checkpoint are therefore 0 appended, not the whole WAL again —
+* otherwise an idle node would be scheduled at the poll interval forever and
+* every summary would count the same frames once per pass. (A restart that
+* appended exactly as many frames as the previous cycle is read as idle too;
+* it is scheduled at the max delay, which is the bounded case anyway.)
+*
+* The one remaining ambiguity — a complete checkpoint followed by writes the
+* writer could NOT restart the WAL for — counts old frames as new, which
+* over-estimates the rate and checkpoints EARLY: the safe direction. `-1`
+* (not a WAL database, or a busy pass) reads as 0.
+*/
+function framesAppendedBetween(previous, current) {
+	const prevWal = Math.max(0, previous.walFrames);
+	const prevDone = Math.max(0, previous.checkpointedFrames);
+	const curWal = Math.max(0, current.walFrames);
+	const curDone = Math.max(0, current.checkpointedFrames);
+	if (prevDone >= prevWal) {
+		if (curWal === prevWal && curDone === prevDone) return 0;
+		return curWal;
+	}
+	return curWal >= prevWal ? curWal - prevWal : curWal;
+}
+/**
+* What the worker "saw" before its first checkpoint: nothing, at the moment it
+* started. Against it, the first checkpoint counts every frame then in the WAL
+* as appended since the start — which over-estimates the rate when the WAL
+* held older frames, and so schedules the second checkpoint EARLY: the safe
+* direction, and the second one measures the real rate.
+*/
+function workerStartObservation(at) {
+	return {
+		at,
+		walFrames: 0,
+		checkpointedFrames: 0
+	};
+}
+/**
+* When to run the next checkpoint: the moment the measured rate says
+* {@link WAL_CHECKPOINT_THRESHOLD_FRAMES} more frames will be pending,
+* clamped to `[minDelayMs, maxDelayMs]`. Nothing appended since the last one
+* is `maxDelayMs`.
+*/
+function nextCheckpointPlan(input) {
+	const { previous, current, minDelayMs, maxDelayMs } = input;
+	const appendedFrames = framesAppendedBetween(previous, current);
+	const elapsedMs = Math.max(1, current.at - previous.at);
+	if (appendedFrames === 0) return {
+		appendedFrames,
+		nextDelayMs: maxDelayMs
+	};
+	const untilThresholdMs = WAL_CHECKPOINT_THRESHOLD_FRAMES / (appendedFrames / elapsedMs);
+	return {
+		appendedFrames,
+		nextDelayMs: Math.round(Math.min(maxDelayMs, Math.max(minDelayMs, untilThresholdMs)))
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Narrow a message off the worker port without a cast. */
+function isWorkerMessage(value) {
+	if (!isRecord(value)) return false;
+	switch (value["kind"]) {
+		case "ready": return true;
+		case "failed": return typeof value["error"] === "string";
+		case "checkpointed": return (value["reason"] === "first" || value["reason"] === "scheduled") && typeof value["appendedFrames"] === "number" && typeof value["nextDelayMs"] === "number" && typeof value["walFrames"] === "number" && typeof value["checkpointedFrames"] === "number" && typeof value["busy"] === "boolean" && typeof value["ms"] === "number";
+		default: return false;
+	}
+}
+function isWorkerStop(value) {
+	return isRecord(value) && value["kind"] === "stop";
+}
+//#endregion
+export { isWorkerMessage as a, workerStartObservation as c, WAL_CHECKPOINT_SLOW_MS as i, WAL_CHECKPOINT_MAX_DELAY_MS as n, isWorkerStop as o, WAL_CHECKPOINT_POLL_MS as r, nextCheckpointPlan as s, WAL_CHECKPOINT_LARGE_PASS_FRAMES as t };