functionalscript 0.39.0 → 0.41.0

package/fjs/cas/evo/proof.f.js

@@ -183,6 +183,87 @@ export const proof = {
         assertEq(subjects.length, 1);
         assertEq(subjects[0], 'doc');
     },
+    // `list()` and `list(true)` partition subjects by the archived flags of
+    // their current heads: a lone root revision carrying `archived: true`
+    // makes its subject archived, one without it leaves the subject active,
+    // and neither subject appears in the other's result.
+    listPartitionsSubjectsByHeadArchivedFlag: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, live] = virtual(state0)(e.add({ parents: [], subject: 'live', snapshot: vecToCBase32(vec8(0x40n)) }));
+        assert(live[0] === 'ok', ['expected the active add to succeed', live]);
+        const [state2, gone] = virtual(state1)(e.add({ parents: [], subject: 'gone', snapshot: vecToCBase32(vec8(0x41n)), archived: true }));
+        assert(gone[0] === 'ok', ['expected the archived add to succeed', gone]);
+        const [state3, active] = virtual(state2)(e.list());
+        assertEq(active.length, 1);
+        assertEq(active[0], 'live');
+        const [, archived] = virtual(state3)(e.list(true));
+        assertEq(archived.length, 1);
+        assertEq(archived[0], 'gone');
+    },
+    // Concurrent heads can disagree about `archived`. One unarchived head
+    // keeps the whole subject active — there is still a head left to build on
+    // — so the subject stays out of the archived-only result.
+    listTreatsDisagreeingHeadsAsActive: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, root] = virtual(state0)(e.add({ parents: [], subject: 'doc', snapshot: vecToCBase32(vec8(0x42n)) }));
+        assert(root[0] === 'ok', ['expected root ok', root]);
+        // The two children differ only in `archived`, which is enough to make
+        // them distinct blobs, hence two concurrent heads of one root.
+        const [state2, kept] = virtual(state1)(e.add({ parents: [root[1]], subject: 'doc' }));
+        assert(kept[0] === 'ok', ['expected the unarchived child ok', kept]);
+        const [state3, dropped] = virtual(state2)(e.add({ parents: [root[1]], subject: 'doc', archived: true }));
+        assert(dropped[0] === 'ok', ['expected the archived child ok', dropped]);
+        const [state4, heads] = virtual(state3)(e.head('doc'));
+        assertEq(heads.length, 2);
+        const [state5, active] = virtual(state4)(e.list());
+        assertEq(active.length, 1);
+        assertEq(active[0], 'doc');
+        const [, archived] = virtual(state5)(e.list(true));
+        assertEq(archived.length, 0);
+    },
+    // `archived` is a property of a revision, not of a subject: a subject
+    // archived at one revision is active again as soon as an unarchived child
+    // demotes that revision out of the head set.
+    listIgnoresArchivedRevisionsThatAreNoLongerHeads: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, root] = virtual(state0)(e.add({ parents: [], subject: 'doc', snapshot: vecToCBase32(vec8(0x45n)), archived: true }));
+        assert(root[0] === 'ok', ['expected the archived root ok', root]);
+        const [state2, revived] = virtual(state1)(e.add({ parents: [root[1]], subject: 'doc' }));
+        assert(revived[0] === 'ok', ['expected the unarchived child ok', revived]);
+        const [state3, active] = virtual(state2)(e.list());
+        assertEq(active.length, 1);
+        assertEq(active[0], 'doc');
+        const [, archived] = virtual(state3)(e.list(true));
+        assertEq(archived.length, 0);
+    },
+    // A subject can end up with no current head at all, and a status is a
+    // statement about heads — so such a subject is neither active nor
+    // archived and belongs to neither result. Nothing verifies that a stored
+    // blob actually hashes to the key it sits under, so a hand-crafted or
+    // corrupt store can present a revision naming its own hash as its parent;
+    // `fixedCas` reproduces exactly that, which a real `fileCas` cannot.
+    listExcludesSubjectWithNoCurrentHeads: () => {
+        const selfHash = vec8(0x43n);
+        const snapshotHash = vecToCBase32(vec8(0x44n));
+        const text = `{"dialect":"${revisionDialect}","subject":"doc","parents":["${vecToCBase32(selfHash)}"],"snapshot":"${snapshotHash}","generation":1}`;
+        const bytes = tryUtf8(text);
+        assert(bytes !== null, 'expected the sample revision text to encode as UTF-8');
+        const cas = fixedCas([[selfHash, bytes]]);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(cas));
+        const e = evo(cas)(cacheKey);
+        const [state1, heads] = virtual(state0)(e.head('doc'));
+        assertEq(heads.length, 0);
+        const [state2, active] = virtual(state1)(e.list());
+        assertEq(active.length, 0);
+        const [, archived] = virtual(state2)(e.list(true));
+        assertEq(archived.length, 0);
+    },
     // Adding the exact same revision twice yields the same (deduplicated)
     // content hash and must not duplicate the head entry.
     addRevisionIdempotentOnDuplicateContent: () => {
@@ -518,7 +599,7 @@ export const proof = {
     // A raw CAS write (e.g. `cas_add`) of valid revision content is folded
     // into the cache exactly as `addRevision` would, without going through
     // `evo.add` — this is what keeps `cas_add` and `evo_add` writes to the
-    // same store consistent (see `fjs/cas/mcp`).
+    // same store consistent (see `fjs/mcp`).
     syncRevisionFoldsValidRevisionIntoCache: () => {
         const c = fileCas(sha256)(home);
         const [state0, cacheKey] = virtual(emptyState)(initEvo(c));

package/fjs/ci/config/module.f.d.ts

@@ -1,7 +1,6 @@
 /**
  * Centralized version pins and OS images used by the CI generator: runner
- * images, tool versions (Bun, Deno, Playwright, Rust, Node, Wasmtime, Wasmer,
- * TSGO).
+ * images, tool versions (Bun, Deno, Rust, Node, Wasmtime, Wasmer, TSGO).
  *
  * @module
  */
@@ -19,16 +18,19 @@ export declare const images: {
         readonly arm: 'windows-11-arm';
     };
 };
-export declare const functionalscript: '0.38.0';
+export declare const functionalscript: '0.39.0';
 export declare const bun = "1.3.14";
 export declare const deno = "2.9.4";
-export declare const playwright = "1.62.0";
 export declare const node: {
-    readonly default: '26.5.0';
-    readonly node22: '22.23.1';
+    readonly default: '26.5.1';
+    readonly node22: '22.23.2';
     readonly node24: '24.18.0';
 };
-export declare const wasmtime = "47.0.2";
+export declare const nixpkgs: {
+    readonly ref: 'nixos-26.05';
+    readonly commit: '6d65bfc1bcef2ef39a239d38e577e92a89fb0f07';
+};
+export declare const wasmtime = "47.0.3";
 export declare const wasmer = "7.2.1";
 export declare const actions: {
     readonly 'actions/checkout': 'v7.0.1';
@@ -38,5 +40,6 @@ export declare const actions: {
     readonly 'oven-sh/setup-bun': 'v2.2.0';
     readonly 'bytecodealliance/actions/wasmtime/setup': 'v1.1.3';
     readonly 'wasmerio/setup-wasmer': 'v3.1';
+    readonly 'cachix/install-nix-action': 'v31.11.0';
     readonly 'dtolnay/rust-toolchain': '1.97.1';
 };

package/fjs/ci/config/module.f.js

@@ -1,7 +1,6 @@
 /**
  * Centralized version pins and OS images used by the CI generator: runner
- * images, tool versions (Bun, Deno, Playwright, Rust, Node, Wasmtime, Wasmer,
- * TSGO).
+ * images, tool versions (Bun, Deno, Rust, Node, Wasmtime, Wasmer, TSGO).
  *
  * @module
  */
@@ -24,21 +23,34 @@ export const images = {
 // published FunctionalScript release; do not tie it to package.json's current
 // in-repo version.
 // https://www.npmjs.com/package/functionalscript
-export const functionalscript = '0.38.0';
+export const functionalscript = '0.39.0';
 // https://bun.sh/
 export const bun = '1.3.14';
 // https://deno.com/
 export const deno = '2.9.4';
-// https://www.npmjs.com/package/playwright
-export const playwright = '1.62.0';
+// The Node versions the pinned Nixpkgs snapshot below provides — read from
+// `pkgs/development/web/nodejs/v{22,24,26}.nix` at that commit. Every runtime
+// uses these: `setup-node` on the GitHub-hosted runners and the generated
+// flakes on the Nix jobs, which assert the version they actually get. Nixpkgs
+// usually trails nodejs.org, so bump the snapshot first and copy the versions
+// it offers rather than the latest release.
 // https://nodejs.org/en/download
 export const node = {
-    default: '26.5.0',
-    node22: '22.23.1',
+    default: '26.5.1',
+    node22: '22.23.2',
     node24: '24.18.0',
 };
+// Official Nixpkgs snapshot used by the generated CI flakes. `ref` is the
+// stable channel the commit is accepted from; `commit` is the exact revision
+// every generated `flake.nix` pins. The Node versions above come from this
+// snapshot, so the two move together.
+// https://channels.nixos.org/nixos-26.05/git-revision
+export const nixpkgs = {
+    ref: 'nixos-26.05',
+    commit: '6d65bfc1bcef2ef39a239d38e577e92a89fb0f07',
+};
 // https://github.com/bytecodealliance/wasmtime/releases
-export const wasmtime = '47.0.2';
+export const wasmtime = '47.0.3';
 // https://github.com/wasmerio/wasmer/releases
 export const wasmer = '7.2.1';
 // GitHub Action versions used by CI step builders. The key is the action
@@ -60,6 +72,9 @@ export const actions = {
     'bytecodealliance/actions/wasmtime/setup': 'v1.1.3',
     // https://github.com/wasmerio/setup-wasmer
     'wasmerio/setup-wasmer': 'v3.1',
+    // https://github.com/marketplace/actions/install-nix
+    // Enables the `nix-command` and `flakes` experimental features by default.
+    'cachix/install-nix-action': 'v31.11.0',
     // https://rust-lang.org/ - value is Rust version, not action version
     'dtolnay/rust-toolchain': '1.97.1',
 };

package/fjs/ci/module.f.js

@@ -3,13 +3,13 @@
  *
  * @module
  */
-import { pure, step } from '../effects/module.f.js';
+import { mapStep, step } from '../effects/module.f.js';
 import { access, writeUtf8File } from '../effects/node/module.f.js';
 import { functionalscript, images } from './config/module.f.js';
 import { architecture, os, toSteps, ubuntuArm } from './common/module.f.js';
 import { rustPlatformSteps, rustWasmSteps } from './rust/module.f.js';
-import { nodeMainSteps, nodeVersionJobs } from './node/module.f.js';
-import { playwrightJob } from './playwright/module.f.js';
+import { nodeMainSteps, nodeNixJobs, nodeNixVersionSteps, nodeVersionJobs } from './node/module.f.js';
+import { nixFlakes, nixInstall } from './nix/module.f.js';
 import { bunSteps } from './bun/module.f.js';
 import { denoSteps } from './deno/module.f.js';
 const job = (rust, nodeExtra) => (o) => (a) => {
@@ -22,12 +22,17 @@ const job = (rust, nodeExtra) => (o) => (a) => {
     ];
     return [id, { 'runs-on': image, steps: toSteps(result) }];
 };
+// Every generated flake, across all job families that own one.
+const nixJobs = nodeNixJobs;
+// Temporary: proves the not-yet-migrated flakes still evaluate. Removed once
+// the canonical Node jobs check their own flake by running through it.
+const nixFlakeJob = ubuntuArm([nixInstall, ...nodeNixVersionSteps]);
 const canonicalJobs = (rust) => ({
     ...(rust ? { wasm: ubuntuArm(rustWasmSteps) } : {}),
     deno: ubuntuArm(denoSteps(functionalscript)),
     bun: ubuntuArm(bunSteps(functionalscript)),
     ...nodeVersionJobs(functionalscript),
-    playwright: playwrightJob,
+    'nix-flakes': nixFlakeJob,
 });
 export const ci = ({ nodeExtra }) => step(access('Cargo.toml'), result => {
     const rust = result[0] === 'ok';
@@ -46,6 +51,8 @@ export const ci = ({ nodeExtra }) => step(access('Cargo.toml'), result => {
         },
         jobs,
     };
-    return step(writeUtf8File('.github/workflows/ci.yml', JSON.stringify(gha, null, '  ')), () => pure(0));
+    const workflowWritten = writeUtf8File('.github/workflows/ci.yml', JSON.stringify(gha, null, '  '));
+    const flakesWritten = step(workflowWritten, () => nixFlakes(nixJobs));
+    return mapStep(flakesWritten, () => 0);
 });
 export const main = () => ci({ nodeExtra: () => [] });

package/fjs/ci/nix/module.f.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Generates one self-contained Nix flake per declared CI job.
+ *
+ * Each job gets its own `nix/generated/<id>/flake.nix` pinning the exact
+ * Nixpkgs commit from `../config/module.f.ts` and exposing a single
+ * `devShells.<system>.default` development shell. The files are static and
+ * readable on purpose: no job selection, no shared Nix modules, no helper
+ * libraries.
+ *
+ * @module
+ */
+import { type Effect } from '../../effects/module.f.ts';
+import { type Mkdir, type WriteFile } from '../../effects/node/module.f.ts';
+import { type MetaStep } from '../common/module.f.ts';
+/** A CI job's development environment, one generated flake each. */
+export type NixJob = {
+    /** Generated directory name under `nix/generated`, matching the CI job id. */
+    readonly id: string;
+    /** Nix system of the job's runner, e.g. `aarch64-linux`. */
+    readonly system: string;
+    /** Nixpkgs attribute names made available in the job's shell. */
+    readonly packages: readonly string[];
+    /** Job-local shell initialization, when the job needs one. */
+    readonly shellHook?: string;
+};
+/** Directory owned by this generator. */
+export declare const generatedDirectory: 'nix/generated';
+/**
+ * Serializes a job's flake.
+ *
+ * The serializer rejects invalid *identifiers*, and every identifier in a flake
+ * is written here — a job only contributes attribute names and strings, which
+ * are quoted when they are not identifiers. The unwrap is therefore a totality
+ * assertion, not an input check.
+ */
+export declare const flakeText: (job: NixJob) => string;
+/** Writes one generated flake per job. */
+export declare const nixFlakes: (jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>;
+/** Path a workflow passes to `nix develop`, for the job of the given id. */
+export declare const flakePath: (id: string) => string;
+/** Installs Nix, with `nix-command` and `flakes` enabled by the action's defaults. */
+export declare const nixInstall: MetaStep;
+/** Runs one command inside a job's generated development shell. */
+export declare const nixDevelop: (id: string, command: string) => string;
+/**
+ * Runs a migrated job's whole command sequence in one development shell, so the
+ * shell's packages and environment reach every command without exporting a
+ * profile across GitHub Actions steps.
+ *
+ * The commands are a shell script, joined so a failure stops the rest, and are
+ * quoted as one argument — a command may contain quotes of its own.
+ */
+export declare const nixDevelopAll: (id: string, commands: readonly string[]) => string;
+/**
+ * Checks a job's generated flake end to end: the shell builds, and the Node it
+ * puts on `PATH` is exactly the pinned version. The pinned Nixpkgs commit
+ * already determines the version, so this is the only place the expectation
+ * is stated — the generated flakes stay declarative instead of carrying an
+ * `assert` that restates the commit they pin.
+ */
+export declare const nixVersionCheckStep: (id: string, version: string) => MetaStep;

package/fjs/ci/nix/module.f.js

@@ -0,0 +1,92 @@
+/**
+ * Generates one self-contained Nix flake per declared CI job.
+ *
+ * Each job gets its own `nix/generated/<id>/flake.nix` pinning the exact
+ * Nixpkgs commit from `../config/module.f.ts` and exposing a single
+ * `devShells.<system>.default` development shell. The files are static and
+ * readable on purpose: no job selection, no shared Nix modules, no helper
+ * libraries.
+ *
+ * @module
+ */
+import { forEachStep, mapStep, pure, step } from '../../effects/module.f.js';
+import { mkdir, writeUtf8File } from '../../effects/node/module.f.js';
+import { nixToString } from '../../media/nix/module.f.js';
+import { fromUndefined, unwrap as unwrapNullable } from '../../types/nullable/module.f.js';
+import { unwrap } from '../../types/result/module.f.js';
+import { install, test, uses } from '../common/module.f.js';
+import { nixpkgs } from '../config/module.f.js';
+/** Directory owned by this generator. */
+export const generatedDirectory = 'nix/generated';
+const { commit } = nixpkgs;
+const url = `github:NixOS/nixpkgs/${commit}`;
+const flake = ({ system, packages, shellHook }) => ['set',
+    ['=', ['inputs', 'nixpkgs', 'url'], url],
+    ['=', ['outputs'], ['lambda',
+            ['open-set-pattern', 'nixpkgs'],
+            ['set',
+                ['=', ['devShells', system, 'default'], ['let',
+                        [['=', ['pkgs'], ['apply',
+                                    ['ref', 'import'],
+                                    ['ref', 'nixpkgs'],
+                                    ['set', ['=', ['system'], system]]
+                                ]]],
+                        ['apply',
+                            ['ref', 'pkgs', 'mkShell'],
+                            ['set',
+                                ['=', ['packages'], ['list', ...packages.map(p => ['ref', 'pkgs', p])]],
+                                ...(shellHook === undefined
+                                    ? []
+                                    : [['=', ['shellHook'], ['indented-string', shellHook]]])
+                            ]
+                        ]
+                    ]]
+            ]
+        ]]
+];
+/**
+ * Serializes a job's flake.
+ *
+ * The serializer rejects invalid *identifiers*, and every identifier in a flake
+ * is written here — a job only contributes attribute names and strings, which
+ * are quoted when they are not identifiers. The unwrap is therefore a totality
+ * assertion, not an input check.
+ */
+export const flakeText = (job) => unwrapNullable(fromUndefined(nixToString(flake(job))));
+const writeFlake = (job) => {
+    const directory = `${generatedDirectory}/${job.id}`;
+    const created = mapStep(mkdir(directory, { recursive: true }), unwrap);
+    const written = step(created, () => writeUtf8File(`${directory}/flake.nix`, flakeText(job)));
+    return mapStep(written, unwrap);
+};
+/** Writes one generated flake per job. */
+export const nixFlakes = (jobs) => forEachStep(pure(jobs), writeFlake);
+/** Path a workflow passes to `nix develop`, for the job of the given id. */
+export const flakePath = (id) => `./${generatedDirectory}/${id}`;
+/** Installs Nix, with `nix-command` and `flakes` enabled by the action's defaults. */
+export const nixInstall = install(uses('cachix/install-nix-action'));
+/** Runs one command inside a job's generated development shell. */
+export const nixDevelop = (id, command) => `nix develop ${flakePath(id)} --command ${command}`;
+/**
+ * Wraps a string so a POSIX shell reproduces it exactly. Single quotes protect
+ * every other character, so only the quote itself needs handling: leave the
+ * literal, reopen it, and escape the quote outside (`'` becomes `'\''`).
+ */
+const singleQuoted = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+/**
+ * Runs a migrated job's whole command sequence in one development shell, so the
+ * shell's packages and environment reach every command without exporting a
+ * profile across GitHub Actions steps.
+ *
+ * The commands are a shell script, joined so a failure stops the rest, and are
+ * quoted as one argument — a command may contain quotes of its own.
+ */
+export const nixDevelopAll = (id, commands) => nixDevelop(id, `bash -euo pipefail -c ${singleQuoted(commands.join(' && '))}`);
+/**
+ * Checks a job's generated flake end to end: the shell builds, and the Node it
+ * puts on `PATH` is exactly the pinned version. The pinned Nixpkgs commit
+ * already determines the version, so this is the only place the expectation
+ * is stated — the generated flakes stay declarative instead of carrying an
+ * `assert` that restates the commit they pin.
+ */
+export const nixVersionCheckStep = (id, version) => test({ run: `test "$(${nixDevelop(id, 'node --version')})" = v${version}` });

package/fjs/ci/nix/proof.f.d.ts

@@ -0,0 +1,23 @@
+export declare const proof: {
+    flakeText: {
+        plain: () => void;
+        shellHook: () => void;
+    };
+    nixFlakes: {
+        write: () => void;
+        every: () => void;
+        nodeShellHook: () => void;
+        packages: () => void;
+        quotedPackage: () => void;
+        multiplePackages: () => void;
+    };
+    workflow: {
+        flakePath: () => void;
+        nixDevelop: () => void;
+        nixDevelopAll: {
+            sequence: () => void;
+            quote: () => void;
+        };
+        nixInstall: () => void;
+    };
+};

package/fjs/ci/nix/proof.f.js

@@ -0,0 +1,109 @@
+/**
+ * Proofs for generated CI flakes.
+ *
+ * @module
+ */
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { step } from '../../effects/module.f.js';
+import { readUtf8File } from '../../effects/node/module.f.js';
+import { emptyState, virtual } from '../../effects/node/virtual/module.f.js';
+import { nixpkgs } from '../config/module.f.js';
+import { nodeNixJobs } from '../node/module.f.js';
+import { flakePath, flakeText, generatedDirectory, nixDevelop, nixDevelopAll, nixFlakes, nixInstall, } from './module.f.js';
+const { commit } = nixpkgs;
+const plain = {
+    id: 'node24',
+    system: 'aarch64-linux',
+    packages: ['nodejs_24'],
+};
+const withShellHook = {
+    ...plain,
+    id: 'node22',
+    packages: ['nodejs_22'],
+    shellHook: `export NPM_CONFIG_PREFIX="$HOME/.npm-global"`,
+};
+const plainFlake = `{
+    inputs.nixpkgs.url = "github:NixOS/nixpkgs/${commit}";
+    outputs = { nixpkgs, ... }: {
+        devShells.aarch64-linux.default = let
+            pkgs = import nixpkgs {
+                system = "aarch64-linux";
+            };
+        in
+        pkgs.mkShell {
+            packages = [ pkgs.nodejs_24 ];
+        };
+    };
+}
+`;
+const shellHookFlake = `{
+    inputs.nixpkgs.url = "github:NixOS/nixpkgs/${commit}";
+    outputs = { nixpkgs, ... }: {
+        devShells.aarch64-linux.default = let
+            pkgs = import nixpkgs {
+                system = "aarch64-linux";
+            };
+        in
+        pkgs.mkShell {
+            packages = [ pkgs.nodejs_22 ];
+            shellHook = ''
+                export NPM_CONFIG_PREFIX="$HOME/.npm-global"
+            '';
+        };
+    };
+}
+`;
+const generated = (jobs, id) => {
+    const written = step(nixFlakes(jobs), () => readUtf8File(`${generatedDirectory}/${id}/flake.nix`));
+    const [, [tag, result]] = virtual(emptyState)(written);
+    assert(tag === 'ok', result);
+    return result;
+};
+export const proof = {
+    flakeText: {
+        plain: () => assertEq(flakeText(plain), plainFlake),
+        shellHook: () => assertEq(flakeText(withShellHook), shellHookFlake),
+    },
+    nixFlakes: {
+        write: () => assertEq(generated([plain], plain.id), plainFlake),
+        every: () => {
+            for (const job of nodeNixJobs) {
+                assertEq(generated(nodeNixJobs, job.id), flakeText(job));
+            }
+        },
+        nodeShellHook: () => {
+            const [node22] = nodeNixJobs;
+            assert(node22.shellHook !== undefined, 'expected a Node 22 shell hook');
+            assert(generated(nodeNixJobs, node22.id).includes('$HOME/.npm-global'), 'expected the Node 22 global installation prefix');
+        },
+        packages: () => {
+            for (const { id, packages } of nodeNixJobs) {
+                assertEq(packages.length, 1);
+                assertEq(packages[0], `nodejs_${id.slice('node'.length)}`);
+            }
+        },
+        // Job data only ever reaches quotable positions, so an unusual package
+        // name is escaped rather than rejected.
+        quotedPackage: () => assert(flakeText({ ...plain, packages: ['not an identifier'] })
+            .includes('pkgs."not an identifier"'), 'expected a quoted attribute name'),
+        multiplePackages: () => assert(flakeText({ ...plain, packages: ['nodejs_24', 'git'] })
+            .includes('[ pkgs.nodejs_24 pkgs.git ]'), 'expected both packages in the shell'),
+    },
+    workflow: {
+        // The path a workflow passes to `nix develop` must be the directory the
+        // generator wrote the flake into.
+        flakePath: () => assertEq(flakePath(plain.id), `./${generatedDirectory}/node24`),
+        nixDevelop: () => assertEq(nixDevelop(plain.id, 'node --version'), 'nix develop ./nix/generated/node24 --command node --version'),
+        nixDevelopAll: {
+            sequence: () => assertEq(nixDevelopAll(plain.id, ['npm ci', 'node --test']), `nix develop ./nix/generated/node24 --command bash -euo pipefail -c 'npm ci && node --test'`),
+            // A command carrying its own quote must not end the outer one: the
+            // shell has to see the script back exactly as it was written.
+            quote: () => assertEq(nixDevelopAll(plain.id, [`printf '%s' 'a b'`]), `nix develop ./nix/generated/node24 --command bash -euo pipefail -c 'printf '\\''%s'\\'' '\\''a b'\\'''`),
+        },
+        nixInstall: () => {
+            assertEq(nixInstall.type, 'install');
+            assert(nixInstall.type === 'install'
+                && nixInstall.step.uses?.startsWith('cachix/install-nix-action@') === true, 'expected the pinned Nix installer action');
+        },
+    },
+};

package/fjs/ci/node/module.f.d.ts

@@ -1,6 +1,28 @@
-import { type Jobs, type MetaStep } from '../common/module.f.ts';
+import { type Job, type Jobs, type MetaStep } from '../common/module.f.ts';
+import { type NixJob } from '../nix/module.f.ts';
 export declare const major: (v: string) => string;
 export declare const basicNode: (version: string) => (extra: readonly MetaStep[]) => readonly MetaStep[];
 export declare const platformNodeSteps: (version: string) => readonly MetaStep[];
 export declare const nodeVersionJobs: (version: string) => Jobs;
+export declare const nixSystem: 'aarch64-linux';
+/** Generated development environments for the canonical Node jobs. */
+export declare const nodeNixJobs: readonly NixJob[];
+/**
+ * Version-check steps for the canonical Node jobs' generated flakes, one per
+ * job. Collected into the shared temporary `nix-flakes` job in
+ * `fjs/ci/module.f.ts`.
+ */
+export declare const nodeNixVersionSteps: readonly MetaStep[];
+/**
+ * Temporary job that instantiates every generated flake.
+ *
+ * Nothing else in CI evaluates the generated files, so a broken flake — or one
+ * whose snapshot moved to a different Node — would only surface once a real job
+ * started using it. It deliberately stays separate from the canonical Node jobs:
+ * those keep their current `setup-node` runtime until they are migrated one at a
+ * time. When the last one migrates and this job goes away, each migrated job
+ * must check its own Node version inside the `nix develop` invocation, or the
+ * guarantee is lost.
+ */
+export declare const nodeNixFlakeJob: Job;
 export declare const nodeMainSteps: typeof platformNodeSteps;

package/fjs/ci/node/module.f.js

@@ -6,7 +6,9 @@
  */
 import { node } from '../config/module.f.js';
 import { install, test, ubuntuArm, uses } from '../common/module.f.js';
+import { nixInstall, nixVersionCheckStep } from '../nix/module.f.js';
 export const major = (v) => v.split('.')[0];
+const jobId = (version) => `node${major(version)}`;
 const installNode = (version) => uses('actions/setup-node', { 'node-version': version });
 const nodeInstall = (v) => [
     install(installNode(v)),
@@ -26,6 +28,7 @@ const node22Steps = (version) => [
     ...nodeInstall(node.node22),
     fjsGlobalInstall(version),
     test({ run: 'fjs t' }),
+    test({ run: 'node --test' }),
 ];
 const node24Steps = [
     ...nodeInstall(node.node24),
@@ -41,8 +44,49 @@ const node26Steps = [
 ];
 const nodeJob = (steps) => ubuntuArm(steps);
 export const nodeVersionJobs = (version) => ({
-    [`node${major(node.node22)}`]: nodeJob(node22Steps(version)),
-    [`node${major(node.node24)}`]: nodeJob(node24Steps),
-    [`node${major(node.default)}`]: nodeJob(node26Steps),
+    [jobId(node.node22)]: nodeJob(node22Steps(version)),
+    [jobId(node.node24)]: nodeJob(node24Steps),
+    [jobId(node.default)]: nodeJob(node26Steps),
+});
+// The canonical Node jobs run on the Ubuntu ARM runner.
+export const nixSystem = 'aarch64-linux';
+// Keeps `npm install -g functionalscript` writable and puts the installed `fjs`
+// on `PATH` for the rest of the same `nix develop` invocation.
+const npmGlobalShellHook = `export NPM_CONFIG_PREFIX="$HOME/.npm-global"
+export PATH="$NPM_CONFIG_PREFIX/bin:$PATH"
+mkdir -p "$NPM_CONFIG_PREFIX"`;
+// Versions of the canonical Node jobs, in job order.
+const nixVersions = [node.node22, node.node24, node.default];
+const nixJob = (version) => ({
+    id: jobId(version),
+    system: nixSystem,
+    packages: [`nodejs_${major(version)}`],
 });
+/** Generated development environments for the canonical Node jobs. */
+export const nodeNixJobs = [
+    { ...nixJob(node.node22), shellHook: npmGlobalShellHook },
+    nixJob(node.node24),
+    nixJob(node.default),
+];
+/**
+ * Version-check steps for the canonical Node jobs' generated flakes, one per
+ * job. Collected into the shared temporary `nix-flakes` job in
+ * `fjs/ci/module.f.ts`.
+ */
+export const nodeNixVersionSteps = nixVersions.map(version => nixVersionCheckStep(jobId(version), version));
+/**
+ * Temporary job that instantiates every generated flake.
+ *
+ * Nothing else in CI evaluates the generated files, so a broken flake — or one
+ * whose snapshot moved to a different Node — would only surface once a real job
+ * started using it. It deliberately stays separate from the canonical Node jobs:
+ * those keep their current `setup-node` runtime until they are migrated one at a
+ * time. When the last one migrates and this job goes away, each migrated job
+ * must check its own Node version inside the `nix develop` invocation, or the
+ * guarantee is lost.
+ */
+export const nodeNixFlakeJob = ubuntuArm([
+    nixInstall,
+    ...nodeNixVersionSteps,
+]);
 export const nodeMainSteps = platformNodeSteps;

package/fjs/ci/node/proof.f.d.ts

@@ -0,0 +1,3 @@
+export declare const proof: {
+    basicNode: () => void;
+};

package/fjs/ci/node/proof.f.js

@@ -0,0 +1,17 @@
+import { basicNode } from './module.f.js';
+import { test } from '../common/module.f.js';
+import { assertEq } from '../../asserts/module.f.js';
+export const proof = {
+    basicNode: () => {
+        const extra = [test({ run: 'echo extra' })];
+        const steps = basicNode('22.0.0')(extra);
+        assertEq(steps.length, 3);
+        const [setupNode, npmCi, extraStep] = steps;
+        assertEq(setupNode.type, 'install');
+        assertEq(setupNode.type === 'install' ? setupNode.step.uses : undefined, 'actions/setup-node@v7.0.0');
+        assertEq(setupNode.type === 'install' ? setupNode.step.with?.['node-version'] : undefined, '22.0.0');
+        assertEq(npmCi.type, 'test');
+        assertEq(npmCi.type === 'test' ? npmCi.step.run : undefined, 'npm ci');
+        assertEq(extraStep, extra[0]);
+    },
+};