cursedbelt 2.6.1 → 2.8.0

package/src/server/sync/types.ts

@@ -0,0 +1,108 @@
+/**
+ * The wire and store types every consumer of this sync engine shares. The op
+ * envelope is the notes shape — `(origin, originSeq)` gives exactly-once application
+ * with no coordination — and the report is vault's cursor discipline (the reader may
+ * advance exactly to `cursor`, never further) merged with notes' `seen` (a duplicate
+ * is not an error, it is proof the dedupe ledger works).
+ *
+ * ── 🔴 "sync-kit" is a PAST NAME. The engine is `cursedbelt/sync` ────────────
+ * The retired generation published this as `@satellites/sync-kit`. It came across
+ * whole into `apps/vault/src/kit/sync/` when that app graduated, and came here —
+ * `cursedbelt/sync` — on 2026-09-15, before `apps/station` could graduate and fork
+ * it a second time. That is the move this header used to call an open question in
+ * `tasks/`; it is done, and the app-local copies are what is temporary now.
+ *
+ * `@satellites/sync-kit` is NOT installable and never was — it was never published
+ * to npm — and its design plan (`plans/01-sync-kit-adoption-design.md`) belonged to
+ * the retired monorepo and did not come across. Comments in consuming apps still say
+ * "the sync-kit adoption": that is the NAME OF AN EVENT, the 2026-08 change that
+ * moved vault from its own `oplog` table onto this engine's `sync_ops`, and it is
+ * worth keeping because the dual-compat code only makes sense in its light.
+ */
+
+/** One durable mutation in the shared op log. `payload` is app-defined per `kind`. */
+export interface SyncOp {
+	/** This instance's monotonic sequence for the op (assigned by the local log). */
+	seq: number;
+	/** The instance id that BORN the op (stable per instance, never per device). */
+	origin: string;
+	/** The origin's own monotonic counter — `(origin, originSeq)` is the identity. */
+	originSeq: number;
+	/** Wall-clock ms when the op was born. LWW inputs, display, nothing structural. */
+	ts: number;
+	/** App-defined kind, e.g. `doc.set`. The version-negotiation unit. */
+	kind: string;
+	payload: unknown;
+}
+
+/** What applying one batch did. `cursor` is the last seq FULLY applied — a stopped
+ *  batch leaves it just before the failure so the next run resumes there. */
+export interface ApplyReport {
+	/** Ops that changed local state. */
+	applied: number;
+	/** Ops already held (dedupe hit) — counted, never re-applied. */
+	seen: number;
+	/** Concurrent edits reconciled (however the app's applier chose to). */
+	conflicts: number;
+	cursor: number;
+	/** Non-null when the batch stopped early (version skew, deferred ordering…). */
+	error: string | null;
+}
+
+/** The peer info handshake. `opKinds` is the compatibility advertisement — a dialer
+ *  stops BEFORE the first op a peer cannot take (notes' version-skew lesson: sending
+ *  it wedges the push with an error that reads like corruption). */
+export interface PeerInfo {
+	instanceId: string;
+	head: number;
+	opKinds: string[];
+}
+
+/** The transport seam. Pure interface so tests drive the engine against a REAL second
+ *  store mounted in a Hono app — no HTTP mocks (the notes/vault discipline). */
+export interface RemoteApi {
+	info(): Promise<PeerInfo>;
+	pull(
+		after: number,
+		excludeOrigin: string,
+	): Promise<{ ops: SyncOp[]; cursor: number; head: number }>;
+	push(payload: { 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 {
+	/** The peer's stable instance id. */
+	peerId: string;
+	/** Max LOCAL-born seq the peer already holds of OURS — an entity whose newest
+	 *  local op is beyond this AND diverges is a true concurrent edit. */
+	peerReceivedUpTo: number;
+}
+
+/** The app's merge logic for ONE op that passed the dedupe ledger. Return value:
+ *  - `"applied"`   — state changed
+ *  - `"ignored"`   — stale/no-op (still recorded in the ledger, cursor advances)
+ *  - `"conflict"`  — applied with a materialized conflict artifact
+ *  Throw {@link StopBatch} to stop BEFORE this op (cursor stays short of it). */
+export type ApplyOne = (op: SyncOp, ctx: ApplyContext) => "applied" | "ignored" | "conflict";
+
+/** Stop the current batch before the offending op — deferred ordering, a payload this
+ *  build cannot hold yet, anything where "retry after the world changes" is right. */
+export class StopBatch extends Error {
+	constructor(reason: string) {
+		super(reason);
+		this.name = "StopBatch";
+	}
+}
+
+export interface SyncSummary {
+	remoteId: string;
+	pushed: number;
+	pulled: number;
+	conflicts: number;
+	/** Ops the export policy held back (counted, never sent). */
+	held: number;
+	/** Set when the remote runs an older schema and cannot take what comes next. */
+	blockedBy?: string;
+}

package/src/verifyGraph.spec.ts

@@ -0,0 +1,181 @@
+/**
+ * 🔴 The gate got faster on 2026-09-15. This is the file that stops it getting smaller.
+ *
+ * `bun run verify` was `paths && typecheck && demo:check && build && test && e2e` — six
+ * serial links, 142.0s measured end to end on an idle machine, five of them single-threaded
+ * work queued behind each other on a fourteen-core Mac. It is now a dependency graph
+ * (`scripts/verify.ts`) that runs the same stages concurrently.
+ *
+ * Every speed-up of a gate is one edit away from being a deletion of a gate, and the two
+ * look identical in a diff: dropping `e2e` from the graph makes `verify` four times faster
+ * and every test still passes. This generation's third rule is that a repo's gate proves
+ * that repo, so the SET of stages is pinned here, by name, against the chain that existed
+ * before the change. Adding a stage is free; removing one has to argue with this file.
+ *
+ * The literal list below is deliberate duplication. A test that derived the expectation from
+ * `STAGES` would assert that the graph equals itself.
+ */
+import { describe, expect, it } from 'bun:test';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import pkg from '../package.json';
+import { graphFault, jobLimit, ROOT, STAGES, timingTable } from '../scripts/verify';
+
+/**
+ * What `verify` ran before it became a graph, expanded to the leaf scripts.
+ *
+ * `typecheck` was one script running three `tsc` projects serially; it is now three scripts
+ * so they can run at once, and `typecheck` still runs all three for anybody typing it by
+ * hand. `styles` is new — it is the first two steps of `build`, hoisted so that the things
+ * which READ the generated stylesheets can wait on the thing that writes them.
+ */
+const MUST_RUN = [
+	'paths',
+	'typecheck:root',
+	'typecheck:server',
+	'typecheck:specs',
+	'demo:check',
+	'styles',
+	'build',
+	'test',
+	'e2e',
+] as const;
+
+describe('the verify graph', () => {
+	it('still runs every check the serial chain ran', () => {
+		const inGraph = STAGES.map((s) => s.script);
+		const missing = MUST_RUN.filter((script) => !inGraph.includes(script));
+		expect(
+			missing,
+			`\`bun run verify\` no longer runs:\n  ${missing.join('\n  ')}\n` +
+				'A gate that got faster by proving less is not faster. Add the stage back, or — if it ' +
+				'genuinely belongs somewhere else now — say so here and in scripts/verify.ts together.',
+		).toEqual([]);
+	});
+
+	it('names only scripts package.json actually declares', () => {
+		const scripts = pkg.scripts as Record<string, string | undefined>;
+		const undeclared = STAGES.map((s) => s.script).filter((script) => !scripts[script]);
+		expect(undeclared, `verify stages with no script:\n  ${undeclared.join('\n  ')}`).toEqual([]);
+	});
+
+	it('is the thing `bun run verify` actually runs', () => {
+		// Without this the graph can be perfect and unreachable: `verify` could quietly go
+		// back to a chain, and every assertion above would still pass.
+		expect(pkg.scripts.verify).toInclude('scripts/verify.ts');
+	});
+
+	it('has no dangling `needs` and no cycle', () => {
+		expect(graphFault(STAGES)).toBeNull();
+	});
+
+	it('catches a dangling `needs` rather than idling with work left', () => {
+		// The negative control. A typo in `needs` makes a stage that can never become ready,
+		// and a scheduler that simply runs out of ready work would exit 0 having skipped it —
+		// "nothing failed" reported as "everything passed", which is the false green in its
+		// purest form.
+		expect(graphFault([{ script: 'a' }, { script: 'b', needs: ['typo'] }])).toInclude('typo');
+	});
+
+	it('catches a cycle', () => {
+		expect(graphFault([{ script: 'a', needs: ['b'] }, { script: 'b', needs: ['a'] }])).toInclude('cycle');
+	});
+
+	it('catches two stages claiming the same script', () => {
+		expect(graphFault([{ script: 'a' }, { script: 'a' }])).toInclude('same script');
+	});
+});
+
+describe('the two edges the graph rests on', () => {
+	it('keeps everything that reads the generated stylesheets behind `styles`', () => {
+		// `build` regenerates src/styles-static.css and src/styles-utilities.css;
+		// stylesStaticMatches.spec.ts and stylesUtilitiesMatches.spec.ts assert those exact
+		// files are current, and the demo bundle e2e drives is compiled from them. Any of
+		// those three running beside the generators is a writer racing a reader.
+		for (const script of ['build', 'test', 'e2e']) {
+			const stage = STAGES.find((s) => s.script === script);
+			expect(stage?.needs, `\`${script}\` must wait for \`styles\``).toContain('styles');
+		}
+	});
+
+	it('🔴 no spec reads dist/, which is why `build` is a leaf', () => {
+		// The graph runs `build` BESIDE `test` and `e2e` rather than in front of them, and
+		// that is only sound while nothing under test can observe the compiled output. The
+		// build stages into dist.next and swaps, so a reader of `dist/` during a build sees
+		// the previous bytes or — for one `mv` — no directory at all.
+		const offenders: string[] = [];
+		const walk = (dir: string): void => {
+			for (const entry of readdirSync(dir)) {
+				const full = join(dir, entry);
+				if (statSync(full).isDirectory()) {
+					walk(full);
+					continue;
+				}
+				if (!/\.spec\.tsx?$/.test(entry)) continue;
+				// This file states the pattern, so it matches itself — the same self-exemption
+				// `namedSubpathsResolve.spec.ts` needs for the same reason.
+				if (entry === 'verifyGraph.spec.ts') continue;
+				const text = readFileSync(full, 'utf8');
+				// A filesystem read whose path argument mentions dist — not the word in prose,
+				// and not `dist.next` inside buildIsStaged's assertions about the SCRIPT TEXT.
+				if (/(?:readFileSync|readdirSync|existsSync|statSync|Bun\.file|new Glob)\([^)]*['"`][^'"`]*\bdist\b/.test(text)) {
+					offenders.push(full.slice(ROOT.length + 1));
+				}
+			}
+		};
+		walk(resolve(ROOT, 'src'));
+		expect(
+			offenders,
+			`these specs read dist/, so \`build\` is no longer a leaf and the graph is wrong:\n  ${offenders.join('\n  ')}\n` +
+				'Either give them `needs: ["build"]` in scripts/verify.ts, or stop reading dist.',
+		).toEqual([]);
+	});
+});
+
+describe('the job limit', () => {
+	it('defaults to a third of the cores, because a stage is not a process', () => {
+		// e2e alone spawns seven Playwright workers; build spawns two tsc processes. Six
+		// stages is already twenty-odd processes on a machine with fourteen cores.
+		expect(jobLimit({}, 14)).toBe(4);
+		expect(jobLimit({}, 4)).toBe(2);
+		expect(jobLimit({}, 64)).toBe(6);
+	});
+
+	it('honours an explicit override, including 1', () => {
+		// 🔴 `1` is the old serial behaviour, and it must stay reachable without a second
+		// gate script existing for somebody to run instead of this one.
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: '1' }, 14)).toBe(1);
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: '9' }, 14)).toBe(9);
+	});
+
+	it('ignores nonsense rather than running zero stages at a time', () => {
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: 'lots' }, 14)).toBe(4);
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: '0' }, 14)).toBe(4);
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: '-3' }, 14)).toBe(4);
+	});
+});
+
+describe('the timing table', () => {
+	it('reports the overlap, which is the whole point of the change', () => {
+		const table = timingTable(
+			[
+				{ script: 'test', ok: true, ms: 60_000, output: '' },
+				{ script: 'e2e', ok: true, ms: 30_000, output: '' },
+			],
+			60_000,
+		);
+		expect(table).toInclude('1.5× overlap');
+		expect(table).toInclude('test');
+	});
+
+	it('says so plainly when nothing overlapped', () => {
+		const table = timingTable([{ script: 'paths', ok: true, ms: 1_000, output: '' }], 1_000);
+		expect(table).toInclude('No overlap');
+	});
+
+	it('shows a skipped stage as skipped, never as passing', () => {
+		const table = timingTable([{ script: 'e2e', ok: false, ms: 0, output: '', skipped: true }], 1_000);
+		expect(table).toInclude('skipped');
+		expect(table).not.toInclude(' ok');
+	});
+});