@celilo/cli 1.12.0 → 1.14.0

package/src/services/module-instances.ts

@@ -1,22 +1,35 @@
 /**
- * Instance identity (openspec/changes/submodules, D2 and D4).
+ * Instance identity and the on-disk shape of an instance
+ * (openspec/changes/submodules, D2 and D4).
  *
- * A parent module addresses the instances it owns by an opaque key it chose.
+ * Two jobs, both small and both load-bearing.
+ *
+ * **Identity.** A parent addresses its instances by an opaque key it chose.
  * celilo addresses them by a `modules.id`, because an instance IS a module row,
  * and that is what lets every reader keyed on `moduleId` keep working. This
  * file is the single place those two names meet, so the mapping cannot drift.
  *
- * The rest of the submodules mechanism (the symlink farm an instance's install
- * is, the deploy-worker capability, the lifecycle) is not here. This is the
- * identity and the ownership question, landed ahead of it because
- * `hook-process-boundary` stage 3 needs `ownedSystemModuleIds` and nothing else
- * from that change.
+ * **Layout.** An instance directory is real and private, holding only
+ * `generated/`, with the submodule's authored subtrees symlinked in. That keeps
+ * `join(sourcePath, 'generated')` true (the invariant nine call sites already
+ * depend on) while giving each instance somewhere of its own to be written to.
+ *
+ * The alternative, pointing `sourcePath` at the shared submodule directory,
+ * looks cleaner and is not. Hooks run with the module directory as their root
+ * and WRITE into it (`browser.ts` puts screenshots there, `module build` uses it
+ * as cwd), so N instances would land on top of each other. Copying instead is
+ * out on size: a module is about 20MB, nearly all of it the bundled hook closure
+ * that celilo#173 makes load-bearing, against about 72KB of authored source.
  */
 
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { lstat, mkdir, readdir, readlink, rm, symlink } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
-import { moduleInstances } from '../db/schema';
+import { type InstanceState, moduleInstances } from '../db/schema';
+import { SUBMODULES_DIR } from '../manifest/validate';
 
 /**
  * Bits of hash in a derived instance id, as hex characters.
@@ -28,14 +41,19 @@ import { moduleInstances } from '../db/schema';
  */
 const INSTANCE_ID_HASH_CHARS = 12;
 
+/** Entries an instance never links, because it owns its own copy or none. */
+const NOT_SYMLINKED = new Set(['generated', 'screenshots', 'cookies.json', 'checksums.json']);
+
+/** The one subdirectory of an instance that is real rather than a link. */
+export const INSTANCE_GENERATED_DIR = 'generated';
+
 /**
  * The `modules.id` an instance runs as.
  *
  * Derived rather than supplied, for two reasons. The parent's key is opaque and
  * may be anything (D2 forbids celilo interpreting it), while `modules.id` must
- * be kebab-case. And identity is the TRIPLE of parent, submodule and key, so
- * the first two have to be inside the hash, or two parents using the same key
- * would collide.
+ * be kebab-case. And identity is the TRIPLE, so the parent and submodule have to
+ * be inside the hash, or two parents using the same key would collide.
  *
  * Deterministic: the same triple always yields the same id, which is what makes
  * an instantiate safe to retry.
@@ -56,6 +74,191 @@ export function deriveInstanceModuleId(
   return `${parentId}-${submodule}-${digest}`;
 }
 
+/** Where a parent's shared submodule source lives inside its own install. */
+export function submoduleSourcePath(parentSourcePath: string, submodule: string): string {
+  return join(parentSourcePath, SUBMODULES_DIR, submodule);
+}
+
+/**
+ * Which entries of a submodule's source get symlinked into an instance.
+ *
+ * Pure, so the decision is testable without a filesystem. `generated/` is
+ * excluded because the instance owns its own. The derived hook outputs
+ * (`screenshots/`, `cookies.json`) are excluded because linking them would put
+ * every instance's writes back into one shared place, which is the failure this
+ * layout exists to prevent.
+ */
+export function planInstanceLinks(submoduleEntries: string[]): string[] {
+  return submoduleEntries.filter((entry) => !NOT_SYMLINKED.has(entry)).sort();
+}
+
+/**
+ * Create or repair an instance's symlink farm.
+ *
+ * Idempotent, and deliberately a full converge rather than a create. A submodule
+ * that gains a top-level directory in a later version would otherwise leave
+ * every existing instance stale, so this runs on instantiate AND on parent
+ * update. A link pointing somewhere else is replaced rather than left, because a
+ * repointed link is the one integrity property unique to instances.
+ *
+ * Returns the entries linked, so a caller can report what changed.
+ */
+export async function buildInstanceLinkFarm(opts: {
+  instancePath: string;
+  submodulePath: string;
+}): Promise<string[]> {
+  const { instancePath, submodulePath } = opts;
+
+  if (!existsSync(submodulePath)) {
+    throw new Error(
+      `Cannot build an instance at ${instancePath}: its submodule source ${submodulePath} does not exist. The parent's install is incomplete.`,
+    );
+  }
+
+  await mkdir(instancePath, { recursive: true });
+  await mkdir(join(instancePath, INSTANCE_GENERATED_DIR), { recursive: true });
+
+  const wanted = planInstanceLinks(await readdir(submodulePath));
+
+  for (const entry of wanted) {
+    const linkPath = join(instancePath, entry);
+    // Relative, so the farm survives the whole data directory being moved or
+    // restored somewhere else, which `celilo restore` does.
+    const target = relative(instancePath, join(submodulePath, entry));
+
+    const existing = await readExistingLink(linkPath);
+    if (existing === target) continue;
+    if (existing !== null) await rm(linkPath, { recursive: true, force: true });
+
+    await symlink(target, linkPath);
+  }
+
+  // Links for entries the submodule no longer has. Left behind they dangle, and
+  // a dangling link reads as a broken install rather than as a stale one.
+  for (const entry of await readdir(instancePath)) {
+    if (entry === INSTANCE_GENERATED_DIR || wanted.includes(entry)) continue;
+    const stale = join(instancePath, entry);
+    if ((await lstat(stale)).isSymbolicLink()) await rm(stale, { force: true });
+  }
+
+  return wanted;
+}
+
+/**
+ * What `linkPath` currently points at, or null if it is absent or not a link.
+ *
+ * A real file or directory where a link belongs returns null so the caller
+ * replaces it. That is the right answer: an instance directory holds nothing of
+ * its own except `generated/`, so anything else there is debris.
+ */
+async function readExistingLink(linkPath: string): Promise<string | null> {
+  if (!existsSync(linkPath)) {
+    // existsSync FOLLOWS links, so a dangling link reports absent. lstat is what
+    // distinguishes "nothing here" from "a link to nowhere", and only the second
+    // needs removing before symlink() will succeed.
+    try {
+      await lstat(linkPath);
+    } catch {
+      return null;
+    }
+    await rm(linkPath, { force: true });
+    return null;
+  }
+  try {
+    return (await lstat(linkPath)).isSymbolicLink() ? await readlink(linkPath) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One link that does not point where it should. */
+export interface LinkViolation {
+  entry: string;
+  expected: string;
+  actual: string | null;
+}
+
+/**
+ * Verify an instance's farm points where it claims.
+ *
+ * The integrity property unique to instances (D4). An instance carries no
+ * authored bytes of its own, so `module verify` has nothing of its own to
+ * checksum: its bytes are the submodule's, which are covered by the parent's
+ * baseline. What IS worth checking, and what nothing else checks, is that the
+ * links still resolve inside the declaring parent and have not been repointed at
+ * somebody else's source.
+ */
+export async function verifyInstanceLinks(opts: {
+  instancePath: string;
+  submodulePath: string;
+}): Promise<LinkViolation[]> {
+  const { instancePath, submodulePath } = opts;
+  const violations: LinkViolation[] = [];
+
+  for (const entry of planInstanceLinks(await readdir(submodulePath))) {
+    const linkPath = join(instancePath, entry);
+    const expected = resolve(submodulePath, entry);
+    const actual = await readExistingLink(linkPath);
+    const resolved = actual === null ? null : resolve(instancePath, actual);
+
+    if (resolved !== expected) {
+      violations.push({ entry, expected, actual: resolved });
+    }
+  }
+
+  return violations;
+}
+
+/** An instance row, joined to what the caller needs to reach its source. */
+export interface InstanceRecord {
+  moduleId: string;
+  parentId: string;
+  submodule: string;
+  instanceKey: string;
+  label: string | null;
+  state: InstanceState;
+}
+
+/**
+ * The instance row for `moduleId`, or null if it names an ordinary module.
+ *
+ * The one question every caller that must treat an instance differently has to
+ * ask, so it lives here rather than being a join each of them writes.
+ */
+export function loadInstance(moduleId: string, db: DbClient): InstanceRecord | null {
+  const row = db
+    .select({
+      moduleId: moduleInstances.moduleId,
+      parentId: moduleInstances.parentId,
+      submodule: moduleInstances.submodule,
+      instanceKey: moduleInstances.instanceKey,
+      label: moduleInstances.label,
+      state: moduleInstances.state,
+    })
+    .from(moduleInstances)
+    .where(eq(moduleInstances.moduleId, moduleId))
+    .get();
+
+  return row ?? null;
+}
+
+/** Every instance a parent owns, oldest first so listings are stable. */
+export function loadInstancesForParent(parentId: string, db: DbClient): InstanceRecord[] {
+  return db
+    .select({
+      moduleId: moduleInstances.moduleId,
+      parentId: moduleInstances.parentId,
+      submodule: moduleInstances.submodule,
+      instanceKey: moduleInstances.instanceKey,
+      label: moduleInstances.label,
+      state: moduleInstances.state,
+    })
+    .from(moduleInstances)
+    .where(eq(moduleInstances.parentId, parentId))
+    .orderBy(moduleInstances.createdAt)
+    .all();
+}
+
 /**
  * Every module id whose systems `moduleId` transitively owns: itself, plus each
  * of its instances.
@@ -66,24 +269,14 @@ export function deriveInstanceModuleId(
  * `IN (...)` set.
  *
  * NOT RECURSIVE, and that is a property of the model rather than a shortcut.
- * Nesting is refused when a parent is imported: a submodule may not declare
- * submodules of its own, so ownership is exactly one level deep by
- * construction. A parent owns instances, and an instance owns nothing. So this
- * is one indexed lookup on `module_instances_parent_idx` rather than a walk,
- * which is what makes it cheap enough to run at hook-invocation time.
- *
- * A recursive walk that happens to terminate and one that cannot recurse are
- * different things, and only the second is safe to call per invocation without
- * reasoning about depth.
+ * Nesting is refused at parent import (`validateSubmoduleManifest`), so
+ * ownership is exactly one level deep by construction: a parent owns instances,
+ * and an instance owns nothing. So this is one indexed lookup on
+ * `module_instances_parent_idx` rather than a walk, which is what makes it
+ * cheap enough to run at hook-invocation time.
  *
  * An instance asking gets only itself, which is correct: an instance provisions
  * its own systems and owns nobody else's.
- *
- * Correct with no instances in existence, which is the state of every fleet
- * until submodules ship: the table is empty, so every module gets `[itself]`,
- * and a caller reaches only the systems it provisioned. That is the answer the
- * allow-list wants today, and it picks up submodule behaviour later with no
- * second edit.
  */
 export function ownedSystemModuleIds(moduleId: string, db: DbClient): string[] {
   const instances = db

package/src/services/restore-from-file.ts

@@ -32,7 +32,7 @@ import {
   rmSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { getDbPath, getMasterKeyPath, getModuleStoragePath } from '../config/paths';
 import { closeDb, getDb } from '../db/client';
@@ -47,6 +47,7 @@ import { decryptFileToFile } from './backup-cipher';
 import { assertCompatibleSchema, parseManifest } from './backup-manifest';
 import { applyCrossModuleWriteRoot, moduleHasCrossModuleRead } from './cross-module-read';
 import { getModuleSystems } from './deployed-systems';
+import { getFleetSshDir } from './fleet-key';
 import {
   completeOperation,
   failOperation,
@@ -376,10 +377,10 @@ export function applyStagedSystemFiles(systemStagingDir: string): StagedSystemAp
   // managed machines; the DB only carries the public half, so without the
   // private half on disk the restored box can't authenticate to the fleet.
   if (existsSync(stagedSsh)) {
-    // The fleet key lives next to the DB (on_install writes it to
-    // dirname(db_path)/.ssh), so follow the DB's location — not getDataDir()
-    // — in case CELILO_DB_PATH points somewhere custom.
-    const liveSshDir = join(dirname(getDbPath()), '.ssh');
+    // One helper, shared with the minting side, so restore and mint cannot
+    // drift to different directories. See getFleetSshDir for why it follows
+    // the DB rather than getDataDir().
+    const liveSshDir = getFleetSshDir();
     mkdirSync(liveSshDir, { recursive: true, mode: 0o700 });
     chmodSync(liveSshDir, 0o700);
     for (const entry of readdirSync(stagedSsh)) {

package/src/services/system-state-stage.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Staging celilo's own state for a backup hook (design D9b of
+ * openspec/changes/hook-process-boundary).
+ *
+ * These assertions used to live in celilo-mgmt-hooks.test.ts, because the
+ * work used to live in celilo-mgmt's on_backup. They moved here with the
+ * code: the hook no longer reads celilo's data directory, the framework
+ * copies it into a staged directory first.
+ */
+
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { snapshotDatabase, stageSystemState } from './system-state-stage';
+
+describe('stageSystemState', () => {
+  let dataDir: string;
+  let stageRoot: string;
+  let masterKeyPath: string;
+
+  beforeEach(() => {
+    dataDir = mkdtempSync(join(tmpdir(), 'celilo-system-state-'));
+    stageRoot = join(dataDir, 'staged');
+    process.env.CELILO_DATA_DIR = dataDir;
+    process.env.CELILO_DB_PATH = join(dataDir, 'celilo.db');
+
+    const seed = new Database(join(dataDir, 'celilo.db'));
+    seed.run('CREATE TABLE probe (id INTEGER PRIMARY KEY, v TEXT)');
+    seed.run("INSERT INTO probe (v) VALUES ('hello')");
+    seed.close();
+
+    masterKeyPath = join(dataDir, 'master.key');
+    writeFileSync(masterKeyPath, 'fake-master-key-32-bytes-padding!');
+    process.env.CELILO_MASTER_KEY_PATH = masterKeyPath;
+  });
+
+  afterEach(() => {
+    process.env.CELILO_DATA_DIR = undefined;
+    process.env.CELILO_DB_PATH = undefined;
+    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('stages the DB snapshot and master.key into the root it is given', () => {
+    const staged = stageSystemState(stageRoot);
+
+    expect(existsSync(join(stageRoot, 'celilo.db'))).toBe(true);
+    expect(existsSync(join(stageRoot, 'master.key'))).toBe(true);
+    expect(staged.masterKeyStaged).toBe(true);
+    expect(staged.root).toBe(stageRoot);
+  });
+
+  it('reports a missing master.key rather than throwing', () => {
+    rmSync(masterKeyPath);
+
+    const staged = stageSystemState(stageRoot);
+
+    expect(staged.masterKeyStaged).toBe(false);
+    expect(existsSync(join(stageRoot, 'master.key'))).toBe(false);
+    // The DB still travels: a snapshot without the key is degraded, not
+    // useless, and refusing here would block backups on a box whose key
+    // path is overridden.
+    expect(existsSync(join(stageRoot, 'celilo.db'))).toBe(true);
+  });
+
+  it('stages the fleet keypair, private half included', () => {
+    const sshDir = join(dataDir, '.ssh');
+    mkdirSync(sshDir, { recursive: true });
+    writeFileSync(join(sshDir, 'id_ed25519'), 'PRIVATE');
+    writeFileSync(join(sshDir, 'id_ed25519.pub'), 'ssh-ed25519 AAAA celilo-fleet');
+
+    const staged = stageSystemState(stageRoot);
+
+    expect(staged.fleetSshStaged).toBe(true);
+    // The DB carries only the public half. Without the private half on disk a
+    // restored box cannot reach machines that already trust the key.
+    expect(readFileSync(join(stageRoot, 'ssh', 'id_ed25519'), 'utf-8')).toBe('PRIVATE');
+  });
+
+  it('reports an absent fleet keypair rather than staging an empty dir', () => {
+    const staged = stageSystemState(stageRoot);
+
+    expect(staged.fleetSshStaged).toBe(false);
+    expect(existsSync(join(stageRoot, 'ssh'))).toBe(false);
+  });
+
+  it('captures LEAN module source: no generated/, no node_modules/, no oversized files', () => {
+    const modSrc = join(dataDir, 'modules', 'caddy');
+    mkdirSync(join(modSrc, 'scripts', 'node_modules', '@celilo'), { recursive: true });
+    mkdirSync(join(modSrc, 'generated', 'terraform'), { recursive: true });
+    mkdirSync(join(modSrc, 'ansible', 'files'), { recursive: true });
+    writeFileSync(join(modSrc, 'manifest.yml'), 'id: caddy');
+    writeFileSync(join(modSrc, 'scripts', 'hook.ts'), '// hook');
+    writeFileSync(join(modSrc, 'generated', 'terraform', 'main.tf'), 'resource {}');
+    writeFileSync(join(modSrc, 'scripts', 'node_modules', '@celilo', 'dep.js'), '// vendored');
+    // A >2MB "compiled binary" sitting in source — skipped by size, because
+    // excluding by directory name misses the ones outside a known build dir.
+    writeFileSync(join(modSrc, 'ansible', 'files', 'server-bin'), Buffer.alloc(3 * 1024 * 1024));
+
+    const staged = stageSystemState(stageRoot);
+    const at = (...parts: string[]) => join(stageRoot, 'module_src', 'caddy', ...parts);
+
+    expect(staged.moduleSourceCount).toBe(1);
+    expect(existsSync(at('manifest.yml'))).toBe(true);
+    expect(existsSync(at('scripts', 'hook.ts'))).toBe(true);
+    expect(existsSync(at('generated'))).toBe(false);
+    expect(existsSync(at('scripts', 'node_modules'))).toBe(false);
+    expect(existsSync(at('ansible', 'files', 'server-bin'))).toBe(false);
+  });
+
+  it('names every file the size cap dropped', () => {
+    const modSrc = join(dataDir, 'modules', 'caddy');
+    mkdirSync(join(modSrc, 'ansible'), { recursive: true });
+    writeFileSync(join(modSrc, 'ansible', 'server-bin'), Buffer.alloc(3 * 1024 * 1024));
+
+    const staged = stageSystemState(stageRoot);
+
+    // No silent caps: a backup that quietly dropped a file reads as complete.
+    expect(staged.skippedLarge).toHaveLength(1);
+    expect(staged.skippedLarge[0]).toContain('caddy/ansible/server-bin');
+    expect(staged.skippedLarge[0]).toContain('3.0MB');
+  });
+});
+
+describe('snapshotDatabase', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-db-snapshot-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('captures rows still sitting in the WAL, uncheckpointed', () => {
+    // The defect this guards: celilo runs the DB in WAL mode, so committed
+    // rows live in celilo.db-wal until a checkpoint folds them into the main
+    // file. A plain copy of the main file produces a snapshot that opens
+    // cleanly and contains NOTHING, and restore then installs it. Swap
+    // serialize() for copyFileSync and this test is the thing that notices.
+    const src = join(dir, 'celilo.db');
+    const live = new Database(src);
+    live.run('PRAGMA journal_mode = WAL');
+    live.run('CREATE TABLE probe (id INTEGER PRIMARY KEY, v TEXT)');
+    for (let i = 0; i < 200; i++) {
+      live.run('INSERT INTO probe (v) VALUES (?)', [`row-${i}`]);
+    }
+
+    const dest = join(dir, 'snapshot.db');
+    snapshotDatabase(src, dest);
+    live.close();
+
+    // Opened read-write, not readonly: the serialized bytes carry WAL journal
+    // mode in their header, so the FIRST open has to be able to create the
+    // -wal/-shm sidecars. Restore opens it read-write too (it copies the file
+    // into place and runs migrations), so this is the real consumer's path.
+    const restored = new Database(dest);
+    const row = restored.query('SELECT COUNT(*) AS n FROM probe').get() as { n: number };
+    restored.close();
+    expect(row.n).toBe(200);
+  });
+});

package/src/services/system-state-stage.ts

@@ -0,0 +1,196 @@
+/**
+ * Staging of celilo's own state for a backup hook
+ * (openspec/changes/hook-process-boundary, design D9b).
+ *
+ * celilo-mgmt's `on_backup` used to reach into celilo's data directory and
+ * copy `master.key`, the DB, the fleet `.ssh` and every other module's
+ * source tree out of it. Measured across the whole hook, it read none of
+ * those bytes: every one was a `copyFileSync` / `cpSync` into `backup_dir`.
+ * It does not need those files in its filesystem view. It needs them to end
+ * up in the backup.
+ *
+ * So the framework copies them into a directory it creates and hands over,
+ * exactly as `materializeCrossModuleRoot` already does for
+ * `cross_module_read`. The hook reads from a staged location it was given,
+ * celilo-mgmt is fully jailed, and "the jail applies to every module" stays
+ * true with no exemption to audit.
+ *
+ * The layout mirrors what `on_backup` puts in the envelope, so the hook's
+ * remaining job is a copy:
+ *
+ *   <root>/celilo.db            WAL-correct snapshot
+ *   <root>/master.key           if present
+ *   <root>/ssh/                 fleet keypair, if present
+ *   <root>/module_src/<id>/     each module's lean source
+ */
+
+import { Database } from 'bun:sqlite';
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { getDbPath, getMasterKeyPath, getModuleStoragePath } from '../config/paths';
+import { getFleetSshDir } from './fleet-key';
+
+/**
+ * Consistent SQLite snapshot via bun:sqlite's serialize().
+ *
+ * celilo runs the DB in WAL mode (apps/celilo/src/db/client.ts), so committed
+ * rows live in `celilo.db-wal` until a checkpoint folds them into the main
+ * file. The main file is routinely a single near-empty page while ALL the
+ * real data (20+ tables, modules, config, secrets) sits in the WAL. A readonly
+ * connection reads THROUGH the WAL, so serialize() captures the full committed
+ * state into one standalone file — exactly what restore needs.
+ *
+ * An earlier implementation shelled out to `sqlite3 ".backup"` and fell back
+ * to a plain copyFileSync when the CLI was absent. On a deb-installed box
+ * there IS no sqlite3 CLI, so the fallback ran — and a plain copy of the main
+ * file alone DROPS the WAL, producing a silently EMPTY backup (restore then
+ * installs an empty DB). bun:sqlite is a Bun built-in and reads the WAL
+ * correctly — no CLI dependency, no data loss.
+ *
+ * This lives in the framework rather than in a module because celilo owns the
+ * schema and `getDbPath()`, and because a bug that silently empties backups
+ * should be fixed once, where it is tested.
+ */
+export function snapshotDatabase(srcPath: string, destPath: string): void {
+  const db = new Database(srcPath, { readonly: true });
+  try {
+    writeFileSync(destPath, db.serialize());
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Directories never worth capturing from a module's source tree. Every one
+ * is rebuilt on deploy (`module build` / `generate`) or re-vendored on
+ * restore (`installScriptDependencies`).
+ */
+const EXCLUDE_DIRS = new Set([
+  'node_modules',
+  'generated',
+  'dist',
+  'coverage',
+  'coverage-raw',
+  '.git',
+  'screenshots',
+  'e2e',
+]);
+
+/**
+ * Size ceiling for a single captured source file.
+ *
+ * celilo module dirs bundle large BUILD artifacts (compiled binaries, built
+ * assets, `*.netapp` packages) — turnip's were ~1.6 GB, which made the
+ * in-memory tar+encrypt segfault. Excluding by directory name misses the ones
+ * that sit outside a known build dir, so a size cap catches them generically.
+ */
+const MAX_SRC_FILE_BYTES = 2 * 1024 * 1024;
+
+export interface StagedSystemState {
+  /** The directory the caller passes to the hook. */
+  root: string;
+  masterKeyStaged: boolean;
+  fleetSshStaged: boolean;
+  moduleSourceCount: number;
+  /** Files the size cap or the `.netapp` rule dropped, named. No silent caps. */
+  skippedLarge: string[];
+}
+
+/**
+ * Populate `rootDir` with celilo's own state and return what landed there.
+ *
+ * Absent pieces are reported rather than thrown on: a box with no fleet key
+ * yet is an ordinary pre-deploy state, and a missing `master.key` is a fact
+ * the caller surfaces to the operator (secrets in the snapshot would be
+ * unreadable on restore) rather than a reason to abort the backup.
+ */
+export function stageSystemState(rootDir: string): StagedSystemState {
+  mkdirSync(rootDir, { recursive: true });
+
+  snapshotDatabase(getDbPath(), join(rootDir, 'celilo.db'));
+
+  // `getMasterKeyPath()` honours CELILO_MASTER_KEY_PATH and otherwise sits
+  // under getDataDir(). The hook used to re-derive it as
+  // `dirname(db_path)/master.key`, which is the same file on a deb install
+  // and a different one whenever CELILO_DB_PATH points elsewhere.
+  const masterKeyPath = getMasterKeyPath();
+  const masterKeyStaged = existsSync(masterKeyPath);
+  if (masterKeyStaged) {
+    copyFileSync(masterKeyPath, join(rootDir, 'master.key'));
+  }
+
+  // The private half too: the DB carries only `ssh.public_key`, so without
+  // it a restored box cannot reach the fleet, and re-keying means
+  // re-authorizing every managed machine.
+  const fleetSshDir = getFleetSshDir();
+  const fleetSshStaged = existsSync(join(fleetSshDir, 'id_ed25519'));
+  if (fleetSshStaged) {
+    cpSync(fleetSshDir, join(rootDir, 'ssh'), { recursive: true });
+  }
+
+  const { moduleSourceCount, skippedLarge } = stageModuleSources(join(rootDir, 'module_src'));
+
+  return { root: rootDir, masterKeyStaged, fleetSshStaged, moduleSourceCount, skippedLarge };
+}
+
+/**
+ * Capture each module's SOURCE (manifest, scripts, ansible, templates) into
+ * `destDir`, minus build artifacts.
+ *
+ * The DB references every module by `source_path`, but the rest of the
+ * envelope carries only DB + state, not module CODE. Restoring onto a fresh
+ * box — especially a different OS, where the source box's absolute
+ * `source_path` does not exist — would otherwise leave it unable to deploy
+ * ANY module, including non-registry ones (e.g. lunacycle) that a
+ * re-import-from-registry cannot recover.
+ *
+ * Reads `getModuleStoragePath()`, which is where `applyStagedSystemFiles`
+ * lays the source back down on restore. The hook derived
+ * `dirname(db_path)/modules` instead — the same directory on a deb install,
+ * and a different one otherwise, so backup and restore could disagree about
+ * where module source lives.
+ */
+function stageModuleSources(destDir: string): {
+  moduleSourceCount: number;
+  skippedLarge: string[];
+} {
+  const modulesSrcDir = getModuleStoragePath();
+  const skippedLarge: string[] = [];
+  let moduleSourceCount = 0;
+
+  if (!existsSync(modulesSrcDir)) {
+    return { moduleSourceCount, skippedLarge };
+  }
+
+  for (const entry of readdirSync(modulesSrcDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const srcModuleDir = join(modulesSrcDir, entry.name);
+    cpSync(srcModuleDir, join(destDir, entry.name), {
+      recursive: true,
+      filter: (src: string) => {
+        const rel = src.slice(srcModuleDir.length).replace(/^\//, '');
+        if (rel === '') return true; // module root
+        if (rel.split('/').some((seg) => EXCLUDE_DIRS.has(seg))) return false;
+        const st = statSync(src);
+        if (st.isDirectory()) return true;
+        if (src.endsWith('.netapp')) return false;
+        if (st.size > MAX_SRC_FILE_BYTES) {
+          skippedLarge.push(`${entry.name}/${rel} (${(st.size / 1048576).toFixed(1)}MB)`);
+          return false;
+        }
+        return true;
+      },
+    });
+    moduleSourceCount += 1;
+  }
+
+  return { moduleSourceCount, skippedLarge };
+}