${name}
${title}
${copy}
SPOOL profiles the source, infers a safe target schema, builds deterministic transforms, dry-runs them, executes in a Worker, groups bad rows, recovers from checkpoints, and exposes only the agent tools that make sense right now.
Autopilot is not a script that clicks the old UI. It is a kernel-level orchestration path that plans, dry-runs and starts the migration through the same deterministic commands used everywhere else.
Run Autopilot ${arrowIcon()}Add source↓Choose Database-ready↓Run Autopilot↓No action required${copy}
SPOOL only advances when the target and transform plan satisfy deterministic safety rules. Strong parseability evidence can promote a dirty string field to a type while rows that fail that contract are rejected into quality groups.
Whitespace trim, normalized identifiers, obvious booleans, strongly parseable numbers and ISO dates.
Name collisions, multiple equally plausible interpretations, or a plan that cannot satisfy the typed target contract.
target field: monthly_fee\ninferred type: number\nconfidence: 0.9900\nevidence: 99 / 100 sampled values parse\ndecision: automatic
The application stopped before entering the migration workflow instead of leaving you on a permanent loading screen.
${esc(message)}The application stopped before entering the migration workflow instead of leaving you on a permanent loading screen.
${esc(message)}The Browser Studio prepares and validates data in-browser. The Local Runner is the production mutation path: bounded-memory streaming of approved UTF-8 filesystem CSV migrations into an existing ordinary SQLite table on the customer-controlled machine, with a 256 MiB default source ceiling.
+The Browser Studio prepares and validates data in-browser. The released Local Runner is the customer-local mutation path: bounded-memory streaming of approved UTF-8 filesystem CSV migrations into an existing ordinary SQLite table on the customer-controlled machine, with a 256 MiB default source ceiling.
Node.js 22+ is required. Browser Studio stays capped at 50 MiB; for production SQLite mutation or larger CSV files use this customer-local runner. The Local Runner uses bounded-memory streaming with a 256 MiB default source ceiling. It keeps a durable content-bound snapshot on local disk for approval/recovery, re-scans that snapshot on restart, and cleans it after VERIFIED completion. Budget disk space for the snapshot plus SQLite/WAL growth. The release remains private on the npm registry; install directly from the versioned GitHub source or release artifact.
# Preferred v1.1.1 install — no npm-registry publication required. ++ BEFORE INSTALLINGFor a SQLite database operator
First prepare the CSV and an existing compatible SQLite table. Then install SPOOL locally, create the documented migration request, inspect and dry-run it, authorize the exact plan, execute, verify and save the receipt. The published capability matrix classifies SQLite target support as experimental because sustained-load qualification is still missing; do not interpret a release download as proof of unrestricted enterprise readiness.
Return to the guided setup →+cd spool && npm ci && npm run check && npm run pack:verify ADVANCED · INSTALL + RUN ON YOUR DEVICEInstall the versioned CLI, then inspect, approve, run and verify.
Node.js 22+ is required. Browser Studio stays capped at 50 MiB; for production SQLite mutation or larger CSV files use this customer-local runner. The Local Runner uses bounded-memory streaming with a 256 MiB default source ceiling. It keeps a durable content-bound snapshot on local disk for approval/recovery, re-scans that snapshot on restart, and cleans it after VERIFIED completion. Budget disk space for the snapshot plus SQLite/WAL growth. The release remains private on the npm registry; install directly from the versioned GitHub source or release artifact.
Show command-line installation and execution steps
# Preferred v1.1.1 install — no npm-registry publication required. npm install -g github:dharan1007/spool#v1.1.1 spool --help @@ -102,7 +101,7 @@ spool receipt --migration-id mig_customers_001 --source-root ./data --target-roo # Source-verification fallback: git clone --branch v1.1.1 https://github.com/dharan1007/spool.git -cd spool && npm ci && npm run check && npm run pack:verify
Choose the outcome first. SPOOL will show the correct interface, what runs on your device, and the evidence you will receive. You do not need to understand API responses to choose a path.
You have a CSV, and want a validated CSV or JSON output. Add the file in your browser, choose a cleanup outcome, run Autopilot, review rejected rows and export. Nothing is sent to a SPOOL data server.
Input: CSV up to 50 MiB · Result: browser-local output, not a live database write.
Open the CSV Studio →You have a CSV and an existing SQLite database. Install the released local runner on the computer holding the data. An operator reviews source and destination, runs a dry-run, approves the exact operation, executes it and examines the receipt.
Default CSV ceiling: 256 MiB · Insert-only, ordinary SQLite targets · Command line and setup required.
See the local setup →Your application can invoke SPOOL through its local CLI or an authenticated loopback bridge. A developer installs and runs the command service on the customer-controlled machine. This website does not host a remote migration API.
Execution stays local · Approvals are not bypassed · Requires development work.
Explore integration paths →Those are not part of the currently published v1.1.1 PostgreSQL production scope. Do not put production credentials into Browser Studio or assume an experimental connector is qualified.
Read capability and limit explanations →An integration is software running on your device, not a button that uploads your database to this site. Pick the supported execution surface before writing any code.
Open Studio, choose your CSV and an outcome, inspect validation, and download the result. No API key, server or integration snippet is necessary.
Open Studio →Install v1.1.1 on the machine holding your existing SQLite table and CSV. A developer can invoke the CLI within local automation, preserving the inspect → plan → dry-run → approve → run → verify → receipt sequence.
Local runner instructions →The source includes an authenticated loopback command service. It is not a hosted API and is not started merely by opening this website. Configure it with a local command service, a strong bearer token and an approved Origin policy.
Bridge contract and setup →Machine-readable command responses belong in developer tools; an HTTP endpoint does not provide a human UI. For humans, use Studio or these guides. For applications, use the local CLI or the loopback bridge after provisioning the customer-controlled runtime. This hosted website has no public database-write API, no cloud database connection form and no universal integration token.
Start with the released CLI for production-scoped filesystem CSV to SQLite operations. The loopback HTTP bridge is an integration component, not a remotely hosted SPOOL API. Code examples and machine formats are deliberately kept in the technical section below.
Install the exact released version on the same customer-controlled system as the source and target. Use a separately configured local bridge only when a client requires HTTP.
Inspect source and live target, create a plan, then run a dry-run. Stop on source or contract drift.
Issue the supported bound approval for the exact operation. An API invocation is not itself permission to mutate.
Run only the approved operation, reconcile ambiguous results, verify the supported evidence and retrieve the receipt.
The current source exports a loopback-only daemon factory. A developer must initialize the local command service, supply a strong bearer token, configure allowed Origins and start the server. It accepts authenticated POST requests to /v1/command on its chosen localhost port; a direct browser navigation or GET is not a valid command call. The daemon returns JSON for programmatic consumers, not a rendered migration dashboard.
Do not point production tools at this site's /api path or treat a JSON document as an installation wizard. The published CLI is the release-scoped local execution path.
Method: POST. Host: customer-controlled loopback IP. Path: /v1/command. Authorization: Bearer token, at least 32 bytes. Body: bounded JSON command envelope. Response: structured success or error JSON.
Supported source commands include inspect, plan, dry-run, approve, run, status, verify and receipt; check the exact released adapter before relying on additional commands. The website itself cannot connect to this bridge because its browser Content Security Policy disallows outbound requests.
Review the actual daemon contract → See installation and approval instructions →
Use Browser Studio when you need local CSV preparation and validation. Use the Local Runner when you need a production-verified, bounded-memory write into an existing SQLite table with a durable snapshot, approval, crash reconciliation and a receipt.
Profile, infer, transform, validate, checkpoint, inspect violations and export without a dataset backend. Browser input limit: 50 MiB.
Start in Studio →Bounded-memory stream + 256 MiB default source ceiling + durable snapshot + live target contract + target_write approval + fencing + atomic ledger + verification + receipt.
Open Local Runner →Use Browser Studio when you need local CSV preparation and validation. Use the Local Runner when you need a released, bounded-memory write into an existing SQLite table with a durable snapshot, approval, crash reconciliation and a receipt.
Profile, infer, transform, validate, checkpoint, inspect violations and export without a dataset backend. Browser input limit: 50 MiB.
Start in Studio →Bounded-memory stream + 256 MiB default source ceiling + durable snapshot + live target contract + target_write approval + fencing + atomic ledger + verification + receipt.
Open Local Runner →Clean a CSV in the browser, prepare a local SQLite migration, or connect an existing app. The supported boundary is different for each path.
# Preferred v1.1.1 install'));
+ assert.doesNotMatch(product, /GATE B · PRODUCTION-VERIFIED/);
+ assert.ok(product.includes('sustained-load qualification is still missing'));
+ assert.ok(product.includes('not a remotely hosted SPOOL API'));
+});
+
+test('developer links resolve to source documentation and mobile nav remains accessible', () => {
+ assert.ok(product.includes('href="${REPO}/blob/main/src/daemon/spoold.js"'));
+ assert.ok(!product.includes('\\' + '${REPO}'));
+ assert.match(styles, /\.start-paths/);
+ assert.match(styles, /\.developer-details/);
+ assert.match(styles, /\.guided-home-band/);
+ assert.match(styles, /\.product-topbar \.primary-nav\{display:flex/);
+});
diff --git a/tests/postgres-cdc-capture-ordering.test.js b/tests/postgres-cdc-capture-ordering.test.js
new file mode 100644
index 00000000..2deec3fc
--- /dev/null
+++ b/tests/postgres-cdc-capture-ordering.test.js
@@ -0,0 +1,237 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createCdcSerialPump } from '../src/connectors/postgres/cdc-serial-pump.js';
+
+const code = readFileSync(new URL('../src/connectors/postgres/cdc.js', import.meta.url), 'utf8');
+const begin = code.indexOf('export async function streamPostgresChanges(');
+const end = code.indexOf('export function createCdcCheckpointStore(', begin);
+assert.ok(begin >= 0 && end > begin, 'real CDC capture implementation is present');
+const captureSource = code.slice(begin, end).replace(/^export /gm, '');
+
+function makeCapture(events, { failAcknowledging = null, refuseAcknowledging = null, honorFlowControl = false, heartbeatLsn = null, heartbeatAfterTag = null, commitEndLsn = null } = {}) {
+ let service;
+ class FakeReplicationService {
+ constructor(_connection, settings) {
+ this.settings = settings;
+ this.listeners = new Map(); this.acknowledged = [];
+ this.stopped = false; this.destroyed = false; this.dispatched = []; service = this;
+ }
+ on(name, cb) { this.listeners.set(name, cb); }
+ async subscribe() {
+ for (const [lsn, kind] of events) {
+ this.dispatched.push(kind);
+ const inflight = this.listeners.get('data')(lsn, { tag: kind, commitEndLsn: kind === 'commit' ? commitEndLsn : null });
+ if (honorFlowControl) await inflight;
+ if (heartbeatLsn && heartbeatAfterTag === kind) this.listeners.get('heartbeat')(heartbeatLsn);
+ }
+ if (heartbeatLsn && !heartbeatAfterTag) this.listeners.get('heartbeat')(heartbeatLsn);
+ }
+ async acknowledge(lsn) {
+ if (lsn === failAcknowledging) throw Object.assign(new Error('injected ACK failure'), { code: 'ACK_FAILED' });
+ if (lsn === refuseAcknowledging) return false;
+ this.acknowledged.push(lsn);
+ return true;
+ }
+ async stop() { this.stopped = true; }
+ async destroy() { this.destroyed = true; }
+ }
+ const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
+ const capture = new Function(
+ 'requireDatabaseRef', 'requireSlotName', 'PUBLICATION_NAME', 'LSN',
+ 'parsePostgresEndpoint', 'LogicalReplicationService', 'PgoutputPlugin',
+ 'normalizeMessage', 'comparePostgresLsn', 'fail',
+ 'classifyCdcStreamError', 'createCdcSerialPump',
+ captureSource + '\nreturn streamPostgresChanges;'
+ )(
+ ref => ref, slot => slot, /^[a-z_]+$/, /^0\/[0-9A-Fa-f]+$/,
+ () => ({ host: 'localhost', port: 5432, sslMode: 'disable' }),
+ FakeReplicationService, class {},
+ (lsn, message) => ({ tag: message.tag, lsn, commitEndLsn: message.commitEndLsn ?? null }),
+ (left, right) => Number.parseInt(left.split('/')[1], 16) - Number.parseInt(right.split('/')[1], 16),
+ fail, error => { throw error; }, createCdcSerialPump
+ );
+ const run = extra => capture({
+ ref: { endpoint: 'postgresql://127.0.0.1:5432?sslmode=disable', database: 'isolated', identity: { user: 'test' }, secretRef: { provider: 'env', key: 'ISOLATED_TEST' } },
+ credentialBroker: { withSecret: async (_, fn) => fn('fake') },
+ slotName: 'isolated_slot', publicationNames: ['isolated_pub'],
+ startLsn: '0/0', untilLsn: '0/3', ...extra
+ });
+ return { run, getService: () => service };
+}
+
+const events = [['0/1', 'begin'], ['0/2', 'insert'], ['0/3', 'commit']];
+
+test('slow durability callback cannot cause a later message to acknowledge first', async () => {
+ let resume;
+ const gate = new Promise(resolve => { resume = resolve; });
+ const harness = makeCapture(events);
+ const observed = [];
+ const running = harness.run({
+ onChange: async change => {
+ if (change.tag === 'begin') await gate;
+ observed.push(change.tag);
+ }
+ });
+ for (let i = 0; i < 5; i++) await Promise.resolve();
+ assert.deepEqual(harness.getService().acknowledged, []);
+ resume();
+ const result = await running;
+ assert.deepEqual(observed, ['begin', 'insert', 'commit']);
+ assert.deepEqual(harness.getService().acknowledged, ['0/3']);
+ assert.equal(result.acknowledgedLsn, '0/3');
+ assert.equal(harness.getService().destroyed, true);
+});
+
+test('replication flow control awaits the complete async callback before reading next WAL message', async () => {
+ let resume;
+ const gate = new Promise(resolve => { resume = resolve; });
+ const harness = makeCapture(events, { honorFlowControl: true });
+ const running = harness.run({
+ onChange: async change => {
+ if (change.tag === 'begin') await gate;
+ }
+ });
+ for (let i = 0; i < 5; i++) await Promise.resolve();
+ assert.deepEqual(harness.getService().dispatched, ['begin']);
+ assert.deepEqual(harness.getService().acknowledged, []);
+ resume();
+ const result = await running;
+ assert.deepEqual(harness.getService().dispatched, ['begin', 'insert', 'commit']);
+ assert.deepEqual(harness.getService().acknowledged, ['0/3']);
+ assert.equal(result.acknowledgedLsn, '0/3');
+});
+
+test('durability failure refuses subsequent messages and never ACKs their WAL positions', async () => {
+ const harness = makeCapture(events);
+ await assert.rejects(harness.run({
+ onChange: async change => {
+ if (change.tag === 'insert') throw Object.assign(new Error('injected apply failure'), { code: 'INJECTED_FAILURE' });
+ }
+ }), { code: 'INJECTED_FAILURE' });
+ assert.deepEqual(harness.getService().acknowledged, []);
+ assert.equal(harness.getService().destroyed, true);
+});
+
+test('maximum message limit refuses incomplete source transaction before ACKing the boundary event', async () => {
+ const harness = makeCapture(events);
+ const delivered = [];
+ await assert.rejects(harness.run({
+ maxMessages: 2, onChange: async change => { delivered.push(change.tag); }
+ }), { code: 'CDC_CAPTURE_BOUNDARY_INCOMPLETE' });
+ assert.deepEqual(delivered, ['begin']);
+ assert.deepEqual(harness.getService().acknowledged, []);
+});
+
+test('LSN waterline is applied only on COMMIT, not to uncommitted row messages', async () => {
+ const harness = makeCapture(events);
+ const result = await harness.run({ untilLsn: '0/2' });
+ assert.deepEqual(harness.getService().acknowledged, ['0/3']);
+ assert.equal(result.acknowledgedLsn, '0/3');
+});
+
+test('transport ACK rejection cannot advance the reported commit LSN', async () => {
+ const harness = makeCapture(events, { failAcknowledging: '0/3' });
+ await assert.rejects(harness.run(), { code: 'ACK_FAILED' });
+ assert.deepEqual(harness.getService().acknowledged, []);
+});
+
+test('callback queue bound refuses overflow without processing subsequent events', async () => {
+ let release;
+ const gate = new Promise(resolve => { release = resolve; });
+ const applied = [];
+ const errors = [];
+ const pump = createCdcSerialPump({
+ maxPending: 2,
+ handle: async (_, message) => { await gate; applied.push(message); },
+ onFailure: error => errors.push(error)
+ });
+ assert.equal(pump.enqueue('0/1', 1), true);
+ assert.equal(pump.enqueue('0/2', 2), true);
+ assert.equal(pump.enqueue('0/3', 3), false);
+ assert.equal(errors.length, 1);
+ assert.equal(errors[0].code, 'CDC_EVENT_BACKPRESSURE_EXCEEDED');
+ release();
+ await pump.drain();
+ assert.deepEqual(applied, []);
+ assert.deepEqual(pump.stats(), { accepting: false, pending: 0 });
+});
+
+
+test('capture reports truncation instead of silently certifying an incomplete CDC window', async () => {
+ const harness = makeCapture(events);
+ const captured = await harness.run({ maxCollectedChanges: 2 });
+ assert.equal(captured.messageCount, 3);
+ assert.equal(captured.collectedChangeCount, 2);
+ assert.equal(captured.truncatedChanges, true);
+ assert.deepEqual(captured.changes.map(change => change.tag), ['insert', 'commit']);
+});
+
+test('capture refuses invalid collection bounds rather than dropping evidence', async () => {
+ for (const maxCollectedChanges of [0, -1, 1.5, Infinity, 1_000_001]) {
+ const harness = makeCapture(events);
+ await assert.rejects(harness.run({ maxCollectedChanges }), { code: 'INVALID_POSTGRES_CDC_CONFIG' });
+ }
+});
+
+test('commit END-LSN satisfies flush-waterline without waiting for another source transaction', async () => {
+ const harness = makeCapture(events, { commitEndLsn: '0/4' });
+ const result = await harness.run({ untilLsn: '0/4' });
+ assert.equal(result.lastLsn, '0/4');
+ assert.equal(result.acknowledgedLsn, '0/4');
+ assert.equal(harness.getService().stopped, true);
+});
+
+test('idle WAL heartbeat completes a fully drained capture after final commit', async () => {
+ const harness = makeCapture(events, { heartbeatLsn: '0/5' });
+ const result = await harness.run({ untilLsn: '0/4' });
+ assert.equal(result.messageCount, 3);
+ assert.equal(result.changes.at(-1).tag, 'commit');
+ assert.equal(harness.getService().acknowledged.join(','), '0/3');
+ assert.equal(result.lastLsn, '0/3');
+ assert.equal(harness.getService().stopped, true);
+});
+
+test('heartbeat never terminates an open source transaction', async () => {
+ const harness = makeCapture(events, {
+ heartbeatLsn: '0/5', heartbeatAfterTag: 'insert', honorFlowControl: true
+ });
+ const result = await harness.run({ untilLsn: '0/4' });
+ assert.deepEqual(result.changes.map(change => change.tag), ['begin','insert','commit']);
+ assert.equal(harness.getService().acknowledged.length, 1);
+ assert.equal(result.messageCount, 3);
+});
+
+
+test('manual pgoutput capture never enables the driver periodic volatile-WAL ACK timer', async () => {
+ const harness = makeCapture(events);
+ await harness.run();
+ assert.deepEqual(harness.getService().settings.acknowledge, {auto:false, timeoutSeconds:0});
+ const applierCode = readFileSync(new URL('../src/connectors/postgres/cdc-apply.js', import.meta.url),'utf8');
+ assert.ok(applierCode.includes('acknowledge: { auto: false, timeoutSeconds: 0 }'));
+});
+
+test('a complete source transaction is the FIRST WAL position acknowledged', async () => {
+ const harness = makeCapture(events, {commitEndLsn:'0/4'});
+ const result = await harness.run({untilLsn:'0/4'});
+ assert.deepEqual(harness.getService().acknowledged,['0/4']);
+ assert.equal(result.acknowledgedLsn,'0/4');
+});
+
+test('driver refusal to acknowledge a COMMIT fails closed and cannot report success', async () => {
+ const harness = makeCapture(events,{refuseAcknowledging:'0/3'});
+ await assert.rejects(harness.run(), {code:'CDC_ACK_FAILED'});
+ assert.deepEqual(harness.getService().acknowledged,[]);
+});
+
+test('orphan COMMIT is never acknowledged',async () => {
+ const harness=makeCapture([['0/1','commit']]);
+ await assert.rejects(harness.run(),{code:'CDC_PROTOCOL_VIOLATION'});
+ assert.deepEqual(harness.getService().acknowledged,[]);
+});
+
+test('row mutation without source BEGIN is never acknowledged',async () => {
+ const harness=makeCapture([['0/1','insert']]);
+ await assert.rejects(harness.run(),{code:'CDC_PROTOCOL_VIOLATION'});
+ assert.deepEqual(harness.getService().acknowledged,[]);
+});
diff --git a/tests/preview-server.test.js b/tests/preview-server.test.js
new file mode 100644
index 00000000..a8ec2e43
--- /dev/null
+++ b/tests/preview-server.test.js
@@ -0,0 +1,70 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { once } from 'node:events';
+import { mkdtemp, mkdir, writeFile, symlink, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createPreviewHandler } from '../scripts/serve-preview.js';
+
+async function withServer(task) {
+ const root = await mkdtemp(join(tmpdir(), 'spool-preview-test-'));
+ const server = createServer(createPreviewHandler({directory:root}));
+ try {
+ await mkdir(join(root,'src'));
+ await writeFile(join(root,'index.html'),'isolated-preview');
+ await writeFile(join(root,'src/app.js'), 'export default 1;');
+ await writeFile(join(root,'vercel.json'), '{"unsafe":true}');
+ server.listen(0,'127.0.0.1'); await once(server,'listening');
+ return await task('http://127.0.0.1:'+server.address().port, root);
+ } finally {
+ if (server.listening) await new Promise(resolve=>server.close(resolve));
+ await rm(root,{recursive:true,force:true});
+ }
+}
+test('health is truthful and discloses preview rather than production',()=>withServer(async u=>{
+ const r=await fetch(u+'/healthz');
+ assert.equal(r.status,200);
+ assert.deepEqual(await r.json(),{status:'preview',productionQualified:false});
+}));
+test('all human and studio deep links return shell, not a 404',()=>withServer(async u=>{
+ for (const path of ['/','/start','/local-runner','/integrations','/developers','/studio/new','/studio/results']) {
+ const r=await fetch(u+path);
+ assert.equal(r.status,200,path);
+ assert.match(await r.text(),/isolated-preview/);
+ assert.match(r.headers.get('content-security-policy'),/connect-src 'none'/);
+ }
+}));
+test('static module correct MIME, no API, no repo metadata or host config exposed',()=>withServer(async u=>{
+ assert.match((await fetch(u+'/src/app.js')).headers.get('content-type'),/text\/javascript/);
+ for (const path of ['/api','/package.json','/vercel.json','/secret.env','/src/nothing.js']) {
+ assert.equal((await fetch(u+path)).status,404,path);
+ }
+}));
+test('reject invalid methods and encoded path traversal',()=>withServer(async u=>{
+ assert.equal((await fetch(u+'/studio/new',{method:'POST'})).status,405);
+ assert.equal((await fetch(u+'/%2e%2e%5csecret')).status,400);
+ assert.equal((await fetch(u+'/%00')).status,400);
+}));
+test('HEAD returns correct length but no body',()=>withServer(async u=>{
+ const r=await fetch(u+'/studio',{method:'HEAD'});
+ assert.equal(r.status,200);
+ assert.equal(r.headers.get('content-length'),String(Buffer.byteLength('isolated-preview')));
+ assert.equal(await r.text(),'');
+}));
+
+test('symlinks inside dist cannot leak files or directories from outside the static artifact',()=>withServer(async (u,root)=>{
+ const outside = await mkdtemp(join(tmpdir(),'spool-preview-outside-'));
+ try {
+ await writeFile(join(outside,'private.html'),'OUTSIDE_DIST_SENTINEL');
+ await symlink(join(outside,'private.html'),join(root,'src','escape.html'));
+ await symlink(outside,join(root,'src','escape-folder'));
+ for (const path of ['/src/escape.html','/src/escape-folder/private.html']) {
+ const response = await fetch(u+path);
+ assert.equal(response.status,404,path);
+ assert.doesNotMatch(await response.text(),/OUTSIDE_DIST_SENTINEL/);
+ }
+ } finally {
+ await rm(outside,{recursive:true,force:true});
+ }
+}));
diff --git a/tests/product-route-bridge.test.js b/tests/product-route-bridge.test.js
new file mode 100644
index 00000000..41db6584
--- /dev/null
+++ b/tests/product-route-bridge.test.js
@@ -0,0 +1,121 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+
+const appSource = readFileSync(new URL('../src/app.js', import.meta.url), 'utf8');
+const productSource = readFileSync(new URL('../src/product-surface.js', import.meta.url), 'utf8');
+const PRODUCT_PATHS = ['/local-runner', '/examples', '/security', '/services', '/start', '/integrations', '/developers'];
+
+function productBridge() {
+ const window = { location: { pathname: '/start' }, addEventListener() {} };
+ const document = { getElementById() { return null; } };
+ return new Function('window', 'document', 'MutationObserver', 'queueMicrotask',
+ productSource + '\nreturn window.__spoolProductSurface;'
+ )(window, document, class {}, () => {});
+}
+
+function appFunction(name, nextName, extra) {
+ const begin = appSource.indexOf('function ' + name + '(');
+ let end = appSource.indexOf('\nfunction ' + nextName + '(', begin);
+ if (end < 0) end = appSource.indexOf('\nasync function ' + nextName + '(', begin);
+ assert.ok(begin >= 0 && end > begin, name + ' must have a bounded definition');
+ return new Function(...extra.names, appSource.slice(begin, end) + '\nreturn ' + name + ';')(...extra.values);
+}
+
+test('every supported product page renders actual human-facing HTML without undefined placeholders', () => {
+ const bridge = productBridge();
+ for (const path of PRODUCT_PATHS) {
+ const html = bridge.render(path);
+ assert.ok(html.includes('data-product-route="' + path + '"'), path);
+ assert.ok(html.includes(' {
+ const bridge = productBridge();
+ for (const path of PRODUCT_PATHS) {
+ const root = { innerHTML: '' };
+ const document = { title: '' };
+ const render = appFunction('render', 'pageTitle', {
+ names: ['appRoot', 'latestState', 'currentPath', 'window', 'document'],
+ values: [root, {}, () => path, { __spoolProductSurface: bridge }, document]
+ });
+ render();
+ assert.equal(root.innerHTML, bridge.render(path), path);
+ assert.equal(document.title, bridge.title(path) + ' — SPOOL', path);
+ }
+});
+
+test('valid product URLs show loading state, never 404, if sibling bundle has not evaluated', () => {
+ const root = { innerHTML: '' };
+ const render = appFunction('render', 'pageTitle', {
+ names: ['appRoot', 'latestState', 'currentPath', 'window', 'document'],
+ values: [root, {}, () => '/start', {}, { title: '' }]
+ });
+ render();
+ assert.match(root.innerHTML, /Loading SPOOL/);
+ assert.doesNotMatch(root.innerHTML, /404/);
+});
+
+test('navigation accepts product URLs and rejects unknown routes', () => {
+ const routeDefinition = appSource.match(/const ROUTES = Object\.freeze\((\[[\s\S]*?\])\);/);
+ assert.ok(routeDefinition);
+ const routes = new Function('return ' + routeDefinition[1])();
+ for (const path of PRODUCT_PATHS) assert.ok(routes.includes(path), path);
+ const moved = [];
+ const window = {
+ location: { pathname: '/' },
+ history: { pushState(_, __, path) { moved.push(path); } },
+ scrollTo() {}
+ };
+ const navigate = appFunction('navigate', 'scheduleRender', {
+ names: ['ROUTES', 'window', 'render'],
+ values: [routes, window, () => {}]
+ });
+ navigate('/local-runner');
+ navigate('/start');
+ navigate('/not-a-route');
+ assert.deepEqual(moved, ['/local-runner', '/start']);
+});
+
+test('product-to-Studio clicks stay in SPA; modified, external, or download clicks stay native', () => {
+ let handler;
+ const routes = ['/', '/studio/new', '/start', '/local-runner'];
+ const moved = [];
+ const root = { addEventListener(type, listener) { if (type === 'click') handler = listener; } };
+ const window = { addEventListener() {} };
+ const bind = appFunction('bindGlobalEvents', 'initWebMcp', {
+ names: ['appRoot', 'window', 'ROUTES', 'navigate', 'render'],
+ values: [root, window, routes, route => moved.push(route), () => {}]
+ });
+ bind();
+ assert.equal(typeof handler, 'function');
+ function click(href, options = {}) {
+ let prevented = false;
+ const anchor = {
+ dataset: {},
+ getAttribute(name) { return name === 'href' ? href : null; },
+ hasAttribute(name) { return name === 'download' ? Boolean(options.download) : false; }
+ };
+ handler({
+ target: { closest(selector) { return selector === '[data-route], a[href^="/"]' ? anchor : null; } },
+ defaultPrevented: false,
+ button: 0,
+ ...options,
+ preventDefault() { prevented = true; }
+ });
+ return prevented;
+ }
+ assert.equal(click('/studio/new'), true);
+ assert.equal(click('/start'), true);
+ assert.equal(click('/start', { ctrlKey: true }), false);
+ assert.equal(click('/start', { metaKey: true }), false);
+ assert.equal(click('/start', { button: 1 }), false);
+ assert.equal(click('/start', { download: true }), false);
+ assert.equal(click('https://example.com/'), false);
+ assert.deepEqual(moved, ['/studio/new', '/start']);
+});
diff --git a/tests/qualify-cdc-capture-proof.test.js b/tests/qualify-cdc-capture-proof.test.js
new file mode 100644
index 00000000..a7bad5ed
--- /dev/null
+++ b/tests/qualify-cdc-capture-proof.test.js
@@ -0,0 +1,80 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { auditCdcCapture, compareCaptureLsn } from '../scripts/qualify/postgres/cdc-capture-proof.js';
+
+const event = (tag, lsn, extra = {}) => ({ tag, lsn, ...extra });
+const tx = (start, row, commit, end) => [
+ event('begin', start),
+ event('insert', row),
+ event('commit', commit, { commitEndLsn: end })
+];
+
+test('concurrent long transaction with old row LSN is not a false replay', () => {
+ const proof = auditCdcCapture(tx('0/10','0/12','0/31','0/33'), { priorCheckpointLsn: '0/30' });
+ assert.deepEqual(proof, { checkpointLsn: '0/33', commits: 1, rowEvents: 1 });
+});
+
+test('cursor records end of complete commit, not earlier row or record start LSN', () => {
+ const proof = auditCdcCapture(tx('0/60','0/61','0/64','0/66'));
+ assert.equal(proof.checkpointLsn, '0/66');
+});
+
+test('cross-window commit regression is rejected against prior durable end cursor', () => {
+ assert.throws(() => auditCdcCapture(tx('0/10','0/11','0/1F','0/21'), {
+ priorCheckpointLsn: '0/20'
+ }), { code: 'CDC_RESTART_REPLAY' });
+});
+
+test('commit end cannot precede its own WAL record', () => {
+ assert.throws(() => auditCdcCapture(tx('0/10','0/11','0/21','0/20')), {
+ code: 'CDC_CAPTURE_INVALID'
+ });
+});
+
+test('within-transaction row WAL record order remains monotonic', () => {
+ assert.throws(() => auditCdcCapture([
+ event('begin','0/10'), event('insert','0/13'), event('update','0/12'),
+ event('commit','0/20')
+ ]), { code: 'CDC_STREAM_ORDER_VIOLATION' });
+});
+
+test('row mutation outside begin/commit is never accepted', () => {
+ assert.throws(() => auditCdcCapture([event('delete','0/10')]), {
+ code: 'CDC_CAPTURE_INCOMPLETE'
+ });
+});
+
+test('truncated open transaction is not a successful capture', () => {
+ assert.throws(() => auditCdcCapture([
+ event('begin','0/10'), event('insert','0/11')
+ ]), { code: 'CDC_CAPTURE_INCOMPLETE' });
+});
+
+test('nested begin, orphan commit, and no-commit capture fail closed', () => {
+ assert.throws(() => auditCdcCapture([
+ event('begin','0/10'), event('begin','0/11')
+ ]), { code: 'CDC_CAPTURE_INCOMPLETE' });
+ assert.throws(() => auditCdcCapture([event('commit','0/21')]), {
+ code: 'CDC_CAPTURE_INCOMPLETE'
+ });
+ assert.throws(() => auditCdcCapture([], { priorCheckpointLsn: '0/20' }), {
+ code: 'CDC_CAPTURE_INCOMPLETE'
+ });
+});
+
+test('transient relation metadata does not break complete transaction auditing', () => {
+ const proof = auditCdcCapture([
+ event('relation','0/10'), event('begin','0/11'),
+ event('relation','0/12'), event('insert','0/13'),
+ event('commit','0/14')
+ ]);
+ assert.equal(proof.commits,1);
+ assert.equal(proof.rowEvents,1);
+});
+
+test('64-bit LSN comparisons do not truncate to JavaScript floating precision', () => {
+ assert.equal(compareCaptureLsn('FFFFFFFF/FFFFFFFF','FFFFFFFF/FFFFFFFE'),1);
+ assert.equal(compareCaptureLsn('00000001/0','0/FFFFFFFF'),1);
+ assert.equal(compareCaptureLsn('ABCDEF00/00000002','ABCDEF00/00000002'),0);
+ assert.throws(()=>compareCaptureLsn('0/not-a-lsn','0/1'), { code:'INVALID_POSTGRES_LSN' });
+});
diff --git a/tests/qualify-cdc-soak.test.js b/tests/qualify-cdc-soak.test.js
new file mode 100644
index 00000000..8502ee72
--- /dev/null
+++ b/tests/qualify-cdc-soak.test.js
@@ -0,0 +1,122 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+
+const code = readFileSync(new URL('../scripts/qualify/postgres/cdc-soak.js', import.meta.url), 'utf8');
+const start = code.indexOf(' async function writePlan(chunk) {');
+const end = code.indexOf(' // Audit every complete pgoutput transaction', start);
+assert.ok(start >= 0 && end > start, 'production CDC qualification writer is present');
+const functionBody = code.slice(start, end);
+// Test the actual production operation counter. A test-local replacement for
+// opEvents previously hid a live-writer accounting defect.
+const mixStart = code.indexOf('function opMix(writer, opIndex) {');
+const mixEnd = code.indexOf('export async function runCdcSoak(', mixStart);
+assert.ok(mixStart >= 0 && mixEnd > mixStart, 'production CDC operation mix is present');
+const { opMix, opEvents } = new Function(code.slice(mixStart, mixEnd) + '\nreturn { opMix, opEvents };')();
+
+test('production counter includes both WAL row changes for update/delete/multi', () => {
+ assert.equal(opEvents('insert'), 1);
+ for (const kind of ['update','delete','multi']) assert.equal(opEvents(kind), 2);
+ assert.throws(() => opEvents('not-a-real-operation'), /Unsupported deterministic/);
+});
+
+test('mixed workload event budget exactly matches emitted source row operations', () => {
+ let inserted = 0, updated = 0, deleted = 0;
+ const kinds = new Set();
+ let expected = 0;
+ for (let writer = 0; writer < 4; writer += 1) {
+ for (let op = 0; op < 100; op += 1) {
+ const kind = opMix(writer, op);
+ kinds.add(kind);
+ inserted += kind === 'multi' ? 2 : 1;
+ if (kind === 'update') updated += 1;
+ if (kind === 'delete') deleted += 1;
+ expected += opEvents(kind);
+ }
+ }
+ assert.deepEqual([...kinds].sort(), ['delete','insert','multi','update']);
+ assert.equal(expected, inserted + updated + deleted);
+});
+
+async function exercise(kind, { workers = 1, fault = null, chunk = 0 } = {}) {
+ const sessions = [];
+ class Client {
+ constructor() { this.calls = []; this.params = []; this.closed = false; sessions.push(this); }
+ async connect() {}
+ async query(sql, values = []) {
+ this.calls.push(sql);
+ this.params.push(values);
+ if (fault && ((fault === 'SECOND_INSERT' && sql.startsWith('INSERT') && this.calls.filter(call => call.startsWith('INSERT')).length === 2)
+ || (fault !== 'SECOND_INSERT' && sql.includes(fault)))) throw new Error('injected PostgreSQL failure');
+ return { rowCount: 1 };
+ }
+ async end() { this.closed = true; }
+ }
+ const fn = new Function(
+ 'Client', 'pgConfig', 'writers', 'opsPerChunk', 'opMix', 'WRITER_BASE',
+ 'WRITER_STRIDE', 'MULTI_OFFSET', 'table', 'opEvents', 'sleep', 'writerPaceMs',
+ functionBody + '\nreturn writePlan;'
+ )(
+ Client, { host: '127.0.0.1', port: 5432, database: 'isolated', user: 'test', password: 'fixture' },
+ workers, 100, () => kind, 100_000_000, 20_000_000, 10_000_000,
+ 'q_cdc_test', opEvents, () => Promise.resolve(), 0
+ );
+ let result, error;
+ try { result = await fn(chunk); } catch (caught) { error = caught; }
+ return { result, error, sessions };
+}
+
+test('seven-day CDC workload is generated in bounded windows, not preallocated arrays', () => {
+ assert.match(code, /const CHUNK_WINDOW_MS = 30_000/);
+ assert.match(code, /const opsPerChunk = 100/);
+ assert.doesNotMatch(code, /const plans =|plans\[chunk\]/);
+ assert.match(code, /const observedSoakMs = Number\(process\.hrtime\.bigint\(\) - soakStart\)/);
+ assert.match(code, /CDC_SOAK_UNDER_EXECUTED/);
+ const chunks = Math.ceil(7 * 86400 * 1000 / 30000);
+ assert.equal(chunks, 20160);
+ const maxOpIndex = chunks * 100 - 1;
+ const lastId = 100_000_000 + 49 * 20_000_000 + maxOpIndex + 1 + 10_000_000;
+ assert.ok(lastId < 2_147_483_647);
+});
+
+for (const kind of ['insert', 'update', 'delete', 'multi']) {
+ test('real source mutations and counted CDC effects: ' + kind, async () => {
+ const { result, error, sessions } = await exercise(kind);
+ assert.equal(error, undefined);
+ assert.equal(result.operations, 100);
+ assert.equal(result.inserted, kind === 'multi' ? 200 : 100);
+ assert.equal(result.attempted, kind === 'insert' ? 100 : 200);
+ assert.equal(sessions.length, 1);
+ assert.equal(sessions[0].closed, true);
+ const log = sessions[0].calls.map(query => query.split(' ')[0]);
+ if (kind === 'insert') assert.deepEqual(log.slice(0, 1), ['INSERT']);
+ else assert.deepEqual(log.slice(0, 4), ['BEGIN', 'INSERT', kind === 'multi' ? 'INSERT' : kind === 'delete' ? 'DELETE' : 'UPDATE', 'COMMIT']);
+ if (kind === 'multi') {
+ assert.equal(sessions[0].params[1][0] - sessions[0].params[2][0], -10_000_000, 'two source rows must have distinct keys');
+ }
+ assert.equal(log.some(sql => sql.includes(';')), false, 'node-postgres parameterized multi-statements forbidden');
+ });
+}
+
+test('concurrent fault rolls back incomplete transaction and awaits every worker shutdown', async () => {
+ const { result, error, sessions } = await exercise('multi', { workers: 2, fault: 'SECOND_INSERT' });
+ assert.equal(result, undefined);
+ assert.match(error?.message ?? '', /injected PostgreSQL failure/);
+ assert.equal(sessions.length, 2);
+ assert.ok(sessions.every(client => client.closed));
+ assert.ok(sessions.every(client => client.calls.includes('ROLLBACK')));
+ assert.ok(sessions.every(client => !client.calls.includes('COMMIT')));
+});
+
+test('identifier-space exhaustion fails instead of aliasing another writer or marker', async () => {
+ const { result, error, sessions } = await exercise('insert', { chunk: 100000 });
+ assert.equal(result, undefined);
+ assert.match(error?.message ?? '', /exhausted/);
+ assert.ok(sessions.every(client => client.closed));
+});
+
+test('a driver exception cannot be silently counted as completed qualification evidence', () => {
+ assert.doesNotMatch(functionBody, /catch\s*\{\s*\}/);
+ assert.match(functionBody, /if \(insertedRow\.rowCount|if \(added\.rowCount/);
+ assert.match(code, /CDC_ACTUAL_EVENT_COUNT_MISMATCH/);
+});
diff --git a/tests/qualify-cdc-writer-transaction.test.js b/tests/qualify-cdc-writer-transaction.test.js
new file mode 100644
index 00000000..0b6d6bc3
--- /dev/null
+++ b/tests/qualify-cdc-writer-transaction.test.js
@@ -0,0 +1,61 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+
+const file = readFileSync(new URL('../scripts/qualify/postgres/cdc-production-lifecycle.js', import.meta.url), 'utf8');
+const start = file.indexOf(' async function writerTask(');
+const end = file.indexOf('\n try {\n const setup =', start);
+assert.ok(start >= 0 && end > start, 'executable qualification writer must exist');
+const writerBody = file.slice(start, end);
+
+async function executeOneWriterOperation({ worker = 0, failSql = null } = {}) {
+ const queries = [];
+ let closed = false;
+ let ticks = 0;
+ const client = {
+ async query(sql) {
+ queries.push(sql);
+ if (failSql && sql.includes(failSql)) throw new Error('injected source transaction fault');
+ return { rowCount: 1 };
+ },
+ async end() { closed = true; }
+ };
+ const fakeDate = { now() { return ticks++ === 0 ? 0 : 2; } };
+ const createWriter = new Function('admin', 'rowCount', 'sourceTable', 'Date', 'setTimeout',
+ writerBody + '\nreturn writerTask;'
+ );
+ const writer = createWriter(async () => client, 100, 'qualification_source', fakeDate,
+ () => Promise.resolve());
+ let result;
+ let error;
+ try { result = await writer(worker, 1); } catch (caught) { error = caught; }
+ return { queries, closed, result, error };
+}
+
+test('each seeded insert is committed as one actual PostgreSQL transaction', async () => {
+ const observed = await executeOneWriterOperation();
+ assert.deepEqual(observed.queries.map(query => query.split(' ')[0]),
+ ['BEGIN', 'INSERT', 'COMMIT']);
+ assert.deepEqual({ ops: observed.result.ops, transactions: observed.result.transactions },
+ { ops: 1, transactions: 1 });
+ assert.equal(observed.closed, true);
+});
+test('CDC delete-plus-reinsert is one atomic source transaction', async () => {
+ const observed = await executeOneWriterOperation({ worker: 7 }); // (7*13) % 100 = 91
+ assert.deepEqual(observed.queries.map(query => query.split(' ')[0]),
+ ['BEGIN', 'DELETE', 'INSERT', 'COMMIT']);
+ assert.equal(observed.result.transactions, 1);
+ assert.equal(observed.closed, true);
+});
+test('failure after delete rolls back both effects, never counts a committed transaction', async () => {
+ const observed = await executeOneWriterOperation({ worker: 7, failSql: 'INSERT' });
+ assert.deepEqual(observed.queries.map(query => query.split(' ')[0]),
+ ['BEGIN', 'DELETE', 'INSERT', 'ROLLBACK']);
+ assert.match(observed.error?.message ?? '', /injected source transaction fault/);
+ assert.equal(observed.closed, true);
+});
+test('qualification reports actual source commits, not loop-count approximations', () => {
+ assert.ok(file.includes('committedSourceTransactions !== totalOps'));
+ assert.ok(file.includes('event: \'writers_quiesced\', totalOps, committedSourceTransactions'));
+ assert.ok(!file.includes('transactions += 1;\n await new Promise'));
+});
diff --git a/tests/qualify-durable-checkpoint.test.js b/tests/qualify-durable-checkpoint.test.js
new file mode 100644
index 00000000..55b4fd7d
--- /dev/null
+++ b/tests/qualify-durable-checkpoint.test.js
@@ -0,0 +1,90 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createDurableJsonCheckpointStore } from '../scripts/qualify/postgres/durable-checkpoint.js';
+
+async function withTemp(fn) {
+ const dir = await mkdtemp(join(tmpdir(), 'spool-durable-checkpoint-'));
+ try { return await fn(dir); }
+ finally { await rm(dir, { recursive: true, force: true }); }
+}
+
+test('fsync/rename checkpoint is complete and owner-only across reopen', async () => withTemp(async dir => {
+ const path = join(dir, 'checkpoint.json');
+ const store = createDurableJsonCheckpointStore({ path });
+ assert.equal(await store.load(), null);
+ await store.save({ nextOffset: 10, id: 'first' });
+ assert.deepEqual(await createDurableJsonCheckpointStore({path}).load(), {nextOffset:10,id:'first'});
+ await store.save({ nextOffset: 20, id: 'second' });
+ assert.deepEqual(await store.load(), { nextOffset:20,id:'second' });
+ if (process.platform !== 'win32') assert.equal((await stat(path)).mode & 0o777, 0o600);
+}));
+
+test('fault after temp file fsync never truncates the previous published checkpoint', async () => withTemp(async dir => {
+ const path = join(dir, 'checkpoint.json');
+ const store = createDurableJsonCheckpointStore({path});
+ await store.save({nextOffset:10});
+ const faulted = createDurableJsonCheckpointStore({path, onBeforeRename: async () => {
+ throw new Error('injected crash boundary');
+ }});
+ await assert.rejects(faulted.save({nextOffset:20}), /injected crash boundary/);
+ assert.deepEqual(await store.load(), {nextOffset:10});
+ assert.deepEqual(await readdir(dir), ['checkpoint.json'], 'abandoned temp file must be deleted');
+}));
+
+test('corrupt checkpoint fails closed instead of silently replaying migration', async () => withTemp(async dir => {
+ const path = join(dir, 'checkpoint.json');
+ const store = createDurableJsonCheckpointStore({path});
+ await writeFile(path, '{"nextOffset":', 'utf8');
+ await assert.rejects(store.load(), SyntaxError);
+ await writeFile(path, 'null', 'utf8');
+ await assert.rejects(store.load(), /must be a JSON object/);
+ await assert.rejects(store.save(null), TypeError);
+}));
+
+test('actual SIGKILL between temp fsync and rename leaves previous durable checkpoint', {
+ skip: process.platform !== 'linux'
+}, async () => withTemp(async dir => {
+ const path = join(dir, 'checkpoint.json');
+ const store = createDurableJsonCheckpointStore({path});
+ await store.save({nextOffset:100});
+ const moduleUrl = new URL('../scripts/qualify/postgres/durable-checkpoint.js', import.meta.url).href;
+ const script = [
+ 'import {createDurableJsonCheckpointStore} from ' + JSON.stringify(moduleUrl) + ';',
+ 'const store = createDurableJsonCheckpointStore({path:process.argv[1],',
+ 'onBeforeRename:async()=>{process.stdout.write("READY\\n");await new Promise(()=>{})}});',
+ 'await store.save({nextOffset:200});'
+ ].join('\n');
+ const child = spawn(process.execPath, ['--input-type=module','--eval',script,path], {
+ stdio:['ignore','pipe','pipe']
+ });
+ let output = '';
+ let stderr = '';
+ child.stderr.on('data', c => { stderr += c.toString(); });
+ const exit = new Promise(resolve => child.on('close',(code,signal)=>resolve({code,signal})));
+ try {
+ let timeout;
+ try {
+ await Promise.race([
+ new Promise((resolve,reject)=>{
+ child.stdout.on('data', chunk=>{
+ output += chunk.toString();
+ if (output.includes('READY\n')) resolve();
+ });
+ child.on('error', reject);
+ child.on('close', ()=>reject(new Error('child died before fsync: '+stderr)));
+ }),
+ new Promise((_,reject)=>{ timeout = setTimeout(()=>reject(new Error('child fsync boundary timeout: '+stderr)),5000); })
+ ]);
+ } finally { clearTimeout(timeout); }
+ assert.equal(child.kill('SIGKILL'), true);
+ assert.equal((await exit).signal, 'SIGKILL');
+ assert.deepEqual(await store.load(), {nextOffset:100});
+ assert.equal(JSON.parse(await readFile(path,'utf8')).nextOffset,100);
+ } finally {
+ if (child.exitCode == null && child.signalCode == null) child.kill('SIGKILL');
+ }
+}));
diff --git a/tests/qualify-snapshot-fanout.test.js b/tests/qualify-snapshot-fanout.test.js
new file mode 100644
index 00000000..5ffe6dd1
--- /dev/null
+++ b/tests/qualify-snapshot-fanout.test.js
@@ -0,0 +1,96 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+
+const source = readFileSync(new URL('../scripts/qualify/postgres/database-source-load.js', import.meta.url), 'utf8');
+
+async function qualifyMock(writers, { wrongJoined = false, missingLive = false } = {}) {
+ const tables = new Map(), writes = [], readers = [];
+ let exporterOpen = false;
+ class Client {
+ async connect() {}
+ async end() {}
+ async query(sql) {
+ const table = /public\."([^"]+)"/.exec(sql)?.[1];
+ if (sql.startsWith('DROP TABLE')) { tables.delete(table); return { rowCount: 0 }; }
+ if (sql.startsWith('CREATE TABLE')) { tables.set(table, 0); return { rowCount: 0 }; }
+ if (sql.includes('generate_series(1, 1000)')) { tables.set(table, 1000); return { rowCount: 1000 }; }
+ if (sql.includes('VALUES (1000001')) {
+ assert.equal(exporterOpen, true, 'post-export write happened after snapshot owner closed');
+ tables.set(table, tables.get(table) + 1);
+ writes.push(table);
+ return { rowCount: 1 };
+ }
+ if (sql.startsWith('SELECT count(*)::int')) {
+ return { rows: [{ c: missingLive && table === writes[0] ? 1000 : tables.get(table) }] };
+ }
+ throw new Error('Unexpected mock SQL: ' + sql);
+ }
+ }
+ const fakeHash = () => ({ update() { return this; }, digest() { return 'abcdef0123456789'; } });
+ const sourceRuntime = () => ({
+ async withSnapshot(ref, read, opts) {
+ assert.equal(exporterOpen, true, 'joined reader ran after export transaction ended');
+ assert.equal(writes.length, writers * 2, 'read began before all post-export writes');
+ assert.equal(opts.snapshotToken, 'snapshot-1');
+ readers.push(ref.table);
+ const count = wrongJoined && readers.length === 1 ? 1001 : 1000;
+ return read({ async *batches() { yield { rows: Array(count) }; } });
+ }
+ });
+ const executable = source.replace(/^import[\s\S]*?;\s*$/gm, '').replace(/^export /gm, '');
+ const qualify = new Function(
+ 'createHash', 'Client', 'CredentialBroker', 'discoverPostgresCatalog',
+ 'withExportedPostgresSnapshot', 'createPostgresSourceRuntime',
+ executable + '\nreturn runDatabaseSourceLoad;'
+ )(
+ fakeHash, Client, class {},
+ async () => ({ tableCount: tables.size, catalogId: 'catalog-1' }),
+ async (_, callback) => {
+ exporterOpen = true;
+ try { return await callback({ exportedSnapshotId: 'snapshot-1', walLsn: '0/A' }); }
+ finally { exporterOpen = false; }
+ },
+ sourceRuntime
+ );
+ let result, error;
+ try {
+ result = await qualify({
+ profile: { writers }, seed: 'fixture', runId: 'fixture',
+ evidenceWriter: { appendRaw() {} },
+ pgConfig: { host: '127.0.0.1', port: 5432, database: 'isolated', user: 'test', password: 'test-only' }
+ });
+ } catch (caught) { error = caught; }
+ return { result, error, writes, readers, remainingTables: tables.size };
+}
+
+test('all declared source readers join the exported snapshot, not two hardcoded tables', async () => {
+ for (const writers of [2, 5]) {
+ const { result, error, writes, readers, remainingTables } = await qualifyMock(writers);
+ assert.equal(error, undefined);
+ assert.equal(writes.length, writers * 2);
+ assert.equal(new Set(readers).size, writers * 2);
+ assert.equal(result.metrics.joinedReaders, writers);
+ assert.equal(result.metrics.tablesRead, writers * 2);
+ assert.equal(result.metrics.postExportWrites, writers * 2);
+ assert.equal(result.metrics.totalRows, writers * 2000);
+ assert.equal(remainingTables, 0);
+ }
+});
+test('reader seeing post-export rows fails the shared-MVCC-snapshot qualification', async () => {
+ const result = await qualifyMock(2, { wrongJoined: true });
+ assert.match(result.error?.message ?? '', /Joined reader/);
+ assert.equal(result.result, undefined);
+ assert.equal(result.remainingTables, 0);
+});
+test('post-export write must be independently visible outside joined snapshot', async () => {
+ const result = await qualifyMock(2, { missingLive: true });
+ assert.match(result.error?.message ?? '', /not visible/);
+ assert.equal(result.result, undefined);
+ assert.equal(result.remainingTables, 0);
+});
+test('source code no longer substitutes a post-closure write for a concurrent snapshot test', () => {
+ assert.doesNotMatch(source, /tables\.slice\(0, 2\)/);
+ assert.match(source, /await Promise\.all\(Array\.from\(\{ length: profile\.writers \}/);
+ assert.match(source, /postExportWrites: snapshotResult\.postExportWrites/);
+});
diff --git a/tests/qualify-test-execution.test.js b/tests/qualify-test-execution.test.js
new file mode 100644
index 00000000..9d4d569c
--- /dev/null
+++ b/tests/qualify-test-execution.test.js
@@ -0,0 +1,37 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { assertExecutedTap } from '../scripts/qualify/assert-test-execution.js';
+
+const make = ({ tests = 2, pass = 2, fail = 0, cancelled = 0, skipped = 0, todo = 0, entries = ['ok 1 - first', 'ok 2 - second'] } = {}) =>
+ ['TAP version 13', ...entries, '# tests ' + tests, '# pass ' + pass, '# fail ' + fail,
+ '# cancelled ' + cancelled, '# skipped ' + skipped, '# todo ' + todo].join('\n');
+
+test('actual TAP with executed passing cases is accepted', () => {
+ const result = assertExecutedTap(make(), { minimumTests: 2 });
+ assert.equal(result.status, 'EXECUTED_ALL_PASS');
+ assert.equal(result.tests, 2);
+});
+test('a pass exit status with zero actual tests is rejected', () => {
+ assert.throws(() => assertExecutedTap(make({ tests: 0, pass: 0, entries: [] })), /Insufficient/);
+});
+test('all-skipped and partially skipped suites never count as qualified', () => {
+ for (const transcript of [
+ make({ pass: 0, skipped: 2, entries: ['ok 1 - no db # SKIP', 'ok 2 - no db # SKIP'] }),
+ make({ pass: 1, skipped: 1, entries: ['ok 1 - real', 'ok 2 - skip # SKIP'] })
+ ]) assert.throws(() => assertExecutedTap(transcript), /skipped/);
+});
+test('claimed PASS cannot override failed/cancelled/TODO or missing tests', () => {
+ for (const transcript of [
+ make({ pass: 1, fail: 1, entries: ['ok 1 - yes', 'not ok 2 - fail'] }),
+ make({ pass: 1, cancelled: 1 }),
+ make({ pass: 1, todo: 1 }),
+ make({ pass: 1 }),
+ make().replace('# pass 2', '')
+ ]) assert.throws(() => assertExecutedTap(transcript));
+});
+test('fake summaries with no test entries and partial transcripts are rejected', () => {
+ assert.throws(() => assertExecutedTap(make({ entries: [] })), /No completed/);
+ assert.throws(() => assertExecutedTap('TAP version 13\nok 1 - unresolved'), /summary/);
+ assert.throws(() => assertExecutedTap(make().replace('TAP version 13', '')), /header/);
+ assert.throws(() => assertExecutedTap(make() + '\n# pass 2'), /ambiguous/);
+});
diff --git a/tests/spoold.test.js b/tests/spoold.test.js
index db895d0b..ee1e9764 100644
--- a/tests/spoold.test.js
+++ b/tests/spoold.test.js
@@ -161,3 +161,43 @@ test('spoold drives cutover arming and commit against a real service', async ()
await rm(dir, { recursive: true, force: true });
}
});
+
+test('strict scoped loopback HTTP refuses cross-migration read and mutation before dispatch', async () => {
+ const calls = [];
+ const service = {
+ status: async id => { calls.push(['status',id]); return {id}; },
+ run: async req => { calls.push(['run',req.migrationId]); return {id:req.migrationId}; },
+ abortCutover: async id => { calls.push(['abort',id]); return {id}; }
+ };
+ const identityToken = 'S'.repeat(32);
+ const daemon = createSpoolDaemon({service, requireMigrationScopes:true, localIdentities:[{
+ token:identityToken, principal:'operator:alice', commands:['status','run','abort-cutover'],
+ migrationIds:['migration-A']
+ }]});
+ const address = await daemon.listen(0);
+ try {
+ for(const [body,expected] of [
+ [{command:'status',migrationId:'migration-B'},403],
+ [{command:'run',request:{principal:'operator:alice',migrationId:'migration-B'}},403],
+ [{command:'abort-cutover',migrationId:'migration-B'},403],
+ [{command:'run',request:{principal:'operator:bob',migrationId:'migration-A'}},403],
+ [{command:'run',request:{principal:'operator:alice',migrationId:'migration-A'},migrationId:'migration-B'},403],
+ [{command:'status',migrationId:'migration-A'},200],
+ [{command:'run',request:{principal:'operator:alice',migrationId:'migration-A'}},200]
+ ]) {
+ const actual = await request({port:address.port,token:identityToken,body});
+ assert.equal(actual.status,expected,JSON.stringify(body));
+ }
+ assert.deepEqual(calls,[['status','migration-A'],['run','migration-A']]);
+ } finally { await daemon.close(); }
+});
+
+test('strict scoped daemon refuses a single shared legacy token or missing scopes at startup', () => {
+ const service={status:async()=>null};
+ assert.throws(()=>createSpoolDaemon({service,token:TOKEN,requireMigrationScopes:true}),{
+ code:'INVALID_DAEMON_CONFIG'
+ });
+ assert.throws(()=>createSpoolDaemon({service,requireMigrationScopes:true,
+ localIdentities:[{token:'X'.repeat(32),principal:'operator:alice',commands:['status'] }]
+ }),{code:'INVALID_DAEMON_CONFIG'});
+});