cursedbelt-server 1.1.0 → 2.1.0

package/dist/server/sync/timer.d.ts

@@ -1,20 +1,63 @@
 /**
- * The in-process dialer loop — vault's `syncTimer` generalized. Runs on the dialing
- * half only; a failure NEVER takes the host daemon down (an unsynced instance still
- * serves and still accepts writes — that is the point of two independently-writable
- * instances). The timer is `unref`'d so it never holds the process open.
- *
- * The peer is re-resolved on EVERY tick, so linking (or revoking) a peer takes
- * effect without a restart. The "Sync now" fast lane polls the receiver's request
- * stamp every ~20s while healthy, so a button press on the far side means seconds,
- * not "sometime in the next interval".
+ * The in-process sync loop. Runs on the dialing half only; a failure NEVER takes
+ * the host daemon down (an unsynced instance still serves and still accepts writes
+ * — that is the point of two independently-writable instances). The timer is
+ * `unref`'d so it never holds the process open.
+ *
+ * ── 🔴 This loop does not poll, and it may never be made to again ────────────────
+ *
+ * Until 2026-09-15 this file was a dialer twice over: a `GET /requested` probe at a
+ * peer every 20 s while healthy (`REQUEST_POLL_MS`), and a full reconciliation every
+ * 5 minutes (`DEFAULT_LOOP.intervalMs`) whether or not either side had news. The
+ * owner ruled both out — *"There should be no polling in cb unless you can make some
+ * good case for it that beats the api option"* — and the case against was asked for
+ * and not found. Measured in `vault`: the 20 s probe alone was **68 % of that app's
+ * entire traffic, one request every 22 seconds, for an app with one user.**
+ *
+ * Both are gone. Every wake-up this loop books now carries a {@link WakeReason}, and
+ * that union is deliberately closed with no periodic member — there is no value you
+ * can pass to {@link schedule} that means "again in a while". That makes the poll
+ * unrepresentable rather than merely discouraged, which matters because
+ * `REQUEST_POLL_MS` did not survive as a habit; it survived as **exported public
+ * API**, and the next consumer to import it would have made its removal a breaking
+ * change instead of an edit.
+ *
+ * What replaced each half:
+ *
+ *   · **Mac → peer** is a PUSH. `markDirty()` after a local write books one
+ *     debounced run: the side that has news says so, which is what "sync now"
+ *     should always have been.
+ *   · **peer → Mac** is `./signal` — the dialing half holds one long-lived stream
+ *     open and the receiver writes a frame when its log grows. The Mac is still
+ *     purely a client: it dials OUT, listens on nothing, and no timer fires.
+ *
+ * 🔴 **`markDirty()` is now REQUIRED wiring, not an optimization.** With the steady
+ * interval gone it is the only thing that pushes a local write. A consumer that
+ * takes the handle and drops `markDirty` (which `apps/vault` did while the interval
+ * still covered for it) will sit clean and silent forever.
+ *
+ * The peer is re-resolved on every run, so revoking a link takes effect without a
+ * restart. Linking a NEW peer is a user action and is noticed at the next
+ * `syncNow()` / `markDirty()` rather than by a timer that was watching for it —
+ * call `syncNow()` after a link and it is immediate.
  */
 import { type SyncLoopConfig } from "./planner";
 import type { SyncStatusReporter } from "./status";
 import type { SyncSummary } from "./types";
-export declare const REQUEST_POLL_MS = 20000;
+/**
+ * 🔴 Every reason this loop is allowed to wake up. There is deliberately no
+ * `"interval"` / `"poll"` member, and adding one is the change this whole file
+ * exists to refuse.
+ *
+ *   · `boot`   — one catch-up run at start.
+ *   · `dirty`  — local ops are waiting to be pushed (debounced).
+ *   · `forced` — `syncNow()`, or a frame off `./signal` saying the peer has news.
+ *   · `retry`  — the last attempt failed. Runs only while disconnected, never
+ *                against a healthy peer; that is a reconnect backoff, not a poll.
+ */
+export type WakeReason = "boot" | "dirty" | "forced" | "retry";
 export interface SyncTimerDeps {
-    /** Re-read every tick: null = not linked (quiet no-op, re-checked next tick). */
+    /** Re-read on every run: null = not linked (quiet no-op). */
     resolvePeer: () => {
         basePath: string;
         token: string;
@@ -26,14 +69,8 @@ export interface SyncTimerDeps {
     }) => Promise<SyncSummary>;
     /** The local op-log head — a head beyond the last synced one marks dirty. */
     head: () => number;
-    /** Ask the peer whether its "Sync now" was pressed; null on any failure. */
-    checkRequest?: (peer: {
-        basePath: string;
-        token: string;
-    }) => Promise<number | null>;
     status?: SyncStatusReporter;
     loop?: SyncLoopConfig;
-    requestPollMs?: number;
     now?: () => number;
     setTimer?: (fn: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
@@ -44,9 +81,16 @@ export interface SyncTimerDeps {
 }
 export interface SyncTimerHandle {
     stop(): void;
-    /** Run the next tick immediately (the "Sync now" button on the dialing half). */
+    /**
+     * Run now. The "Sync now" button on the dialing half, and the handler for a
+     * `./signal` frame — both are "something has news", which is a push.
+     */
     syncNow(): void;
-    /** Mark local writes pending (call after any local op) — debounces a burst. */
+    /**
+     * Mark local writes pending — call after any local op. 🔴 Required wiring: with
+     * no steady interval this is what pushes a local write. A burst coalesces into
+     * one run via the planner's debounce.
+     */
     markDirty(): void;
 }
 export declare function startSyncTimer(deps: SyncTimerDeps): SyncTimerHandle;

package/dist/server/sync/timer.js

@@ -1,16 +1,52 @@
 /**
- * The in-process dialer loop — vault's `syncTimer` generalized. Runs on the dialing
- * half only; a failure NEVER takes the host daemon down (an unsynced instance still
- * serves and still accepts writes — that is the point of two independently-writable
- * instances). The timer is `unref`'d so it never holds the process open.
+ * The in-process sync loop. Runs on the dialing half only; a failure NEVER takes
+ * the host daemon down (an unsynced instance still serves and still accepts writes
+ * — that is the point of two independently-writable instances). The timer is
+ * `unref`'d so it never holds the process open.
  *
- * The peer is re-resolved on EVERY tick, so linking (or revoking) a peer takes
- * effect without a restart. The "Sync now" fast lane polls the receiver's request
- * stamp every ~20s while healthy, so a button press on the far side means seconds,
- * not "sometime in the next interval".
+ * ── 🔴 This loop does not poll, and it may never be made to again ────────────────
+ *
+ * Until 2026-09-15 this file was a dialer twice over: a `GET /requested` probe at a
+ * peer every 20 s while healthy (`REQUEST_POLL_MS`), and a full reconciliation every
+ * 5 minutes (`DEFAULT_LOOP.intervalMs`) whether or not either side had news. The
+ * owner ruled both out — *"There should be no polling in cb unless you can make some
+ * good case for it that beats the api option"* — and the case against was asked for
+ * and not found. Measured in `vault`: the 20 s probe alone was **68 % of that app's
+ * entire traffic, one request every 22 seconds, for an app with one user.**
+ *
+ * Both are gone. Every wake-up this loop books now carries a {@link WakeReason}, and
+ * that union is deliberately closed with no periodic member — there is no value you
+ * can pass to {@link schedule} that means "again in a while". That makes the poll
+ * unrepresentable rather than merely discouraged, which matters because
+ * `REQUEST_POLL_MS` did not survive as a habit; it survived as **exported public
+ * API**, and the next consumer to import it would have made its removal a breaking
+ * change instead of an edit.
+ *
+ * What replaced each half:
+ *
+ *   · **Mac → peer** is a PUSH. `markDirty()` after a local write books one
+ *     debounced run: the side that has news says so, which is what "sync now"
+ *     should always have been.
+ *   · **peer → Mac** is `./signal` — the dialing half holds one long-lived stream
+ *     open and the receiver writes a frame when its log grows. The Mac is still
+ *     purely a client: it dials OUT, listens on nothing, and no timer fires.
+ *
+ * 🔴 **`markDirty()` is now REQUIRED wiring, not an optimization.** With the steady
+ * interval gone it is the only thing that pushes a local write. A consumer that
+ * takes the handle and drops `markDirty` (which `apps/vault` did while the interval
+ * still covered for it) will sit clean and silent forever.
+ *
+ * The peer is re-resolved on every run, so revoking a link takes effect without a
+ * restart. Linking a NEW peer is a user action and is noticed at the next
+ * `syncNow()` / `markDirty()` rather than by a timer that was watching for it —
+ * call `syncNow()` after a link and it is immediate.
  */
 import { isUnreachable, DEFAULT_LOOP, planNextSync, } from "./planner";
-export const REQUEST_POLL_MS = 20_000;
+/**
+ * One reconciliation shortly after start: catch up on whatever happened while this
+ * process was down. A single shot at boot, not a cadence — the same catch-up a push
+ * model needs anyway.
+ */
 const KICKOFF_MS = 5_000;
 function defaultPeerLabel(basePath) {
     try {
@@ -29,46 +65,63 @@ export function startSyncTimer(deps) {
     const warn = deps.warn ?? ((m) => console.error(m));
     const status = deps.status;
     const peerLabel = deps.peerLabel ?? defaultPeerLabel;
-    const requestPollMs = deps.requestPollMs ?? REQUEST_POLL_MS;
     status?.update({ enabled: true, role: "dialer" });
     const state = { lastAttempt: 0, consecutiveFailures: 0, dirtySince: null };
     let syncedHead = deps.head();
     let stopped = false;
     let handle = null;
     let reportedUnreachable = false;
-    let forceRun = false;
-    let handledRequestAt = 0;
-    let probing = false;
+    /**
+     * 🔴 Starts TRUE: the boot catch-up is a forced run, not a scheduled one.
+     *
+     * It used to fall out of the planner for free — `lastAttempt: 0` plus a steady
+     * `intervalMs` made the first tick always due. With no interval left, a clean
+     * healthy state plans nothing, so the one run this loop genuinely owes at
+     * startup has to be asked for explicitly. It has a reason: this process may have
+     * missed ops while it was down, and catching up is exactly what a push model
+     * does on reconnect.
+     */
+    let forceRun = true;
     let inFlight = false;
-    const schedule = (ms) => {
+    /** Why the currently-booked wake exists, or null when the loop is quiet. */
+    let bookedFor = null;
+    /**
+     * Book the next wake-up. 🔴 The `reason` is not decoration — it is the type-level
+     * guard: {@link WakeReason} has no periodic member, so there is no way to spell
+     * "wake again in `intervalMs`" through this function. It is also read back by
+     * {@link SyncTimerHandle.markDirty}, which must not push an imminent forced run
+     * out to a debounce.
+     */
+    const schedule = (reason, ms) => {
         if (stopped)
             return;
         if (handle !== null)
             clearTimer(handle);
         handle = setTimer(tick, ms);
         handle?.unref?.();
+        bookedFor = reason;
     };
-    const sleepFor = (waitMs) => {
-        const healthy = state.consecutiveFailures === 0 && requestPollMs > 0;
-        return Math.max(1, healthy ? Math.min(waitMs, requestPollMs) : waitMs);
+    /** Nothing to push, nothing to retry: cancel any pending wake and go quiet. */
+    const idle = () => {
+        if (handle !== null)
+            clearTimer(handle);
+        handle = null;
+        bookedFor = null;
     };
-    const probeRequest = (peer) => {
-        if (probing || requestPollMs === 0 || !deps.checkRequest)
+    /** Apply the planner's verdict — the ONE place a wake-up is booked or declined. */
+    const bookNext = () => {
+        if (stopped)
             return;
-        probing = true;
-        void deps
-            .checkRequest(peer)
-            .then((requestedAt) => {
-            if (stopped || requestedAt === null || requestedAt <= handledRequestAt)
-                return;
-            handledRequestAt = requestedAt;
-            log("[sync] sync requested from the peer — running now.");
-            forceRun = true;
-            schedule(1);
-        })
-            .finally(() => {
-            probing = false;
-        });
+        if (forceRun) {
+            schedule("forced", 1);
+            return;
+        }
+        const plan = planNextSync(state, now(), loop);
+        if (plan.waitMs === null || plan.reason === null) {
+            idle();
+            return;
+        }
+        schedule(plan.reason, Math.max(1, plan.waitMs));
     };
     const tick = () => {
         if (stopped)
@@ -84,15 +137,16 @@ export function startSyncTimer(deps) {
             pending: Math.max(0, head - syncedHead),
         });
         if (peer === null) {
-            schedule(loop.intervalMs);
+            // Not linked. Nothing to dial and nothing to wait for — `syncNow()` or the
+            // next local write re-checks. A re-check timer here would be a poll at a
+            // peer that does not exist yet.
+            forceRun = false;
+            idle();
             return;
         }
         const plan = planNextSync(state, now(), loop);
         if (!plan.runNow && !forceRun) {
-            const linkedAndHealthy = state.consecutiveFailures === 0 && requestPollMs > 0;
-            schedule(sleepFor(plan.waitMs));
-            if (linkedAndHealthy)
-                probeRequest(peer);
+            bookNext();
             return;
         }
         forceRun = false;
@@ -140,31 +194,36 @@ export function startSyncTimer(deps) {
         })
             .finally(() => {
             inFlight = false;
-            if (forceRun)
-                schedule(1);
-            else
-                schedule(sleepFor(Math.max(1_000, planNextSync(state, now(), loop).waitMs)));
+            // A local write that landed mid-run is news the planner must see.
+            if (deps.head() > syncedHead && state.dirtySince === null)
+                state.dirtySince = now();
+            bookNext();
         });
     };
-    schedule(KICKOFF_MS);
+    schedule("boot", KICKOFF_MS);
     return {
         stop: () => {
             stopped = true;
             if (handle !== null)
                 clearTimer(handle);
+            handle = null;
         },
         syncNow: () => {
             if (stopped)
                 return;
             forceRun = true;
-            schedule(1);
+            schedule("forced", 1);
         },
         markDirty: () => {
             if (stopped)
                 return;
             if (state.dirtySince === null)
                 state.dirtySince = now();
-            schedule(1);
+            // A forced run is already due in ~1ms and will push these ops; re-booking
+            // would replace it with a 3s debounce and make "Sync now" slower.
+            if (bookedFor === "forced")
+                return;
+            bookNext();
         },
     };
 }

package/dist/server/sync/types.d.ts

@@ -67,8 +67,6 @@ export interface RemoteApi {
         ops: SyncOp[];
         peerHas: number;
     }): Promise<ApplyReport>;
-    /** The receiver's "someone pressed Sync now here" stamp; null when unsupported. */
-    requestedAt?(): Promise<number | null>;
 }
 /** Context the applier gets per batch — vault's concurrency bound. */
 export interface ApplyContext {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "1.1.0",
+	"version": "2.1.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -48,6 +48,24 @@
 			"source": "./src/server/context.ts",
 			"import": "./dist/server/context.js"
 		},
+		"./bench": {
+			"types": "./dist/server/bench/index.d.ts",
+			"bun": "./src/server/bench/index.ts",
+			"source": "./src/server/bench/index.ts",
+			"import": "./dist/server/bench/index.js"
+		},
+		"./d1": {
+			"types": "./dist/server/d1/index.d.ts",
+			"bun": "./src/server/d1/index.ts",
+			"source": "./src/server/d1/index.ts",
+			"import": "./dist/server/d1/index.js"
+		},
+		"./d1/testing": {
+			"types": "./dist/server/d1/fakeD1.d.ts",
+			"bun": "./src/server/d1/fakeD1.ts",
+			"source": "./src/server/d1/fakeD1.ts",
+			"import": "./dist/server/d1/fakeD1.js"
+		},
 		"./dropzone": {
 			"types": "./dist/server/dropzone/index.d.ts",
 			"bun": "./src/server/dropzone/index.ts",
@@ -182,8 +200,8 @@
 		}
 	},
 	"dependencies": {
-		"cursedbelt-core": "^1.0.0",
-		"cwip": "^3.0.2",
+		"cursedbelt-core": "^1.2.0",
+		"cwip": "^4.1.0",
 		"jose": "^6.2.3"
 	},
 	"peerDependencies": {

package/src/leafSubpathsImportNothing.spec.ts

@@ -156,8 +156,10 @@ const sourceOf = (subpath: string): string => {
  * Resolution here is therefore explicit rather than inherited. The redirected root is
  * used when it lies outside the repo (the normal case — the runner always sets
  * `$FORGE_STATE`, and the preload's sweep then cleans up after a killed run). When it
- * does not, this hops to `$HOME`, which `resolveTestTmpRoot` refuses for the general
- * default and which this check genuinely requires: an isolated root is the whole
+ * does not, this hops to `$FORGE_STATE/test-scratch.noindex` — or, with no generation
+ * in the environment, `~/.code/test-scratch.noindex`, which is where this machine keeps
+ * everything it builds for itself. `resolveTestTmpRoot` refuses `$HOME` for the general
+ * default and this check genuinely requires an isolated root: that isolation is the whole
  * measurement. Stale siblings are swept by mtime, the same way the preload does it,
  * so the hop cannot accumulate.
  */
@@ -175,7 +177,17 @@ const fixtureRoot = (): string => {
         'a check that cannot isolate itself is not a passing check',
     );
   }
-  const outside = `${home}/.${pkg.name}-leaf-fixture.noindex`;
+  // 🔴 Under `$FORGE_STATE`, or under `~/.code` — never a dotted directory of its own in
+  // `$HOME`. Measured 2026-09-17: this hop had left three `~/.cursedbelt*-leaf-fixture.noindex`
+  // trees in the owner's home directory, indistinguishable at a glance from the forty a Mac's
+  // real software puts there, and the sweep below only ever cleaned their INSIDES. A check that
+  // tidies up after itself and still leaves its address behind for ever is the shape this
+  // generation's home-dir rule exists to stop; `tools/check-home-dir.ts` now fails on it.
+  const state = process.env.FORGE_STATE?.trim();
+  const outside =
+    state !== undefined && state !== '' && !`${state}/`.startsWith(REPO_PREFIX)
+      ? `${state}/test-scratch.noindex/${pkg.name}-leaf-fixture`
+      : `${home}/.code/test-scratch.noindex/${pkg.name}-leaf-fixture`;
   try {
     const cutoff = Date.now() - 6 * 60 * 60 * 1000;
     for (const entry of readdirSync(outside)) {