@north-light/crouter 0.3.281 → 0.3.283

package/dist/core/__tests__/integration/plugin-revalidate.test.js

@@ -0,0 +1,355 @@
+// Contract-seam tests for bundle-plugin revalidation against a stub endpoint.
+// Run with: npm run test:integration
+//
+// Two behaviors whose absence would be SILENT — the package on disk would still
+// be a complete, valid command tree, so nothing fails loudly while the client
+// dispatches against a description the server retired:
+//
+//  1. Round trip — an install stores the served validator; a later check sends
+//     it conditionally, leaves the package untouched on 304, and swaps it on a
+//     200 that carries different bytes.
+//  2. Refetch on miss — the forced refetch a `manifest_stale` answer triggers
+//     reports whether the package actually CHANGED. That boolean is the whole
+//     branch: false means the operation is genuinely gone and the server's own
+//     error stands, true means the retry has a fresher tree to parse against.
+//  3. Recovery from a RENAMED op, end to end and entirely off the wire: the
+//     stub answers the v1 op with a real 400 error envelope carrying
+//     `manifest_stale`, so the flag is parsed by the transport rather than
+//     hand-built. `runCli` renders every other failure itself, so recovery is
+//     unreachable unless this one class escapes it — and from the outside a
+//     rendered error looks identical to a recovered one. Its three legs: the
+//     escape, the refetch-and-replay, and exactly-once.
+//
+// All run against an isolated HOME and a startDir with no `.crouter` ancestor,
+// so no ambient plugin or scope of the developer's machine is reachable.
+import { test, describe, before, beforeEach, afterEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync, readFileSync, realpathSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as tar from 'tar';
+import { resetScopeCache, userScopeRoot } from '../../scope.js';
+import { readState, readConfig } from '../../config.js';
+import { revalidateBundlePlugins, forceRevalidateBundlePlugin } from '../../command-plugins/revalidate.js';
+import { pluginInstall } from '../../../commands/pkg/plugin-manage.js';
+import { runCli } from '../../command.js';
+import { buildRoot } from '../../../build-root.js';
+import { dispatchWithStaleRecovery } from '../../manifest-recovery.js';
+import { CrtrError } from '../../errors.js';
+const PLUGIN = 'revalidate-fixture';
+const ARGV = ['node', 'crtr', 'demo', 'show'];
+/** The positional the fixture leaf echoes back. */
+const FIXTURE_ID = 'fixture-1';
+let isolatedHome;
+let isolatedCwd;
+let prevHome;
+let prevTtl;
+let prevCwd;
+let server;
+let endpoint;
+/** What the stub serves right now, and what every BUNDLE request asked for. */
+let served;
+let requests;
+/** Which generations of the `demo show` op this backend has retired. A call
+ *  against a retired one gets the 400 + `manifest_stale` envelope that drives
+ *  client recovery; any other generation is served normally. */
+let retiredOps;
+/** Every generation the leaf was actually invoked at, in order — `['v1','v2']`
+ *  is one recovery: the stale call, then the replay against the fresh tree. */
+let opCalls;
+before(() => {
+    prevHome = process.env.HOME;
+    prevTtl = process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS;
+    prevCwd = process.cwd();
+});
+beforeEach(async () => {
+    isolatedHome = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-revalidate-home-')));
+    isolatedCwd = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-revalidate-cwd-')));
+    process.env.HOME = isolatedHome;
+    process.chdir(isolatedCwd);
+    resetScopeCache();
+    served = { archive: makeArchive('v1'), etag: '"sha256-v1"' };
+    requests = [];
+    retiredOps = new Set();
+    opCalls = [];
+    server = createServer((req, res) => {
+        const path = (req.url ?? '/').split('?')[0] ?? '/';
+        const op = /^\/(v\d+)\/demo\/(.+)$/.exec(path);
+        if (op !== null) {
+            serveOp(res, op[1], op[2]);
+            return;
+        }
+        if (path !== '/v1/cli/bundle') {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: { code: 'not_found', message: `no route for ${path}` } }));
+            return;
+        }
+        const ifNoneMatch = typeof req.headers['if-none-match'] === 'string' ? req.headers['if-none-match'] : undefined;
+        if (ifNoneMatch === served.etag) {
+            requests.push({ ifNoneMatch, status: 304 });
+            res.writeHead(304, { ETag: served.etag, 'Cache-Control': 'private, no-cache' });
+            res.end();
+            return;
+        }
+        requests.push({ ifNoneMatch, status: 200 });
+        res.writeHead(200, { 'Content-Type': 'application/x-tar', ETag: served.etag, 'Cache-Control': 'private, no-cache' });
+        res.end(Buffer.from(served.archive));
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (address === null || typeof address === 'string')
+        throw new Error('stub server has no TCP address');
+    endpoint = `http://127.0.0.1:${address.port}/v1/cli/bundle`;
+});
+afterEach(async () => {
+    await new Promise((resolve) => server.close(() => resolve()));
+    process.chdir(prevCwd);
+    rmSync(isolatedHome, { recursive: true, force: true });
+    rmSync(isolatedCwd, { recursive: true, force: true });
+});
+after(() => {
+    process.chdir(prevCwd);
+    process.env.HOME = prevHome;
+    if (prevTtl === undefined)
+        delete process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS;
+    else
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = prevTtl;
+    resetScopeCache();
+});
+/** The `demo show` leaf, answered at whichever generation the caller's tree
+ *  parsed the path from. A retired generation gets a real error envelope with
+ *  `manifest_stale` set, so the flag reaches the client through the transport's
+ *  own JSON parse rather than being constructed in the test. */
+function serveOp(res, generation, id) {
+    opCalls.push(generation);
+    if (retiredOps.has(generation)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            error: {
+                code: 'cli_op_unknown',
+                message: `this backend no longer serves "demo show" at ${generation}`,
+                manifest_stale: true,
+                next: 'Refetch the plugin package and re-run.',
+            },
+        }));
+        return;
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ id }));
+}
+/** One archive per generation. `marker` rides the leaf description AND the REST
+ *  path its leaf calls, so the tree unpacked on disk says which generation
+ *  produced it, the two generations are different bytes with different
+ *  validators, and a call made from the OLD tree is distinguishable on the wire
+ *  from the same call made after a swap — which is exactly what a renamed op
+ *  looks like to a backend. */
+function makeArchive(marker) {
+    const commands = {
+        schemaVersion: 1,
+        mounts: [
+            {
+                parent: [],
+                node: {
+                    kind: 'branch',
+                    name: 'demo',
+                    description: `demo commands (${marker})`,
+                    whenToUse: 'you are exercising the revalidation seam',
+                    rootEntry: {
+                        concept: 'a fixture command tree served by the stub endpoint',
+                        description: `demo commands (${marker})`,
+                        whenToUse: 'you are exercising the revalidation seam',
+                    },
+                    summary: `demo commands (${marker})`,
+                    model: 'A fixture tree with one read-only leaf.',
+                    children: [
+                        {
+                            kind: 'leaf',
+                            name: 'show',
+                            description: `show the fixture (${marker})`,
+                            whenToUse: 'inspect the fixture record',
+                            tier: 'important',
+                            summary: `show the fixture record (${marker})`,
+                            params: [{ kind: 'positional', name: 'id', required: true, constraint: 'the fixture id' }],
+                            output: [{ name: 'id', type: 'string', required: true, constraint: 'the echoed fixture id' }],
+                            effects: ['None. Read-only.'],
+                            rest: { method: 'GET', path: `/${marker}/demo/{id}`, params: { id: { in: 'path' } } },
+                        },
+                    ],
+                },
+            },
+        ],
+    };
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-revalidate-tar-'));
+    try {
+        writeFileSync(join(dir, 'bundle.json'), JSON.stringify({ bundleVersion: 1 }));
+        writeFileSync(join(dir, 'commands.json'), JSON.stringify(commands));
+        const pack = tar.create({ sync: true, cwd: dir, portable: true }, ['bundle.json', 'commands.json']);
+        const chunks = [];
+        let chunk;
+        while ((chunk = pack.read()) !== null)
+            chunks.push(chunk);
+        return new Uint8Array(Buffer.concat(chunks));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+async function install() {
+    await pluginInstall.run({ endpoint, name: PLUGIN, scope: 'user' });
+}
+/** The generation of the tree actually unpacked under the user scope. */
+function installedMarker() {
+    const path = join(userScopeRoot(), 'plugins', PLUGIN, 'commands.json');
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    const description = parsed.mounts[0].node.description;
+    return description.slice(description.indexOf('(') + 1, description.indexOf(')'));
+}
+function pluginState() {
+    return readState('user').plugins[PLUGIN] ?? {};
+}
+function installedVersion() {
+    return readConfig('user').plugins[PLUGIN]?.version;
+}
+/** Age out the TTL without waiting one out: the pass measures freshness from
+ *  `checked_at`, so a one-millisecond TTL plus a real pause is due. */
+async function makeDue() {
+    process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '1';
+    await new Promise((resolve) => setTimeout(resolve, 5));
+}
+/** Run a dispatch and collect what the caller would actually have observed:
+ *  what reached stdout (both rendered results and rendered errors go there) and
+ *  whether anything escaped the frame. `process.exitCode` is restored, since a
+ *  rendered error sets it and would otherwise fail the whole test process. */
+async function captured(run) {
+    const chunks = [];
+    const realWrite = process.stdout.write.bind(process.stdout);
+    const realExitCode = process.exitCode;
+    process.stdout.write = ((chunk) => {
+        chunks.push(String(chunk));
+        return true;
+    });
+    let thrown;
+    try {
+        await run();
+    }
+    catch (error) {
+        thrown = error;
+    }
+    finally {
+        process.stdout.write = realWrite;
+        process.exitCode = realExitCode;
+    }
+    return { stdout: chunks.join(''), thrown };
+}
+describe('bundle plugin revalidation', () => {
+    test('an install fills the cache; an unchanged bundle 304s and a changed one swaps the package', async () => {
+        await install();
+        // The install IS the first cache fill: unconditional, and it stores what
+        // the server named for the bytes it unpacked.
+        assert.deepEqual(requests, [{ ifNoneMatch: undefined, status: 200 }]);
+        assert.equal(pluginState().etag, '"sha256-v1"');
+        assert.ok(pluginState().checked_at !== undefined);
+        assert.equal(installedMarker(), 'v1');
+        const firstVersion = installedVersion();
+        // Inside the TTL there is nothing to do, and nothing is asked.
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        await revalidateBundlePlugins(ARGV);
+        assert.equal(requests.length, 1);
+        // Due, unchanged: the request carries the stored validator, the server
+        // answers 304, and the package on disk is left exactly as it was.
+        await makeDue();
+        const beforeCheck = pluginState().checked_at;
+        await revalidateBundlePlugins(ARGV);
+        assert.deepEqual(requests[1], { ifNoneMatch: '"sha256-v1"', status: 304 });
+        assert.equal(installedMarker(), 'v1');
+        assert.equal(installedVersion(), firstVersion);
+        assert.equal(pluginState().etag, '"sha256-v1"');
+        assert.notEqual(pluginState().checked_at, beforeCheck);
+        // Due, changed: the 200 swaps the package, and the new validator replaces
+        // the old one so the next check is conditional on what is now on disk.
+        served = { archive: makeArchive('v2'), etag: '"sha256-v2"' };
+        await makeDue();
+        await revalidateBundlePlugins(ARGV);
+        assert.deepEqual(requests[2], { ifNoneMatch: '"sha256-v1"', status: 200 });
+        assert.equal(installedMarker(), 'v2');
+        assert.notEqual(installedVersion(), firstVersion);
+        assert.equal(pluginState().etag, '"sha256-v2"');
+    });
+    test('a forced refetch reports whether the package changed, ignoring a fresh TTL', async () => {
+        await install();
+        // A TTL the ordinary pass would honor. The forced path must not.
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        // Nothing newer is served: the operation the caller invoked is genuinely
+        // gone, so the refetch reports no change and the server's error stands.
+        assert.equal(await forceRevalidateBundlePlugin(PLUGIN), false);
+        assert.deepEqual(requests[1], { ifNoneMatch: undefined, status: 200 });
+        assert.equal(installedMarker(), 'v1');
+        // A changed package: the retry has a fresher tree to re-parse against.
+        served = { archive: makeArchive('v2'), etag: '"sha256-v2"' };
+        assert.equal(await forceRevalidateBundlePlugin(PLUGIN), true);
+        assert.equal(installedMarker(), 'v2');
+        assert.equal(pluginState().etag, '"sha256-v2"');
+        // A plugin that is not installed is not a recovery path.
+        assert.equal(await forceRevalidateBundlePlugin('absent-plugin'), false);
+    });
+    test('the dispatcher lets a manifest_stale answer off the wire escape, and renders every other failure', async () => {
+        await install();
+        // The pass must not fire underneath these legs: every fetch below is one a
+        // test asked for.
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        retiredOps.add('v1');
+        const root = await buildRoot();
+        const stale = await captured(() => runCli(root, [...ARGV, FIXTURE_ID]));
+        // Rethrown, not rendered: nothing printed, and the frame above holds the
+        // error with the two details recovery needs.
+        assert.equal(stale.stdout, '');
+        const thrown = stale.thrown;
+        assert.ok(thrown instanceof CrtrError, String(thrown));
+        assert.equal(thrown.details?.['manifest_stale'], true);
+        assert.equal(thrown.details?.['plugin'], PLUGIN);
+        assert.deepEqual(opCalls, ['v1']);
+        // Every other failure stays the dispatcher's to report. The same leaf,
+        // missing its required positional, is rendered rather than thrown.
+        const usage = await captured(() => runCli(root, ARGV));
+        assert.equal(usage.thrown, undefined);
+        assert.ok(usage.stdout.includes('id'), usage.stdout);
+    });
+    test('a stale answer refetches the package and re-runs the ORIGINAL argv against the refreshed tree', async () => {
+        await install();
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        // The backend has moved the op on: it retired the generation this client
+        // installed, and now serves a package whose leaf calls the new path.
+        retiredOps.add('v1');
+        served = { archive: makeArchive('v2'), etag: '"sha256-v2"' };
+        const root = await buildRoot();
+        const run = await captured(() => dispatchWithStaleRecovery(root, [...ARGV, FIXTURE_ID]));
+        assert.equal(run.thrown, undefined);
+        // The stale call, one forced bundle fetch, then the replay at the NEW
+        // generation — which only the refreshed tree could have addressed.
+        assert.deepEqual(opCalls, ['v1', 'v2']);
+        assert.deepEqual(requests, [
+            { ifNoneMatch: undefined, status: 200 }, // the install
+            { ifNoneMatch: undefined, status: 200 }, // the forced refetch
+        ]);
+        assert.equal(installedMarker(), 'v2');
+        assert.ok(run.stdout.includes(FIXTURE_ID), run.stdout);
+    });
+    test('a second stale answer is rendered rather than refetched again', async () => {
+        await install();
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        // A backend that keeps answering `manifest_stale` however fresh the package
+        // is. The refetch genuinely changes the tree, so the retry does happen —
+        // and its own stale answer must end the cycle, not restart it.
+        retiredOps = new Set(['v1', 'v2']);
+        served = { archive: makeArchive('v2'), etag: '"sha256-v2"' };
+        const root = await buildRoot();
+        const run = await captured(() => dispatchWithStaleRecovery(root, [...ARGV, FIXTURE_ID]));
+        assert.equal(run.thrown, undefined);
+        assert.deepEqual(opCalls, ['v1', 'v2']);
+        assert.equal(requests.length, 2, 'the install plus exactly ONE forced refetch');
+        assert.equal(installedMarker(), 'v2');
+        // The backend's own second complaint is the answer the caller gets.
+        assert.ok(run.stdout.includes('no longer serves'), run.stdout);
+    });
+});

package/dist/core/__tests__/integration/profile-pause.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/integration/profile-pause.test.js

@@ -0,0 +1,115 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { contextDir } from '../../canvas/paths.js';
+import { getRow } from '../../canvas/canvas.js';
+import { bashJobPaths, bashJobsDir } from '../../bash-jobs.js';
+import { readCursor } from '../../feed/inbox.js';
+import { transition } from '../../runtime/lifecycle.js';
+import { ensureRootProfile, pauseProfile } from '../../profiles/manifest.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+function runningJob(nodeId) {
+    const dir = bashJobsDir(contextDir(nodeId));
+    try {
+        for (const jobId of readdirSync(dir)) {
+            const paths = bashJobPaths(contextDir(nodeId), jobId);
+            if (existsSync(paths.jobRun))
+                return paths;
+        }
+    }
+    catch {
+        // The valve has not created its job directory yet.
+    }
+    return undefined;
+}
+test('profile pause backgrounds real bash, retains its inbox cursor, and recovers after a quick resume without failure', { timeout: 120_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-profile-pause' });
+    try {
+        const profile = ensureRootProfile();
+        const parent = h.fabricateBrokerNode({ lifecycle: 'resident' });
+        const child = await h.spawnHeadlessChild(parent, 'stay available while the profile pauses', { profile: profile.profileId });
+        h.fakeCmd(child, { cmd: 'bash', command: "sh -c 'sleep 2; printf preserved'" });
+        const job = await h.waitFor(() => runningJob(child), { label: 'valve job.run' });
+        assert.ok(existsSync(job.jobRun), 'the bash valve owns the foreground command before pause');
+        const paused = h.cli(null, ['profile', 'pause', profile.profileId]);
+        assert.equal(paused.code, 0, paused.stderr);
+        await h.tick();
+        assert.equal(h.bootCount(child), 1, 'the lifecycle pass while paused launches no replacement');
+        const retained = h.cli(null, ['node', 'message', 'send', '--to', child, 'mail retained while profile is paused']);
+        assert.equal(retained.code, 0, retained.stderr);
+        const retainedEntry = h.inbox(child).find((entry) => entry.data?.['body'] === 'mail retained while profile is paused');
+        assert.ok(retainedEntry, 'the message was durably appended');
+        assert.equal(readCursor(child), undefined, 'pause leaves the durable inbox cursor unadvanced');
+        const resumed = h.cli(null, ['profile', 'resume', profile.profileId]);
+        assert.equal(resumed.code, 0, resumed.stderr);
+        await h.awaitFleetExit(child);
+        assert.ok(existsSync(job.jobBg), 'SIGTERM atomically handed job.run to job.bg');
+        assert.equal(existsSync(job.jobRun), false, 'the foreground valve ownership is gone');
+        await h.waitFor(() => existsSync(job.jobExit), { label: 'background bash completion' });
+        assert.equal(readFileSync(job.jobExit, 'utf8').trim(), '0', 'the handoff command completed after its broker exited');
+        assert.equal(readCursor(child), undefined, 'neither retained message nor background completion advanced the stopped broker cursor');
+        await h.tick();
+        assert.equal(h.bootCount(child), 1, 'the first resumed policy pass only consumes the pause interruption');
+        assert.equal(getRow(child)?.respawn_failures, 0, 'the intentional SIGTERM never counts as a crash');
+        await h.tick();
+        // `#respawn`'s backoff-assessment defers this exact relaunch on its first
+        // assessment: this node's original spawn (`spawnChild`'s direct
+        // `headlessBrokerHost.launch`) never records `launched_at`, so
+        // `decideRespawnAttempt` can never see `last_settled_at > launched_at` on
+        // this first-ever `#respawn` call for the row and always takes the
+        // `respawn_not_before` backoff branch (fleet.ts's RESPAWN_BACKOFF_BASE_MS,
+        // currently 5s) instead of launching. A THIRD tick, issued once real time
+        // has passed that window, finds `respawn_not_before` already set (so
+        // `#respawn` skips reassessment this time) and actually calls `reviveNode`.
+        // Real-time sleep, not a fake clock: `now()` here is the daemon's real
+        // `Date.now`, so only the wall clock — not another tick — advances it.
+        await new Promise((r) => setTimeout(r, 5_500));
+        await h.tick();
+        await h.awaitBoot(child, { minCount: 2, timeoutMs: 30_000 });
+        const deliveries = await h.awaitWake(child, { match: /mail retained while profile is paused/ });
+        assert.ok(deliveries.some((content) => /mail retained while profile is paused/.test(content)), 'the resumed watcher delivers the retained backlog');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+test('profile pause preserves an idle-release row so mail queued during pause wakes it', { timeout: 120_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-profile-pause-idle' });
+    try {
+        const profile = ensureRootProfile();
+        const parent = h.fabricateBrokerNode({ lifecycle: 'resident' });
+        const child = await h.spawnHeadlessChild(parent, 'await ordinary mail', { profile: profile.profileId, lifecycle: 'resident' });
+        transition(child, 'release');
+        const paused = h.cli(null, ['profile', 'pause', profile.profileId]);
+        assert.equal(paused.code, 0, paused.stderr);
+        const queued = h.cli(null, ['node', 'message', 'send', '--to', child, 'ordinary mail queued during pause']);
+        assert.equal(queued.code, 0, queued.stderr);
+        await h.awaitFleetExit(child);
+        const resumed = h.cli(null, ['profile', 'resume', profile.profileId]);
+        assert.equal(resumed.code, 0, resumed.stderr);
+        await h.tick();
+        await h.tick();
+        await h.awaitBoot(child, { minCount: 2, timeoutMs: 60_000 });
+        const deliveries = await h.awaitWake(child, { match: /ordinary mail queued during pause/ });
+        assert.ok(deliveries.some((content) => /ordinary mail queued during pause/.test(content)), 'the idle-release wake is not stranded behind the pause marker');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+test('lifecycle catches a broker that became live after the pause command fast scan', { timeout: 60_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-profile-pause-race' });
+    try {
+        const profile = ensureRootProfile();
+        const parent = h.fabricateBrokerNode({ lifecycle: 'resident' });
+        const child = await h.spawnHeadlessChild(parent, 'broker launched after pause scan', { profile: profile.profileId });
+        pauseProfile(profile.profileId);
+        await h.tick();
+        await h.awaitFleetExit(child);
+        assert.equal(h.bootCount(child), 1, 'the paused lifecycle tick terminates the late live broker instead of leaving it running');
+        assert.equal(getRow(child)?.respawn_failures, 0, 'the late broker interruption has no failure cost');
+    }
+    finally {
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/node-outcome.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/node-outcome.test.js

@@ -0,0 +1,184 @@
+import { after, afterEach, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb, MIGRATIONS } from '../canvas/db.js';
+import { createNode, getRow } from '../canvas/canvas.js';
+import { armOutcomeDelivery, claimOutcomeDelivery, outcomeDeliveryBackoffMs, readOutcomeDelivery, recoverRunningOutcomeDeliveries, settleOutcomeDelivery, } from '../canvas/node-outcome-deliveries.js';
+import { transition } from '../runtime/lifecycle.js';
+import { composeNodeOutcomeDocument } from '../runtime/outcome-document.js';
+import { pushFinal } from '../feed/feed.js';
+import { OUTCOME_PAYLOAD_MAX_BYTES } from '../canvas/types.js';
+let home;
+const priorHome = process.env['CRTR_HOME'];
+function node(nodeId) {
+    return {
+        node_id: nodeId,
+        name: nodeId,
+        created: new Date().toISOString(),
+        cwd: home,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+beforeEach(() => {
+    closeDb();
+    home = mkdtempSync(join(tmpdir(), 'crtr-node-outcome-'));
+    process.env['CRTR_HOME'] = home;
+});
+afterEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    if (priorHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = priorHome;
+});
+test('the terminal outcome latch survives competing terminal transitions and revive', () => {
+    createNode(node('latched'));
+    transition('latched', 'finish');
+    transition('latched', 'cancel');
+    let row = getRow('latched');
+    assert.deepEqual({ kind: row.outcome_kind, reason: row.outcome_reason, revision: row.outcome_revision }, {
+        kind: 'failure', reason: 'finished', revision: 1,
+    });
+    transition('latched', 'revive');
+    row = getRow('latched');
+    assert.equal(row.outcome_at === null, false, 'revive must not clear a latched outcome');
+    assert.equal(row.outcome_revision, 1);
+});
+test('outcome detail keeps only a 500-byte first line', () => {
+    createNode(node('detail'));
+    transition('detail', 'crash', {
+        outcome: { detail: { schema: 'crtr.node-outcome-detail/v1', message: `${'x'.repeat(1_000)}\nignored` } },
+    });
+    const detail = JSON.parse(getRow('detail').outcome_detail_json);
+    assert.equal(Buffer.byteLength(detail.message, 'utf8'), 500);
+    assert.equal(detail.message.includes('\n'), false);
+});
+test('the outcome composer is total and omits an oversized structured result', () => {
+    const meta = node('document');
+    meta.description = 'x'.repeat(2 * 1024);
+    createNode(meta);
+    const document = composeNodeOutcomeDocument({
+        node: meta,
+        outcome: { kind: 'result', reason: 'finalized', at: new Date().toISOString(), revision: 1, detailJson: null },
+        action: { name: 'test-action', payload: { callback: 'one' } },
+        finalReport: 'final.md',
+        structuredResult: { value: 'y'.repeat(300 * 1024) },
+    });
+    assert.ok(Buffer.byteLength(JSON.stringify(document), 'utf8') <= 256 * 1024);
+    assert.equal(Buffer.byteLength(document.node.description, 'utf8') <= 1024, true);
+    assert.equal(document.result?.structuredResult, undefined);
+    assert.equal(document.result?.structuredResultOmitted, true);
+});
+test('the outcome composer caps a failure document with an oversized node name', () => {
+    const meta = node('failure-document');
+    meta.name = 'x'.repeat(300 * 1024);
+    const document = composeNodeOutcomeDocument({
+        node: meta,
+        outcome: { kind: 'failure', reason: 'crashed', at: new Date().toISOString(), revision: 1, detailJson: null },
+        action: { name: 'test-action', payload: { callback: 'one' } },
+    });
+    assert.ok(Buffer.byteLength(JSON.stringify(document), 'utf8') <= 256 * 1024);
+    assert.ok(Buffer.byteLength(document.node.name, 'utf8') <= 1024);
+    assert.equal(document.result, undefined);
+    assert.ok(document.failure);
+});
+test('a canonical final supersedes a prior failure outcome and increments revision', async () => {
+    createNode(node('supersede'));
+    transition('supersede', 'crash');
+    transition('supersede', 'revive');
+    await pushFinal('supersede', 'recovered and finished');
+    const row = getRow('supersede');
+    assert.deepEqual({ kind: row.outcome_kind, reason: row.outcome_reason, revision: row.outcome_revision }, {
+        kind: 'result', reason: 'finalized', revision: 2,
+    });
+    assert.equal(row.outcome_detail_json, null);
+});
+test('outcome delivery rejects an oversized payload before a node is armed', () => {
+    createNode(node('oversized-payload'));
+    assert.throws(() => armOutcomeDelivery({
+        nodeId: 'oversized-payload', actionName: 'test-action', argv: ['/bin/true'], cwd: home, configOrigin: 'test', payload: { value: 'x'.repeat(OUTCOME_PAYLOAD_MAX_BYTES) },
+    }), /exceeds/);
+    assert.equal(readOutcomeDelivery('oversized-payload'), null);
+});
+test('outcome delivery armed after settlement is born pending with its document', () => {
+    createNode(node('settled-delivery'));
+    transition('settled-delivery', 'crash');
+    const delivery = armOutcomeDelivery({
+        nodeId: 'settled-delivery', actionName: 'test-action', argv: ['/bin/true'], cwd: home, configOrigin: 'test', payload: { callback: 'one' }, now: 123,
+    });
+    assert.equal(delivery?.state, 'pending');
+    assert.equal(delivery?.nextAttemptAt, 123);
+    assert.deepEqual(delivery?.document && {
+        schema: delivery.document.schema,
+        outcomeId: delivery.document.outcomeId,
+        action: delivery.document.action,
+    }, {
+        schema: 'crtr.node-outcome/v1',
+        outcomeId: 'settled-delivery:1',
+        action: { name: 'test-action', payload: { callback: 'one' } },
+    });
+});
+test('outcome delivery state is fenced, recoverable, and follows the durable backoff', () => {
+    createNode(node('delivery'));
+    assert.ok(armOutcomeDelivery({
+        nodeId: 'delivery', actionName: 'test-action', argv: ['/bin/true'], cwd: home, configOrigin: 'test', payload: { callback: 'one' }, now: 100,
+    }));
+    transition('delivery', 'crash');
+    assert.equal(readOutcomeDelivery('delivery')?.state, 'pending');
+    assert.ok(readOutcomeDelivery('delivery')?.document, 'the armed row is stamped with its outcome document');
+    const first = claimOutcomeDelivery('delivery', Date.now(), 'daemon-a');
+    assert.equal(first.state, 'running');
+    assert.equal(settleOutcomeDelivery('delivery', first.attempt, 'daemon-b', { state: 'accepted' }, Date.now()), false, 'a stale claimant cannot settle');
+    assert.equal(settleOutcomeDelivery('delivery', first.attempt, 'daemon-a', { state: 'accepted' }, Date.now()), true);
+    assert.equal(readOutcomeDelivery('delivery')?.state, 'accepted');
+    createNode(node('recover'));
+    armOutcomeDelivery({ nodeId: 'recover', actionName: 'test-action', argv: ['/bin/true'], cwd: home, configOrigin: 'test', now: 100 });
+    transition('recover', 'crash');
+    const running = claimOutcomeDelivery('recover', Date.now(), 'daemon-a');
+    assert.equal(running.state, 'running');
+    const recoveredAt = Date.now();
+    assert.equal(recoverRunningOutcomeDeliveries(recoveredAt), 1);
+    assert.deepEqual(readOutcomeDelivery('recover') && {
+        state: readOutcomeDelivery('recover').state,
+        nextAttemptAt: readOutcomeDelivery('recover').nextAttemptAt,
+        claimOwner: readOutcomeDelivery('recover').claimOwner,
+    }, { state: 'pending', nextAttemptAt: recoveredAt, claimOwner: null });
+    assert.equal(outcomeDeliveryBackoffMs(1), 5_000);
+    assert.equal(outcomeDeliveryBackoffMs(2), 10_000);
+    assert.equal(outcomeDeliveryBackoffMs(3), 20_000);
+    assert.equal(outcomeDeliveryBackoffMs(11), 3_600_000);
+    assert.equal(outcomeDeliveryBackoffMs(100), 3_600_000);
+});
+test('v39 migrates a v38 database and backfills finalized and terminal rows', () => {
+    const dbPath = join(home, 'v38.db');
+    mkdirSync(join(home, 'nodes'), { recursive: true });
+    const db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA foreign_keys = ON;');
+    for (const migration of MIGRATIONS.slice(0, 38))
+        migration(db);
+    db.prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, created, final_report, finalized_at, terminal_reason)
+    VALUES (?, ?, 'general', 'base', 'terminal', ?, ?, ?, ?, ?, ?)`)
+        .run('finalized', 'finalized', 'done', home, '2026-01-01T00:00:00.000Z', 'report.md', '2026-01-01T01:00:00.000Z', 'finalized');
+    db.prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, created, terminal_reason)
+    VALUES (?, ?, 'general', 'base', 'terminal', ?, ?, ?, ?)`)
+        .run('dead', 'dead', 'dead', home, '2026-01-02T00:00:00.000Z', 'crashed');
+    MIGRATIONS[38](db);
+    const rows = db.prepare('SELECT node_id, outcome_kind, outcome_reason, outcome_at, outcome_revision FROM nodes ORDER BY node_id').all().map((row) => ({ ...row }));
+    assert.deepEqual(rows, [
+        { node_id: 'dead', outcome_kind: 'failure', outcome_reason: 'crashed', outcome_at: '2026-01-02T00:00:00.000Z', outcome_revision: 1 },
+        { node_id: 'finalized', outcome_kind: 'result', outcome_reason: 'finalized', outcome_at: '2026-01-01T01:00:00.000Z', outcome_revision: 1 },
+    ]);
+    assert.ok(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'node_outcome_deliveries'").get());
+    assert.ok(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = 'idx_nodes_deadline'").get());
+    db.close();
+});