geneseed 3.1.1 → 3.1.3

package/js/build/stubs.mjs

@@ -0,0 +1,256 @@
+/**
+ * The files an emit CREATES WHEN THEY ARE ABSENT and never touches again — context, wiki,
+ * user rules, excludes, profile, the bundle's .gitignore, the memory and notebook indexes.
+ *
+ * Every stub is a literal here and an `ensure*` beside it, and the pairing is the contract:
+ * the writer checks first and returns without writing when the file exists, because these are
+ * the USER's files from the moment they exist. A stub body is bytes a recorded corpus compares
+ * — changing one is a product change, not a tidy-up.
+ */
+import path from 'node:path';
+import { writeText } from '../lib/fs.mjs';
+import { jsonDumpsIndent } from '../lib/json.mjs';
+import { isDir } from './emit-common.mjs';
+import { existsSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// Seeded stubs. Written once into the bundle and NEVER overwritten — each holds
+// something the user owns. Duplicated from `_build_render.py` rather than read from a
+// shared file: the parity gate drives both sides, so drift surfaces as a failing cell
+// instead of as two copies rotting apart, and a shared file would be a third format to
+// keep in agreement. Backticks are escaped; a raw one would end the literal.
+// ---------------------------------------------------------------------------
+
+/** `_build_render.CONTEXT_STUB`. */
+const CONTEXT_STUB = {
+  _comment: "Point the agent at this project's own documentation. Each entry: 'path' "
+    + "(absolute, or relative to the repo root), 'load' ('eager' = read every "
+    + "session for small always-relevant rules; 'lazy' = read only when the task "
+    + "needs it), and 'description'. This file is host-specific — git-ignore it. "
+    + 'The build creates it once, empty, and never overwrites it.',
+  context: [],
+};
+
+/** `_build_render.WIKI_STUB`. */
+const WIKI_STUB = `\
+// Geneseed wiki.jsonc — declare your machine-wide knowledge base(s) here, typically
+// an Obsidian vault (AGENT.md: the Wiki section). Comments are allowed in this file
+// (JSONC). It is host-specific — never commit it. The build created it once, empty,
+// and will never overwrite it.
+//
+// Each wiki carries:
+//   name         a short label
+//   path         absolute root of the vault (use forward slashes, also on Windows)
+//   description  one line shown to the agent
+//   entries      notes OR folders to load: path relative to the vault root ("." =
+//                the whole vault); load "eager" = read every session, "lazy" =
+//                read on demand; a folder applies its mode to every note beneath
+//                it, a file entry overrides its folder, "exclude" prunes
+//   conventions  the vault's authoring-rules note — read before the first write
+//   inbox        drop folder for notes the agent cannot confidently file
+//   protected    folders the agent must never write to (guard-enforced on OpenCode)
+//
+// Example — copy this object into the "wikis" array below and edit:
+// {
+//   "name": "Brain",
+//   "path": "C:/Users/me/Documents/Brain",
+//   "description": "my machine-wide knowledge base",
+//   "entries": [
+//     { "path": "ARCHITECTURE.md", "load": "eager", "description": "the root map" },
+//     { "path": ".", "load": "lazy" }
+//   ],
+//   "conventions": "STYLE.md",
+//   "inbox": "Inbox/",
+//   "protected": ["Journal/"]
+// }
+{
+  "wikis": []
+}
+`;
+
+/** `_build_render.RULES_FILE`. */
+const RULES_FILE = 'user-rules.md';
+
+/** `_build_render.RULES_STUB`. */
+const RULES_STUB = `\
+# User rules
+
+Your own standing rules. The agent obeys every rule in this file exactly as it
+obeys the laws in AGENT.md §1 — always in force, in every task. A user rule may
+*tighten* a law, never repeal one: where they conflict, the law wins.
+
+Geneseed seeded this file once and will never overwrite it. The laws file is
+regenerated on every update — never edit that one; this file is where your own
+governance lives, and it survives updates, reinstalls, and theme switches.
+Unlike \`context.json\`, it is safe to commit: project rules are meant to travel
+with the repo and bind the whole team.
+
+Keep the set small — every rule here is loaded every session, and a bloated
+rule set dilutes the rules that matter. A durable fact belongs in memory, a
+pointer to documentation belongs in \`context.json\`; only a standing *behaviour*
+belongs here.
+
+Format — one rule per \`## R<n> — Title\` heading, an optional metadata line in
+parentheses, then the rule stated plainly:
+
+    ## R1 — No emoji in commit subjects
+    (scope: project | source: written by hand)
+    Commit subjects are plain text; no emoji, no decorative unicode.
+
+\`trial until: YYYY-MM-DD\` in the metadata line marks a rule on probation —
+usually one promoted from a recurring memory. Review it by that date, then
+graduate it (remove the marker) or demote it back to memory.
+`;
+
+/** `_build_render.EXCLUDES_FILE`. */
+export const EXCLUDES_FILE = 'excludes.json';
+
+/**
+ * `_build_render.EXCLUDES_STUB` — one long line, exactly as Python spells it.
+ *
+ * Exported since P5c because `js/inspect/excludes.mjs` reads it as the single source of the shape a
+ * missing or corrupt `excludes.json` degrades to, exactly as `_harness_exclude._read_excludes`
+ * reads `build.EXCLUDES_STUB` rather than spelling `{"excludes": []}` a second time.
+ */
+export const EXCLUDES_STUB = `\
+{
+  "_comment": "Folders where this global Geneseed install goes dormant (hooks silent, preamble suppressed). Managed by \`harness exclude add|remove|list\`; safe to edit by hand. Paths are absolute.",
+  "excludes": []
+}
+`;
+
+/**
+ * `_build_global._BOB_RULES_STUB` — the workspace shadow stub a PROJECT Bob emit ships.
+ *
+ * Exported since P5c: `harness exclude add` writes the SAME stub into an excluded repo, and
+ * decides ownership on the next `remove` by comparing the file's content to it byte for byte
+ * — so a second spelling here would orphan every stub the other writer created.
+ */
+export const BOB_RULES_STUB = `\
+<!-- geneseed: workspace shadow stub -->
+This project's Geneseed instructions are the repo-root \`AGENTS.md\`, which Bob
+auto-loads. This file exists only to shadow the same-named global Geneseed rules
+file (\`~/.bob/rules/geneseed.md\`) so the global preamble does not stack on top of
+the project's own. Follow the root \`AGENTS.md\`.
+`;
+
+/** `_build_render.PROFILE_FILE`. */
+const PROFILE_FILE = 'PROFILE.md';
+
+/** `_build_render.PROFILE_STUB`. */
+const PROFILE_STUB = `\
+# Your profile
+
+Who you are and how you like to work — so the agent can meet you where you are
+instead of guessing. Every section is optional; delete what you don't want to
+share, add what you do. Geneseed seeded this file once and will never overwrite
+it, so it survives updates, reinstalls, and theme switches.
+
+This is *identity, not rules*. A standing rule the agent must obey belongs in
+\`user-rules.md\` (AGENT.md §1); this file only colours how the agent works — tone,
+depth, defaults. Where the two ever seem to conflict, the rule wins: precedence
+is laws, then user-rules, then this profile.
+
+## Who I am
+
+Role, domains you know deeply, domains you're learning. What you're usually here
+to do.
+
+## How I work
+
+Habits, tools, and environment worth knowing — your stack, your shell, the
+conventions you hold to, the things that reliably annoy you.
+
+## Register preferences
+
+How you like answers pitched: terse or expansive, teach-me or just-do-it, how
+much pushback you want, which language(s) you think in.
+`;
+
+/** `_build_render.BUNDLE_GITIGNORE`. */
+const BUNDLE_GITIGNORE = `\
+# Generated by Geneseed. The rendered harness — AGENT.md, the laws, agents, and
+# skills — is safe to commit; track it if you want it versioned with your project.
+# Only the host-specific / personal files below are kept out of git.
+
+# Project-context manifest — may hold private paths; never commit.
+context.json
+
+# Knowledge-base manifest — holds private machine paths; never commit.
+# (wiki.json is the legacy name from earlier seeds.)
+wiki.jsonc
+wiki.json
+
+# Per-agent model/temperature overrides — host-specific; never commit.
+agent-overrides.json
+
+# Which theme + emit mode + footprint this host last built (local build state, must not travel).
+.geneseed-theme
+.geneseed-emit
+.geneseed-footprint
+.geneseed-srcdirs.json
+
+# memory/ keeps its own .gitignore so learned facts stay on this machine.
+# notebook/ keeps its own .gitignore so the agent's own files stay on this machine.
+`;
+
+// ---------------------------------------------------------------------------
+// Seeded stubs — write-once, never overwrite
+// ---------------------------------------------------------------------------
+
+/** `_build_render.ensure_context_stub`. */
+export function ensureContextStub(out) {
+  const dest = path.join(out, 'context.json');
+  if (!existsSync(dest)) {
+    writeText(dest, `${jsonDumpsIndent(CONTEXT_STUB, { ensureAscii: false })}\n`);
+  }
+}
+
+/** `_build_render.ensure_wiki_stub` — a legacy `wiki.json` counts as present. */
+export function ensureWikiStub(out) {
+  const dest = path.join(out, 'wiki.jsonc');
+  if (!existsSync(dest) && !existsSync(path.join(out, 'wiki.json'))) writeText(dest, WIKI_STUB);
+}
+
+/** `_build_render.ensure_rules_stub`. */
+export function ensureRulesStub(out) {
+  const dest = path.join(out, RULES_FILE);
+  if (!existsSync(dest)) writeText(dest, RULES_STUB);
+}
+
+/** `_build_render.ensure_profile_stub`. */
+export function ensureProfileStub(out) {
+  const dest = path.join(out, PROFILE_FILE);
+  if (!existsSync(dest)) writeText(dest, PROFILE_STUB);
+}
+
+/**
+ * `_build_render.ensure_excludes_stub` — the sovereign-repo list, seeded once and NEVER
+ * overwritten. Reachable only from the Claude-shaped emits, which is why it arrived with
+ * `emitClaudeRender` rather than with the bundle stubs beside it.
+ */
+export function ensureExcludesStub(out) {
+  const dest = path.join(out, EXCLUDES_FILE);
+  if (!existsSync(dest)) writeText(dest, EXCLUDES_STUB);
+}
+
+/** `_build_render.ensure_bundle_gitignore`. */
+export function ensureBundleGitignore(out) {
+  const dest = path.join(out, '.gitignore');
+  if (!existsSync(dest)) writeText(dest, BUNDLE_GITIGNORE);
+}
+
+/** `_build_render.ensure_memory_index` — only inside an EXISTING store dir. */
+export function ensureMemoryIndex(memDir) {
+  if (!isDir(memDir)) return;
+  const idx = path.join(memDir, 'MEMORY.md');
+  if (!existsSync(idx)) writeText(idx, '# Memory Index\n');
+}
+
+/** `_build_render.ensure_notebook_index`. */
+export function ensureNotebookIndex(nbDir) {
+  if (!isDir(nbDir)) return;
+  const idx = path.join(nbDir, 'NOTEBOOK.md');
+  if (!existsSync(idx)) writeText(idx, '# Notebook Index\n');
+}
+

package/js/{themes.mjs → build/themes.mjs}

@@ -11,33 +11,33 @@
  * gate — is where that would be discovered.
  *
  * NEITHER `--sync-themes` NOR `--validate-only` IS REACHABLE FROM ANY CELL. `golden.py`'s
- * `_argv` emits neither flag (argued in situ at `bin/geneseed.mjs`'s dispatch), so the
+ * `_argv` emits neither flag (argued in situ at `bin/build-driver.mjs`'s dispatch), so the
  * acceptance matrix that gates all nine emits is structurally blind to both, and the driver
  * refused them rather than crossing for exactly that reason. The gate is
- * `tests/test_maintainer_tools_parity.py`: a corpus of hand-made theme directories run
- * through BOTH implementations, comparing the printed output, the return value, and the
- * resulting FILE BYTES.
+ * `tests/unit/maintainer_tools.test.mjs`, replaying the frozen recording in
+ * `tests/__snapshots__/sync_themes.json`: a corpus of hand-made theme directories, comparing
+ * the printed output, the return value and the resulting FILE BYTES against what the reference
+ * answered. Nothing can re-record it, so a change here that moves a byte is a product change.
  *
- * WHY THIS MODULE IS NOT `js/doctor.mjs`. `--sync-themes` has no doctor dependency, so it
+ * WHY THIS MODULE IS NOT `js/inspect/doctor.mjs`. `--sync-themes` has no doctor dependency, so it
  * stays on the generator driver where its flag lives — and the driver is under a transitive
  * ban on starting processes, which this module's imports respect. Its sibling
  * `--validate-only` needs the doctor and therefore could not stay; see `cmdValidate`.
  *
- * THE PRIMITIVES ARE BORROWED, NOT REWRITTEN. `pySplitLines`, `pyStripSpace`/`pyLStripSpace`/
- * `pyRStripSpace`, `parseJson`, `pyEq`, `jsonDumpsCompact`, `jsonDumpsIndent`, `readText` and
+ * THE PRIMITIVES ARE BORROWED, NOT REWRITTEN. `splitLines`, `stripWhitespace`/`stripWhitespaceStart`/
+ * `stripWhitespaceEnd`, `parseJson`, `deepEquals`, `jsonDumpsCompact`, `jsonDumpsIndent`, `readText` and
  * `writeText` all already exist and are all already gated. This file's documented failure
  * mode is the same primitive existing twice under two names and the two disagreeing, and
  * `str.strip` and `json.dumps` are precisely the two that would have been re-derived here.
  */
 import path from 'node:path';
 
-import { THEMES } from './checkout.mjs';
-import { themeFiles } from './installs.mjs';
-import { pySplitLines } from './lib/udiff.mjs';
-import {
-  jsonDumpsCompact, jsonDumpsIndent, parseJson, pyEq, pyLStripSpace, pyRStripSpace,
-  pyStripSpace, readText, writeText,
-} from './lib/fs.mjs';
+import { THEMES } from './source.mjs';
+import { themeFiles } from '../hosts/installs.mjs';
+import { splitLines } from '../lib/udiff.mjs';
+import { readText, writeText } from '../lib/fs.mjs';
+import { jsonDumpsCompact, jsonDumpsIndent, parseJson, deepEquals } from '../lib/json.mjs';
+import { stripWhitespaceStart, stripWhitespaceEnd, stripWhitespace } from '../lib/text.mjs';
 
 /**
  * `_build_render._insert_theme_keys` — insert ONLY the missing keys into the theme's existing
@@ -53,7 +53,7 @@ import {
  * caller then falls back to a full re-dump.
  *
  * FOUR PRIMITIVES CARRY THE WHOLE THING, and each is a place the two languages differ:
- *   - `pySplitLines` is `str.splitlines()`, which breaks on U+2028/U+2029 where `split('\\n')`
+ *   - `splitLines` is `str.splitlines()`, which breaks on U+2028/U+2029 where `split('\\n')`
  *     does not — a theme file that acquired one from a paste would be re-lined by Python and
  *     not by a naive port, and the insertion index would then point at a different key;
  *   - the three `strip` spellings are Python's whitespace set, not `String.prototype.trim`'s;
@@ -62,13 +62,13 @@ import {
  *     `AGENT_COLORS`, the only non-string among `_TEMPLATE.json`'s 140 values. `ensureAscii`
  *     is false because the reference passes `ensure_ascii=False`, and 33 template values
  *     carry non-ASCII text that would otherwise be escaped into the committed file;
- *   - `pyEq`, because the safety net compares two `json.loads` results and `===` is identity
+ *   - `deepEquals`, because the safety net compares two `json.loads` results and `===` is identity
  *     for containers — a `===` here would return `null` every time and silently route every
  *     theme through the re-dump fallback, i.e. rewrite all 14 files in full.
  */
 export function insertThemeKeys(raw, theme, tmpl, tmplKeys, missing) {
-  const lines = pySplitLines(raw);
-  if (!lines.length || pyStripSpace(lines[0]) !== '{') return null;
+  const lines = splitLines(raw);
+  if (!lines.length || stripWhitespace(lines[0]) !== '{') return null;
 
   const lineOf = (key) => {
     // `f'  "{key}":'` — raw interpolation, NOT a JSON-escaped key. A theme key carrying a
@@ -92,9 +92,9 @@ export function insertThemeKeys(raw, theme, tmpl, tmplKeys, missing) {
     }
     if (pred === null) {
       // No earlier template key exists in this theme: insert right after `{`.
-      const follows = lines.slice(1).some((ln) => pyLStripSpace(ln).startsWith('"'));
+      const follows = lines.slice(1).some((ln) => stripWhitespaceStart(ln).startsWith('"'));
       lines.splice(1, 0, entry + (follows ? ',' : ''));
-    } else if (pyRStripSpace(lines[pred]).endsWith(',')) {
+    } else if (stripWhitespaceEnd(lines[pred]).endsWith(',')) {
       lines.splice(pred + 1, 0, `${entry},`);
     } else {
       // Predecessor was the last entry: it gains the comma, the new line is last.
@@ -109,7 +109,7 @@ export function insertThemeKeys(raw, theme, tmpl, tmplKeys, missing) {
   try { reparsed = parseJson(newText); } catch { return null; }
   const want = { ...theme };
   for (const k of missing) want[k] = tmpl[k];
-  return pyEq(reparsed, want) ? newText : null;
+  return deepEquals(reparsed, want) ? newText : null;
 }
 
 /**
@@ -122,8 +122,8 @@ export function insertThemeKeys(raw, theme, tmpl, tmplKeys, missing) {
  * default is the checkout's own `themes/`, which is what the driver passes.
  *
  * PRINTS THROUGH A BARE `process.stdout.write`, like the generator's other ~25 print sites and
- * unlike every CLI verb: `bin/geneseed.mjs`'s `main` wraps the whole run in `withPyNewlines`,
- * so a `pyPrint` here would translate a second time and put `\r\r\n` on every line.
+ * unlike every CLI verb: `bin/build-driver.mjs`'s `main` wraps the whole run in `withPlatformNewlines`,
+ * so a `printOut` here would translate a second time and put `\r\r\n` on every line.
  *
  * ONE DELIBERATE DIVERGENCE FROM THE REFERENCE, changed on BOTH sides in this commit: a
  * missing or unreadable `_TEMPLATE.json` used to print and `return 0`, which the CLI maps to
@@ -133,7 +133,7 @@ export function insertThemeKeys(raw, theme, tmpl, tmplKeys, missing) {
  * is what makes the branch gateable at all: `json.JSONDecodeError` and V8's parse error
  * disagree on both wording and offset, so a message carrying `{e}` can never be compared
  * across the two implementations. The PER-THEME unreadable message below keeps its `{e}` and
- * therefore keeps that divergence, matching the convention `js/doctor.mjs` already ships at
+ * therefore keeps that divergence, matching the convention `js/inspect/doctor.mjs` already ships at
  * six sites — a skipped theme is a warning, not the tool's verdict.
  */
 export function syncThemes(themesDir = THEMES) {

package/js/build/version.mjs

@@ -0,0 +1,155 @@
+/**
+ * What version an install carries, and whether the one about to be written is newer.
+ *
+ * `sourceFingerprint` answers "did the sources change?" without reading a version at all;
+ * the rest read, compare and write the release marker, and warn on a downgrade. Split out of
+ * `emit.mjs` because none of it is about emitting — `update` and the doctor ask the same
+ * questions of an install nobody is emitting into.
+ */
+import path from 'node:path';
+import { VERSION_MARKER } from '../hosts/hosts.mjs';
+import { sourceReleaseVersion } from '../hosts/opencode.mjs';
+import { readText, writeText } from '../lib/fs.mjs';
+import { isDir, relPosix, rglobFiles } from './emit-common.mjs';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// Version identity
+// ---------------------------------------------------------------------------
+
+/**
+ * `_build_render.source_fingerprint`.
+ *
+ * Sorted by the ROOT-relative POSIX path as a plain string — NOT `comparePaths`. Python
+ * sorts by an explicit `key=` here rather than by `Path` objects, so this one sort is
+ * case-SENSITIVE on every platform while `sorted(SRC.rglob("*"))` in `render_all` is not.
+ * Two sorts of the same files, two different orders, and only one of them is observable
+ * in the output; reproducing the wrong one changes the fingerprint of every install.
+ */
+export function sourceFingerprint(cfg) {
+  const h = createHash('sha256');
+  const files = [];
+  for (const r of [cfg.src, cfg.themes, cfg.pluginSrc, cfg.workflowSrc]) {
+    if (isDir(r)) files.push(...rglobFiles(r));
+  }
+  const keyed = files.map((p) => [relPosix(cfg.root, p), p]);
+  keyed.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  for (const [rel, p] of keyed) {
+    h.update(Buffer.from(`${rel}\0`, 'utf8'));
+    h.update(readFileSync(p));
+    h.update(Buffer.from([0]));
+  }
+  return h.digest('hex').slice(0, 12);
+}
+
+/**
+ * `_build_render.read_version` — the FINGERPRINT token, which is a different name and a
+ * different value from `read_release_version` right below it. `harness version` and the
+ * status panel both compare this one against `sourceFingerprint`.
+ *
+ * `txt.split()[0] if txt else None`: a marker that is empty or whitespace-only reads as no
+ * version at all, so the caller's candidate walk carries on past it rather than stopping.
+ */
+export function readVersion(dir) {
+  let txt;
+  try {
+    txt = readText(path.join(dir, VERSION_MARKER)).trim();
+  } catch {
+    return null;
+  }
+  // `str.split()` with no argument splits on runs of whitespace AND drops the leading
+  // empties; `String.split(/\s+/)` does not, so an indented marker would yield ''.
+  const first = txt.split(/\s+/).filter(Boolean)[0];
+  return first === undefined ? null : first;
+}
+
+/** `_build_render.read_release_version`. */
+function readReleaseVersion(out) {
+  let txt;
+  try {
+    txt = readText(path.join(out, VERSION_MARKER)).trim();
+  } catch {
+    // Python catches OSError only. A marker that is not valid UTF-8 raises there and
+    // degrades to U+FFFD here (Node's decoder substitutes rather than reporting) — the
+    // same asymmetry already recorded for `agent-overrides.json`, and on no covered path.
+    return null;
+  }
+  const m = /\[release ([^\]]+)\]/.exec(txt);
+  return m ? m[1] : null;
+}
+
+/** `_build_core._parse_version_tuple`. */
+function parseVersionTuple(v) {
+  const parts = v.trim().split('.');
+  if (!parts.length) return null;
+  const out = [];
+  for (const p of parts) {
+    // `str.isdigit()`, not `Number.isInteger(+p)`: '' and '1e2' and ' 1' are all
+    // non-digit to Python, and `+p` accepts every one of them.
+    if (!/^[0-9]+$/.test(p)) return null;
+    out.push(Number(p));
+  }
+  return out;
+}
+
+/**
+ * `_build_core.version_is_newer` — null when either side fails to parse.
+ *
+ * EXPORTED FOR ITS GATE, and the argument belongs here rather than in the test. Its only
+ * caller is `warnIfDowngrade`, one line down, whose whole observable behaviour is "print a
+ * warning or say nothing" — so through the emit face `false` and `null` are the SAME
+ * observation, and six of the nine claims this function makes are invisible. That numeric
+ * comparison beats lexical (`1.10.0` > `1.9.0`), that a short tuple is zero-padded on the
+ * right (`1.2` == `1.2.0`), and that an unparseable side answers `null` rather than `false`
+ * are each a decision with a wrong answer that no cell and no emit can distinguish.
+ *
+ * Nothing else changes: it is the same function, called the same way, from the same one
+ * place. See `tests/unit/lifecycle.test.mjs`.
+ */
+export function versionIsNewer(a, b) {
+  const ta = parseVersionTuple(a);
+  const tb = parseVersionTuple(b);
+  if (ta === null || tb === null) return null;
+  const width = Math.max(ta.length, tb.length);
+  for (let i = 0; i < width; i++) {
+    const x = ta[i] ?? 0;
+    const y = tb[i] ?? 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+/** `_build_render._warn_if_downgrade` — STDOUT, matching the Python. */
+function warnIfDowngrade(cfg, out) {
+  const deployed = readReleaseVersion(out);
+  if (deployed === null) return;
+  const current = sourceReleaseVersion(cfg);
+  if (versionIsNewer(deployed, current)) {
+    process.stdout.write(`[geneseed] WARN: installing older Geneseed ${current} over newer `
+      + `${deployed} at ${out} — did you forget git pull?\n`);
+  }
+}
+
+/** `_build_render.write_version`. */
+export function writeVersion(cfg, out) {
+  warnIfDowngrade(cfg, out);
+  const fp = sourceFingerprint(cfg);
+  const release = sourceReleaseVersion(cfg);
+  // `datetime.date.today().isoformat()` — the LOCAL date. `toISOString()` is UTC and
+  // would stamp tomorrow's date for anyone east of Greenwich after their evening.
+  //
+  // No gate can catch this one, and it is recorded rather than left to be discovered:
+  // both runtimes read their own clock at almost the same instant, so a UTC-vs-local
+  // mutation produces identical bytes except during the hour the two dates disagree.
+  // Mutating it away stays green here for a reason no cell can remove — freezing the
+  // clock across a process boundary is not something the harness can do — which is
+  // exactly why the choice is spelled out instead of relying on the comparison.
+  const d = new Date();
+  const today = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-`
+    + `${String(d.getDate()).padStart(2, '0')}`;
+  writeText(path.join(out, VERSION_MARKER),
+    `${fp} (built ${today}) [release ${release}]\n`);
+  return fp;
+}
+