@hearthlog/tooling 0.1.2 → 0.1.4

package/bin/hearthlog.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// The `hearthlog` command: runs the TypeScript tools through tsx. `build`, `init`, `export`, `check-module`, `artifact`, and
+// The `hearthlog` command: runs the TypeScript tools through tsx. `build`, `init`, `export`, `check-module`, `lock`, `artifact`, and
 // `gallery-public:build` start before a site has generated files (or write their own), so they run alone; the
 // `apple:*` commands run the build and then the tools of `@hearthlog/native` (a dependency of the site, not of this
-// package); `ensure`, `deploy`, `deploy-ledger`, and `split` run the build and then a deploy tool; every other
+// package); `ensure`, `deploy`, and `deploy-ledger` run the build and then a deploy tool; every other
 // command goes to the CLI.
 import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
@@ -33,7 +33,7 @@ if (native) {
 
 // The deploy tools read the site's generated files, so each starts with the build (which does nothing when they are
 // current). They work from a tenant repository because they run from this package, not from the host's scripts.
-const deployTools = { ensure: 'deploy/ensure-tenant.ts', deploy: 'deploy/deploy-tenant.ts', 'deploy-ledger': 'deploy/deploy-ledger.ts', split: 'deploy/split-tenant.ts' };
+const deployTools = { ensure: 'deploy/ensure-tenant.ts', deploy: 'deploy/deploy-tenant.ts', 'deploy-ledger': 'deploy/deploy-ledger.ts' };
 if (deployTools[command]) {
     const site = rest[rest.indexOf('--site') + 1];
     const env = { ...process.env, ...(rest.includes('--site') && site ? { VITE_STOR_TENANT: site } : {}) };
@@ -46,7 +46,8 @@ if (deployTools[command]) {
 if (command === 'plan') {
     const site = rest[rest.indexOf('--site') + 1];
     const env = { ...process.env, ...(rest.includes('--site') && site ? { VITE_STOR_TENANT: site } : {}) };
-    const built = spawnSync(process.execPath, [tsx, source('generate/build-generated.ts'), '--quiet'], { stdio: 'inherit', env }).status ?? 1;
+    // The build's messages go to stderr: `plan --json` writes only the plan to stdout.
+    const built = spawnSync(process.execPath, [tsx, source('generate/build-generated.ts'), '--quiet'], { stdio: ['inherit', 2, 'inherit'], env }).status ?? 1;
     if (built !== 0) process.exit(built);
 }
 
@@ -55,6 +56,7 @@ const entry = {
     init: 'init/init.ts',
     export: 'init/export-tenant.ts',
     'check-module': 'init/check-module.ts',
+    lock: 'tenants/module-lock.ts',
     'gallery-public:build': 'public-workers/build-gallery-public.ts',
     artifact: 'deploy/artifact.ts',
 }[command];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hearthlog/tooling",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "tsx": "^4.23.15",
-    "@hearthlog/contracts": "0.1.2"
+    "@hearthlog/contracts": "0.1.4"
   },
   "bin": {
     "hearthlog": "./bin/hearthlog.mjs"

package/src/init/init.ts

@@ -100,6 +100,7 @@ export function renderSite(options: InitOptions): Array<[string, string]> {
         ["pnpm-workspace.yaml", template("pnpm-workspace.yaml.tmpl")],
         ["patches/sqlocal@0.18.0.patch", template("patches/sqlocal@0.18.0.patch")],
         [".github/workflows/deploy.yml", renderWorkflow(id)],
+        [".github/dependabot.yml", template("dependabot.yml.tmpl")],
         [".gitignore", template("gitignore.tmpl")],
         ["README.md", render(template("README.md.tmpl"), values)],
     ];

package/src/tenants/lock-file.ts

@@ -1,5 +1,8 @@
 /**
- * The lock file's content: which modules a site ships and the exact manifest each was composed from. It
+ * The lock file's content: which modules a site ships and the exact manifest each was composed from. It names no version:
+ * a release that keeps a module's manifest changes nothing here (the package manager's lockfile adopts it), and a release
+ * that moves the contract changes `manifestSha256`, so `hearthlog lock --check` fails until the lock is regenerated and the
+ * diff names the module. It
  * imports nothing generated, so `hearthlog init` can write one before a site has any generated files.
  */
 
@@ -14,7 +17,6 @@ import { modulesForFeatures, type LoadedModule } from "../compose/compose-module
 export interface ModuleLockEntry {
     id: string;
     package: string;
-    version: string;
     /** The site's enabled features this module provides. */
     features: string[];
     /** SHA-256 of the module's `hearthlog.module.json`. */
@@ -32,7 +34,6 @@ export function lockFor(modules: readonly LoadedModule[], features: readonly str
     const entries: ModuleLockEntry[] = modulesForFeatures(modules, features).map(({ directory, manifest }) => ({
         id: manifest.id,
         package: manifest.package,
-        version: manifest.version,
         features: manifest.features.map((feature) => feature.id).filter((id) => features.includes(id)),
         manifestSha256: createHash("sha256").update(readFileSync(join(directory, "hearthlog.module.json"))).digest("hex"),
     }));

package/src/tenants/module-lock.ts

@@ -33,8 +33,17 @@ export async function buildModuleLock(site: Pick<ResolvedSite, "features">): Pro
 export async function moduleLockProblems(site: Pick<ResolvedSite, "id" | "features">): Promise<string[]> {
     const expected = renderModuleLock(await buildModuleLock(site));
     const current = await readFile(moduleLockPath(site.id), "utf8").catch(() => null);
-    if (current === null) return [`tenants/${site.id}/modules.lock.json is missing; run pnpm lock:modules`];
-    return current === expected ? [] : [`tenants/${site.id}/modules.lock.json is stale; run pnpm lock:modules`];
+    if (current === null) return [`tenants/${site.id}/modules.lock.json is missing; run pnpm lock:modules (hearthlog lock)`];
+    // Older locks also recorded each module's version; it is not part of the contract.
+    const withoutVersions = (text: string) => {
+        try {
+            const lock = JSON.parse(text) as { modules?: Array<Record<string, unknown>> };
+            return renderModuleLock({ ...lock, modules: (lock.modules ?? []).map(({ version: _version, ...entry }) => entry) } as unknown as ModuleLock);
+        } catch {
+            return text;
+        }
+    };
+    return withoutVersions(current) === expected ? [] : [`tenants/${site.id}/modules.lock.json is stale; run pnpm lock:modules (hearthlog lock)`];
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/src/tenants/tenant-config.ts

@@ -105,7 +105,7 @@ export interface InfrastructureDefinition {
     ledgerAdminEmail: string;
     /** Shared Cloudflare Access team origin pushed to every site Worker. */
     accessTeamDomain: string;
-    /** The Cloudflare account that holds the shared stack; `tenant:split declare` pins a moved site to it. */
+    /** The Cloudflare account that holds the shared stack. */
     accountId?: string;
     /** Browser application and team-wide SSO lifetimes, in whole hours. */
     accessSessionDuration?: string;

package/src/vite/config.ts

@@ -23,6 +23,16 @@ import {
 
 import { defineConfig, type ProxyOptions, type UserConfig } from 'vite';
 
+/** The `@hearthlog/*` packages the site depends on (the platform and its modules). */
+function hearthlogDependencies(): string[] {
+	try {
+		const manifest = JSON.parse(readFileSync('package.json', 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+		return Object.keys({ ...manifest.dependencies, ...manifest.devDependencies }).filter((name) => name.startsWith('@hearthlog/') && name !== '@hearthlog/generated');
+	} catch {
+		return [];
+	}
+}
+
 function installedVersion(name: string): string {
 	try {
 		return JSON.parse(readFileSync(join('node_modules', name, 'package.json'), 'utf8')).version;
@@ -293,7 +303,9 @@ return defineConfig(({ command, mode }): UserConfig => {
 		},
 	],
 	optimizeDeps: {
-		exclude: ['sqlocal', 'microlighter']
+		// The platform and the modules ship Svelte and TypeScript source; installed from the registry they sit in node_modules,
+		// where the dependency scan cannot resolve their relative imports. They are compiled with the site, not pre-bundled.
+		exclude: ['sqlocal', 'microlighter', ...hearthlogDependencies()]
 	},
 	build: {
 		// Bundle Microlighter's lazy grammars, which Vite skips in dependencies by default.

package/templates/tenant/dependabot.yml.tmpl

@@ -0,0 +1,13 @@
+# Releases of the platform and of the modules arrive as pull requests that change the lockfile (and nothing else, unless a
+# module's contract moved: then `hearthlog lock` rewrites tenants/<id>/modules.lock.json and the diff names the module).
+# The build job of this repository's workflow builds each one; merge it to deploy, with the approval of the environment.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      hearthlog:
+        patterns:
+          - "@hearthlog/*"

package/templates/tenant/github-workflows/deploy.yml.tmpl

@@ -46,7 +46,10 @@ jobs:
           pnpm exec hearthlog gallery-public:build --site {{id}}
           pnpm exec vite build
           pnpm exec hearthlog artifact manifest --site {{id}}
-      # After the build: the plan reads the generated files the build writes.
+      # After the build: the lock and the plan read the generated files the build writes. The lock fails when a module's
+      # contract changed since `tenants/{{id}}/modules.lock.json` was written: run `pnpm exec hearthlog lock` and commit it.
+      - name: Check the module lock
+        run: pnpm exec hearthlog lock --check
       - name: Plan (read-only)
         run: pnpm exec hearthlog plan --site {{id}}
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2

package/src/deploy/copy-tenant.ts

@@ -1,395 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * Copy one tenant into a new tenant on its own stack, with new identities.
- *
- * The source is only read. Both tenants keep working and diverge afterwards;
- * nothing is merged back. See docs/tenant-copy.md for the full runbook.
- *
- *   events  Export the source app through the Ledger administrator API (the
- *           source app's own token is neither needed nor rotated), restore it
- *           into the target Ledger as a new app named after the target site,
- *           with new log IDs, and verify. Event IDs, timestamps, authors,
- *           action grouping, fork lineage, and hidden logs are kept. Writes
- *           `mapping.json` (IDs only, no tokens).
- *   files   Deploy a short-lived copy Worker bound to the source and target
- *           buckets, copy invoice files, Gallery files, and the source app's
- *           Gallery publications with app and log IDs rewritten from the
- *           mapping, compare every object, then delete the Worker.
- *
- * Usage:
- *   pnpm tenant:copy -- events --from alpha --to jst [--allow-skipped-forks]
- *   pnpm tenant:copy -- files --from alpha --to jst --run <directory>
- *
- * Environment: the administrator tokens of both Ledgers (LEDGER_ADMIN_TOKEN or
- * .wrangler/tenants/.admin-token for the shared Ledger, LEDGER_ADMIN_TOKEN_<SITE>
- * or .wrangler/tenants/<id>/.admin-token for a site's own Ledger), optional
- * LEDGER_BASE_URL / LEDGER_BASE_URL_<SITE> overrides, and a wrangler login for
- * `files`.
- */
-
-import { spawn } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { dedicatedLedgerBaseUrl, resolveDedicatedAdminToken } from "./dedicated-ledger.js";
-import { runWrangler } from "./deploy-runner.js";
-import { resolveLedgerAdminToken, resolveLedgerBaseUrl } from "./ledger-credential.js";
-import {
-    infrastructureFor,
-    loadTenantConfig,
-    REPOSITORY_ROOT,
-    siteById,
-    type InfrastructureDefinition,
-    type ResolvedSite,
-} from "../tenants/tenant-config.js";
-import { planFileCopies, validateMapping, type CopyJob, type TenantCopyMapping } from "../tenants/tenant-copy-plan.js";
-import { WRANGLER_BASE } from "../tenants/wrangler-base.js";
-import { ledgerScript } from "./ledger-scripts.js";
-
-const COPY_ROOT = join(REPOSITORY_ROOT, ".wrangler", "tenant-copies");
-const COPY_WORKER_CONFIG = "wrangler.tenant-copy.jsonc";
-
-interface Options {
-    command: "events" | "files" | "help";
-    from: string;
-    to: string;
-    run?: string;
-    allowSkippedForks: boolean;
-}
-
-interface LedgerAccess {
-    baseUrl: string;
-    adminToken: string;
-}
-
-interface AppSummary {
-    id: string;
-    name: string;
-    revokedAt: string | null;
-}
-
-interface LogSummary {
-    id: string;
-    headVersion: number;
-    sourceLogId: string | null;
-    sourceVersion: number | null;
-    hiddenAt: string | null;
-    status: string;
-}
-
-interface OwnedPage { owned: string[]; cursor: string | null }
-interface CopyPage { copied: number; skipped: number; bytes: number; cursor: string | null }
-interface ComparePage { checked: number; problems: string[]; cursor: string | null }
-
-export interface CopyRecord {
-    source: { site: string; appId: string };
-    target: { site: string; appId: string };
-    copiedAt: string;
-    manifestSha256: string;
-    logs: Array<{ sourceLogId: string; targetLogId: string; headVersion: number; hidden: boolean }>;
-    skippedLogIds: string[];
-}
-
-export function parseOptions(argv: string[]): Options {
-    const args = argv.filter((argument) => argument !== "--");
-    const command = args[0];
-    const options: Options = {
-        command: command === "events" || command === "files" ? command : "help",
-        from: "",
-        to: "",
-        allowSkippedForks: false,
-    };
-    for (let index = 1; index < args.length; index += 1) {
-        const argument = args[index];
-        const value = () => {
-            const next = args[index + 1]?.trim();
-            if (!next) throw new Error(`${argument} requires a value`);
-            index += 1;
-            return next;
-        };
-        switch (argument) {
-            case "--from": options.from = value(); break;
-            case "--to": options.to = value(); break;
-            case "--run": options.run = value(); break;
-            case "--allow-skipped-forks": options.allowSkippedForks = true; break;
-            case "--help": case "-h": options.command = "help"; break;
-            default: throw new Error(`Unknown option: ${argument}`);
-        }
-    }
-    if (options.command !== "help" && (!options.from || !options.to)) throw new Error("--from and --to are required");
-    if (options.command === "files" && !options.run) throw new Error("files needs --run <directory> from the events step");
-    return options;
-}
-
-async function ledgerAccess(site: ResolvedSite, shared: InfrastructureDefinition): Promise<LedgerAccess> {
-    if (site.deployment) {
-        const variable = site.id.toUpperCase().replace(/-/g, "_");
-        const adminToken = await resolveDedicatedAdminToken(site.id);
-        if (!adminToken) throw new Error(`No administrator token for the ${site.id} Ledger`);
-        return {
-            baseUrl: process.env[`LEDGER_BASE_URL_${variable}`]?.trim().replace(/\/$/, "") || dedicatedLedgerBaseUrl(site, shared),
-            adminToken,
-        };
-    }
-    const adminToken = await resolveLedgerAdminToken();
-    if (!adminToken) throw new Error("No administrator token for the shared Ledger (LEDGER_ADMIN_TOKEN)");
-    return { baseUrl: resolveLedgerBaseUrl(process.env.LEDGER_BASE_URL, shared.ledgerWorker, shared.workersDevDomain), adminToken };
-}
-
-async function adminApi<T>(ledger: LedgerAccess, route: string): Promise<T> {
-    const response = await fetch(`${ledger.baseUrl}${route}`, { headers: { Authorization: `Bearer ${ledger.adminToken}` } });
-    if (!response.ok) throw new Error(`GET ${route} failed with ${response.status}`);
-    return await response.json() as T;
-}
-
-async function activeApp(ledger: LedgerAccess, name: string): Promise<AppSummary | null> {
-    const { apps } = await adminApi<{ apps: AppSummary[] }>(ledger, "/admin/v1/apps");
-    const matches = apps.filter((app) => app.name === name && app.revokedAt === null);
-    if (matches.length > 1) throw new Error(`Ledger has ${matches.length} active apps named "${name}"`);
-    return matches[0] ?? null;
-}
-
-/** Run the logical backup script; stdout is its JSON result, never shown. */
-function logicalBackup(args: string[], ledger: LedgerAccess): Promise<unknown> {
-    return new Promise((resolvePromise, reject) => {
-        const backup = ledgerScript("logical-backup", args);
-        const child = spawn(backup.command, backup.args, {
-            cwd: REPOSITORY_ROOT,
-            env: { ...process.env, LEDGER_BASE_URL: ledger.baseUrl, LEDGER_ADMIN_TOKEN: ledger.adminToken },
-            stdio: ["ignore", "pipe", "inherit"],
-        });
-        let output = "";
-        child.stdout.on("data", (chunk: Buffer) => { output += chunk.toString("utf8"); });
-        child.on("error", reject);
-        child.on("close", (code) => {
-            if (code !== 0) return reject(new Error(`logical backup ${args[0]} failed with exit code ${code}`));
-            try {
-                resolvePromise(JSON.parse(output));
-            } catch {
-                reject(new Error(`logical backup ${args[0]} printed no JSON result`));
-            }
-        });
-    });
-}
-
-async function copyEvents(options: Options): Promise<void> {
-    const { infrastructure, sites } = await loadTenantConfig();
-    const source = siteById(sites, options.from);
-    const target = siteById(sites, options.to);
-    if (!target.deployment) throw new Error(`Target ${target.id} must run on its own stack (tenants/${target.id}/deployment.json)`);
-    const sourceLedger = await ledgerAccess(source, infrastructure);
-    const targetLedger = await ledgerAccess(target, infrastructure);
-    if (sourceLedger.baseUrl === targetLedger.baseUrl) throw new Error("Source and target use the same Ledger");
-
-    const sourceApp = await activeApp(sourceLedger, source.ledgerAppName);
-    if (!sourceApp) throw new Error(`The source Ledger has no active app named "${source.ledgerAppName}"`);
-    const existing = await activeApp(targetLedger, target.ledgerAppName);
-    if (existing) {
-        throw new Error(
-            `The ${target.id} Ledger already has an app named "${target.ledgerAppName}" (${existing.id}). ` +
-                "A copy only goes into a new app; to redo it, revoke that app first (see docs/tenant-copy.md).",
-        );
-    }
-
-    const run = join(COPY_ROOT, `${target.id}-${new Date().toISOString().replace(/\D/g, "").slice(0, 14)}`);
-    await mkdir(run, { recursive: true, mode: 0o700 });
-    console.log(`Exporting ${source.id} (${sourceApp.id}) through the administrator API...`);
-    const exported = await logicalBackup(["export", "--app", sourceApp.id, "--output", join(run, "export")], sourceLedger) as {
-        manifestSha256: string;
-        skippedLogIds: string[];
-    };
-    if (exported.skippedLogIds.length > 0 && !options.allowSkippedForks) {
-        throw new Error(
-            `Forks still being prepared were skipped: ${exported.skippedLogIds.join(", ")}. ` +
-                "Let them finish and run again, or pass --allow-skipped-forks to copy without them.",
-        );
-    }
-
-    console.log(`Restoring into the ${target.id} Ledger as "${target.ledgerAppName}"...`);
-    const restored = await logicalBackup(["restore", "--input", join(run, "export"), "--name", target.ledgerAppName], targetLedger) as {
-        app: { id: string };
-        manifestSha256: string;
-        logs: Array<{ sourceLogId: string; targetLogId: string }>;
-    };
-    if (restored.manifestSha256 !== exported.manifestSha256) throw new Error("Restore read a different export");
-
-    const record = await verifyEvents(sourceLedger, targetLedger, sourceApp.id, restored.app.id, restored.logs);
-    const result: CopyRecord = {
-        source: { site: source.id, appId: sourceApp.id },
-        target: { site: target.id, appId: restored.app.id },
-        copiedAt: new Date().toISOString(),
-        manifestSha256: exported.manifestSha256,
-        logs: record,
-        skippedLogIds: exported.skippedLogIds,
-    };
-    await writeFile(join(run, "mapping.json"), `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
-    console.log(
-        `\nCopied ${record.length} log(s) into app ${restored.app.id}. Mapping: ${relative(REPOSITORY_ROOT, run)}/mapping.json\n` +
-            `Next: pnpm tenant:copy -- files --from ${source.id} --to ${target.id} --run ${relative(REPOSITORY_ROOT, run)}\n` +
-            `Then give the ${target.id} gateway a token: pnpm ensure:tenant -- --site ${target.id} --rotate-token`,
-    );
-}
-
-/** Heads, lineage, and hidden state match across the mapping; restore already compared every event page. */
-async function verifyEvents(
-    sourceLedger: LedgerAccess,
-    targetLedger: LedgerAccess,
-    sourceAppId: string,
-    targetAppId: string,
-    pairs: ReadonlyArray<{ sourceLogId: string; targetLogId: string }>,
-): Promise<CopyRecord["logs"]> {
-    const sourceLogs = new Map((await adminApi<{ logs: LogSummary[] }>(sourceLedger, `/admin/v1/apps/${sourceAppId}/logs`)).logs.map((log) => [log.id, log]));
-    const targetLogs = new Map((await adminApi<{ logs: LogSummary[] }>(targetLedger, `/admin/v1/apps/${targetAppId}/logs`)).logs.map((log) => [log.id, log]));
-    const mapped = new Map(pairs.map((pair) => [pair.sourceLogId, pair.targetLogId]));
-    if (targetLogs.size !== pairs.length) throw new Error(`Target app has ${targetLogs.size} logs, expected ${pairs.length}`);
-    return pairs.map(({ sourceLogId, targetLogId }) => {
-        const from = sourceLogs.get(sourceLogId);
-        const to = targetLogs.get(targetLogId);
-        if (!from || !to) throw new Error(`Log ${sourceLogId} is missing after the copy`);
-        // The source may have moved on since the export; the copy holds the exported head.
-        if (to.headVersion > from.headVersion) throw new Error(`Log ${targetLogId} is ahead of its source`);
-        const expectedParent = from.sourceLogId ? mapped.get(from.sourceLogId) ?? null : null;
-        if ((to.sourceLogId ?? null) !== expectedParent || (to.sourceVersion ?? null) !== (from.sourceVersion ?? null)) {
-            throw new Error(`Fork lineage of ${targetLogId} does not match ${sourceLogId}`);
-        }
-        if (Boolean(to.hiddenAt) !== Boolean(from.hiddenAt)) throw new Error(`Hidden state of ${targetLogId} does not match`);
-        return { sourceLogId, targetLogId, headVersion: to.headVersion, hidden: Boolean(to.hiddenAt) };
-    });
-}
-
-export function buildCopyWorkerConfig(
-    name: string,
-    source: InfrastructureDefinition,
-    target: InfrastructureDefinition,
-    compatibilityDate: string,
-): Record<string, unknown> {
-    return {
-        name,
-        main: "tenant-copy/index.ts",
-        compatibility_date: compatibilityDate,
-        workers_dev: true,
-        preview_urls: false,
-        r2_buckets: [
-            { binding: "SOURCE_INVOICE_PDFS", bucket_name: source.invoicePdfsBucket },
-            { binding: "TARGET_INVOICE_PDFS", bucket_name: target.invoicePdfsBucket },
-            { binding: "SOURCE_GALLERY_FILES", bucket_name: source.galleryFilesBucket },
-            { binding: "TARGET_GALLERY_FILES", bucket_name: target.galleryFilesBucket },
-            { binding: "SOURCE_GALLERY_PUBLIC", bucket_name: source.galleryPublicBucket },
-            { binding: "TARGET_GALLERY_PUBLIC", bucket_name: target.galleryPublicBucket },
-        ],
-    };
-}
-
-async function copyFiles(options: Options): Promise<void> {
-    const { infrastructure, sites } = await loadTenantConfig();
-    const source = siteById(sites, options.from);
-    const target = siteById(sites, options.to);
-    const run = resolve(REPOSITORY_ROOT, options.run!);
-    const record = JSON.parse(await readFile(join(run, "mapping.json"), "utf8")) as CopyRecord;
-    if (record.source.site !== source.id || record.target.site !== target.id) throw new Error("The mapping belongs to another copy");
-    const mapping: TenantCopyMapping = {
-        sourceAppId: record.source.appId,
-        targetAppId: record.target.appId,
-        logs: Object.fromEntries(record.logs.map((log) => [log.sourceLogId, log.targetLogId])),
-    };
-    validateMapping(mapping);
-
-    const name = `${target.id}-tenant-copy`;
-    const config = buildCopyWorkerConfig(name, infrastructureFor(source, infrastructure), infrastructureFor(target, infrastructure), WRANGLER_BASE.compatibility_date);
-    await writeFile(join(REPOSITORY_ROOT, COPY_WORKER_CONFIG), `${JSON.stringify(config, null, 2)}\n`, "utf8");
-    const token = randomBytes(32).toString("base64url");
-    const url = `https://${name}.${infrastructureFor(target, infrastructure).workersDevDomain}`;
-
-    console.log(`Deploying the short-lived copy Worker ${name}...`);
-    await runWrangler(COPY_WORKER_CONFIG, null, ["deploy"]);
-    try {
-        await runWrangler(COPY_WORKER_CONFIG, null, ["secret", "bulk"], { input: `${JSON.stringify({ COPY_TOKEN: token })}\n` });
-        const report = await copyFilesThrough(workerClient(url, token), mapping);
-        await writeFile(join(run, "files-report.json"), `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
-        const total = report.jobs.reduce((sum, job) => sum + job.checked, 0);
-        console.log(`\nCopied and compared ${total} object(s), ${report.publications} publication(s). Report: ${relative(REPOSITORY_ROOT, run)}/files-report.json`);
-    } finally {
-        console.log(`Deleting the copy Worker ${name}...`);
-        await runWrangler(COPY_WORKER_CONFIG, null, ["delete", "--force"]);
-    }
-}
-
-export type CopyCall = <T>(path: string, body: unknown) => Promise<T>;
-
-export interface FilesReport {
-    copiedAt: string;
-    publications: number;
-    jobs: Array<CopyJob & { copied: number; skipped: number; bytes: number; checked: number }>;
-}
-
-/** Copy, then compare, every planned prefix through a running copy Worker. */
-export async function copyFilesThrough(call: CopyCall, mapping: TenantCopyMapping): Promise<FilesReport> {
-    const owned: string[] = [];
-    for (let cursor: string | null | undefined = undefined; cursor !== null;) {
-        const page: OwnedPage = await call<OwnedPage>("/publications", { appId: mapping.sourceAppId, cursor });
-        owned.push(...page.owned);
-        cursor = page.cursor;
-    }
-    const report: FilesReport = { copiedAt: new Date().toISOString(), publications: owned.length, jobs: [] };
-    for (const job of planFileCopies(mapping, owned)) {
-        const body = { ...job, ...(job.rewriteOwner ? { mapping } : {}) };
-        let copied = 0, skipped = 0, bytes = 0, checked = 0;
-        for (let cursor: string | null | undefined = undefined; cursor !== null;) {
-            const page: CopyPage = await call<CopyPage>("/copy", { ...body, cursor });
-            copied += page.copied; skipped += page.skipped; bytes += page.bytes; cursor = page.cursor;
-        }
-        for (let cursor: string | null | undefined = undefined; cursor !== null;) {
-            const page: ComparePage = await call<ComparePage>("/compare", { ...body, cursor });
-            if (page.problems.length > 0) throw new Error(`Copied objects differ under ${job.toPrefix}: ${page.problems.slice(0, 5).join(", ")}`);
-            checked += page.checked; cursor = page.cursor;
-        }
-        report.jobs.push({ ...job, copied, skipped, bytes, checked });
-        if (checked > 0) console.log(`${job.pair} ${job.fromPrefix} -> ${job.toPrefix}: ${checked} object(s), ${copied} copied`);
-    }
-    return report;
-}
-
-export function workerClient(url: string, token: string): CopyCall {
-    return async function call<T>(path: string, body: unknown): Promise<T> {
-        // A new workers.dev name can take a few seconds to answer.
-        for (let attempt = 0; ; attempt += 1) {
-            const response = await fetch(`${url}${path}`, {
-                method: "POST",
-                headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
-                body: JSON.stringify(body),
-            });
-            if (response.ok) return await response.json() as T;
-            if (attempt < 10 && (response.status === 404 || response.status >= 520)) {
-                await new Promise((wait) => setTimeout(wait, 3000));
-                continue;
-            }
-            const detail = await response.text();
-            throw new Error(`Copy Worker ${path} failed with ${response.status}: ${detail.slice(0, 300)}`);
-        }
-    };
-}
-
-function usage(): string {
-    return `Copy a tenant into a new tenant on its own stack (new identities; the source is only read).
-
-Usage:
-  pnpm tenant:copy -- events --from <site> --to <site> [--allow-skipped-forks]
-  pnpm tenant:copy -- files --from <site> --to <site> --run <directory>`;
-}
-
-export async function main(argv = process.argv.slice(2)): Promise<void> {
-    const options = parseOptions(argv);
-    process.chdir(REPOSITORY_ROOT);
-    if (options.command === "events") await copyEvents(options);
-    else if (options.command === "files") await copyFiles(options);
-    else console.log(usage());
-}
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-    main().catch((error: unknown) => {
-        console.error(`\n${error instanceof Error ? error.message : String(error)}`);
-        process.exitCode = 1;
-    });
-}

package/src/deploy/split-tenant.ts

@@ -1,295 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * Splits a tenant of the shared stack onto its own Ledger and buckets, keeping
- * every identity (docs/tenant-split-runbook.md). Each step changes nothing it
- * cannot repeat, and none of them switches traffic except `cutover`, which you
- * run yourself once `verify` passes.
- *
- *   pnpm tenant:split -- declare  --site bravo      # write tenants/bravo/deployment.json (keep it local; see the runbook)
- *   pnpm tenant:split -- fence    --site bravo --mode tenant_migrating|moved|off
- *   pnpm tenant:split -- transfer --site bravo      # history: source Ledger -> own Ledger
- *   pnpm tenant:split -- files    --site bravo      # objects: shared buckets -> own buckets
- *   pnpm tenant:split -- verify   --site bravo      # checksums, file report, denied access
- *   pnpm tenant:split -- cutover  --site bravo      # verify, mint the gateway token, deploy the gateway (--skip-access: leave Access alone)
- *
- * The site must already have `tenants/<id>/deployment.json` and its stack must
- * be provisioned empty (`pnpm hearthlog apply --site <id> --yes --stop-before ledger-app`: the import needs a
- * Ledger with no application, and creates the application itself under its original id).
- *
- * `verify --skip-files` skips the file copy check and is accepted only against a Ledger on localhost (a rehearsal).
- */
-
-import { spawn } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { identityMapping, validateMapping } from "../tenants/tenant-copy-plan.js";
-import { moveApplication, sameChecksums, type AdminCall, type LogChecksum } from "@hearthlog/tooling";
-
-import { buildCopyWorkerConfig, copyFilesThrough, workerClient, type FilesReport } from "./copy-tenant.js";
-import { dedicatedLedgerBaseUrl, resolveDedicatedAdminToken } from "./dedicated-ledger.js";
-import { runWrangler } from "./deploy-runner.js";
-import { resolveLedgerAdminToken, resolveLedgerBaseUrl } from "./ledger-credential.js";
-import {
-    gallerySweeperId,
-    infrastructureFor,
-    loadTenantConfig,
-    REPOSITORY_ROOT,
-    siteById,
-    type InfrastructureDefinition,
-    type ResolvedSite,
-} from "../tenants/tenant-config.js";
-import { WRANGLER_BASE } from "../tenants/wrangler-base.js";
-
-const COPY_WORKER_CONFIG = "wrangler.tenant-move.jsonc";
-
-export function movesDirectory(siteId: string): string {
-    return join(REPOSITORY_ROOT, ".wrangler", "tenant-moves", siteId);
-}
-
-export function adminCaller(baseUrl: string, token: string): AdminCall {
-    return (method, path, body) =>
-        fetch(`${baseUrl.replace(/\/$/, "")}${path}`, {
-            method,
-            headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-        });
-}
-
-interface Stacks {
-    site: ResolvedSite;
-    shared: InfrastructureDefinition;
-    source: AdminCall;
-    target: () => Promise<AdminCall>;
-    sourceAppId: string;
-}
-
-async function stacks(siteId: string): Promise<Stacks> {
-    const { infrastructure, sites } = await loadTenantConfig();
-    const site = siteById(sites, siteId);
-    if (!site.deployment) throw new Error(`${siteId} has no tenants/${siteId}/deployment.json: add it, then provision the stack with "pnpm hearthlog apply --site ${siteId} --yes --stop-before ledger-app"`);
-    const sourceToken = await resolveLedgerAdminToken();
-    if (!sourceToken) throw new Error("No administrator token for the shared Ledger (LEDGER_ADMIN_TOKEN)");
-    const source = adminCaller(resolveLedgerBaseUrl(process.env.LEDGER_BASE_URL, infrastructure.ledgerWorker, infrastructure.workersDevDomain), sourceToken);
-    const response = await source("GET", "/admin/v1/apps");
-    if (!response.ok) throw new Error(`Listing the shared Ledger's applications failed with ${response.status}`);
-    const apps = ((await response.json()) as { apps: Array<{ id: string; name: string; revokedAt: string | null }> }).apps;
-    const app = apps.find((candidate) => candidate.name === site.ledgerAppName && candidate.revokedAt === null);
-    if (!app) throw new Error(`The shared Ledger has no active application "${site.ledgerAppName}"`);
-    return {
-        site,
-        shared: infrastructure,
-        source,
-        sourceAppId: app.id,
-        target: async () => {
-            const token = await resolveDedicatedAdminToken(site.id);
-            if (!token) throw new Error(`No administrator token for the ${site.id} Ledger: provision it first`);
-            return adminCaller(process.env[`LEDGER_BASE_URL_${site.id.toUpperCase().replace(/-/g, "_")}`]?.trim() || dedicatedLedgerBaseUrl(site, infrastructure), token);
-        },
-    };
-}
-
-async function newRun(siteId: string): Promise<string> {
-    const directory = join(movesDirectory(siteId), new Date().toISOString().replace(/[:.]/g, "-"));
-    await mkdir(directory, { recursive: true });
-    return directory;
-}
-
-/** The latest run directory holding `file`, so `files` and `verify` follow `transfer`. */
-async function latest(siteId: string, file: string): Promise<string | null> {
-    const runs = (await readdir(movesDirectory(siteId)).catch(() => [] as string[])).sort().reverse();
-    for (const run of runs) {
-        try {
-            await readFile(join(movesDirectory(siteId), run, file));
-            return join(movesDirectory(siteId), run);
-        } catch {
-            // Try the next older run.
-        }
-    }
-    return null;
-}
-
-async function fence(siteId: string, mode: string): Promise<void> {
-    if (!["tenant_migrating", "moved", "off"].includes(mode)) throw new Error('--mode must be tenant_migrating, moved, or off');
-    const { site, source, sourceAppId } = await stacks(siteId);
-    const body = mode === "moved" ? { mode, destination: new URL(site.hostname).origin } : { mode };
-    const response = await source("PUT", `/admin/v1/apps/${sourceAppId}/fence`, body);
-    if (!response.ok) throw new Error(`Setting the fence failed with ${response.status}: ${await response.text()}`);
-    console.log(`Fence on ${site.ledgerAppName} (${sourceAppId}): ${mode}`);
-}
-
-async function transfer(siteId: string, allowUnfenced: boolean): Promise<void> {
-    const { site, source, target, sourceAppId } = await stacks(siteId);
-    const run = await newRun(siteId);
-    const report = await moveApplication({ appId: sourceAppId, source, target: await target(), allowUnfenced, log: (message) => console.log(message) });
-    await writeFile(join(run, "transfer.json"), `${JSON.stringify({ site: site.id, ...report }, null, 2)}\n`, { mode: 0o600 });
-    console.log(`\nMoved ${report.logs} log(s), ${report.events} event(s), ${report.requests} idempotency record(s). Report: ${relative(REPOSITORY_ROOT, run)}/transfer.json`);
-}
-
-async function files(siteId: string): Promise<void> {
-    const { site, shared, sourceAppId } = await stacks(siteId);
-    const run = (await latest(siteId, "transfer.json")) ?? (await newRun(siteId));
-    const mapping = identityMapping(sourceAppId);
-    validateMapping(mapping);
-    const name = `${site.id}-tenant-move`;
-    const own = infrastructureFor(site, shared);
-    const config = buildCopyWorkerConfig(name, shared, own, WRANGLER_BASE.compatibility_date);
-    await writeFile(join(REPOSITORY_ROOT, COPY_WORKER_CONFIG), `${JSON.stringify({ ...config, name }, null, 2)}\n`, "utf8");
-    const token = randomBytes(32).toString("base64url");
-    console.log(`Deploying the short-lived copy Worker ${name}...`);
-    await runWrangler(COPY_WORKER_CONFIG, null, ["deploy"]);
-    try {
-        await runWrangler(COPY_WORKER_CONFIG, null, ["secret", "bulk"], { input: `${JSON.stringify({ COPY_TOKEN: token })}\n` });
-        const report = await copyFilesThrough(workerClient(`https://${name}.${own.workersDevDomain}`, token), mapping);
-        await writeFile(join(run, "files-report.json"), `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
-        const total = report.jobs.reduce((sum, job) => sum + job.checked, 0);
-        console.log(`\nCopied and compared ${total} object(s), ${report.publications} publication(s). Report: ${relative(REPOSITORY_ROOT, run)}/files-report.json`);
-    } finally {
-        console.log(`Deleting the copy Worker ${name}...`);
-        await runWrangler(COPY_WORKER_CONFIG, null, ["delete", "--force"]);
-    }
-}
-
-export interface VerifyInput {
-    source: LogChecksum[];
-    target: LogChecksum[];
-    files: FilesReport | null;
-    /** A rehearsal against a local Ledger has no buckets to copy; a real move never skips the file check. */
-    skipFiles?: boolean;
-    /** What the destination answered to a request with a credential it did not issue. */
-    foreignCredentialStatus: number;
-}
-
-/** Everything `verify` checks, as a list of what is wrong. */
-export function verificationProblems(input: VerifyInput): string[] {
-    const problems = sameChecksums(input.source, input.target);
-    if (!input.files && !input.skipFiles) problems.push("no files report: run the files step");
-    if (input.foreignCredentialStatus !== 401 && input.foreignCredentialStatus !== 403) {
-        problems.push(`the destination answered ${input.foreignCredentialStatus} to a credential it did not issue; it must refuse it`);
-    }
-    return problems;
-}
-
-/** `--skip-files` is only for a rehearsal: the destination must be a Ledger on this machine. */
-export function maySkipFiles(destinationUrl: string): boolean {
-    const host = new URL(destinationUrl).hostname;
-    return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
-}
-
-async function verificationProblemsFor(siteId: string, skipFiles: boolean): Promise<string[]> {
-    const { source, target, sourceAppId } = await stacks(siteId);
-    const destination = await target();
-    const read = async (call: AdminCall) => {
-        const response = await call("GET", `/admin/v1/apps/${sourceAppId}/checksums`);
-        if (!response.ok) throw new Error(`Reading checksums failed with ${response.status}`);
-        return ((await response.json()) as { logs: LogChecksum[] }).logs;
-    };
-    const run = await latest(siteId, "files-report.json");
-    const files = run ? (JSON.parse(await readFile(join(run, "files-report.json"), "utf8")) as FilesReport) : null;
-    return verificationProblems({ source: await read(source), target: await read(destination), files, skipFiles, foreignCredentialStatus: await foreignStatus(siteId) });
-}
-
-async function verify(siteId: string, skipFiles: boolean): Promise<void> {
-    if (skipFiles && !maySkipFiles(await destinationUrl(siteId))) {
-        throw new Error("--skip-files is for a rehearsal against a Ledger on localhost; the destination here is not local, so the file copy must be compared");
-    }
-    const problems = await verificationProblemsFor(siteId, skipFiles);
-    if (problems.length) {
-        console.error(`Verification failed:\n  - ${problems.join("\n  - ")}`);
-        process.exit(1);
-    }
-    console.log(skipFiles
-        ? "Verified (files skipped, rehearsal): event checksums match on every log, and the destination refuses a credential it did not issue."
-        : "Verified: event checksums match on every log, the file copy was compared, and the destination refuses a credential it did not issue.");
-}
-
-/** The destination signs its own tokens: a credential it did not issue must be refused. */
-async function destinationUrl(siteId: string): Promise<string> {
-    const { infrastructure, sites } = await loadTenantConfig();
-    const site = siteById(sites, siteId);
-    return (process.env[`LEDGER_BASE_URL_${site.id.toUpperCase().replace(/-/g, "_")}`]?.trim() || dedicatedLedgerBaseUrl(site, infrastructure)).replace(/\/$/, "");
-}
-
-async function foreignStatus(siteId: string): Promise<number> {
-    const base = await destinationUrl(siteId);
-    const response = await fetch(`${base}/session`, { headers: { Authorization: `Bearer ${randomBytes(48).toString("base64url")}` } });
-    return response.status;
-}
-
-const BIN = fileURLToPath(new URL("../../bin/hearthlog.mjs", import.meta.url));
-
-/** Run a `hearthlog` command of this package for the site, and wait for it. */
-function hearthlog(args: string[]): Promise<void> {
-    return new Promise((resolveRun, reject) => {
-        const child = spawn(process.execPath, [BIN, ...args], { cwd: REPOSITORY_ROOT, stdio: "inherit" });
-        child.on("error", reject);
-        child.on("exit", (code) => (code === 0 ? resolveRun() : reject(new Error(`hearthlog ${args.join(" ")} exited with ${String(code)}`))));
-    });
-}
-
-/**
- * Write `tenants/<id>/deployment.json` for a site that is about to leave the shared stack, pinned to the shared stack's
- * account so the move stays in it. This changes the site's configuration: it no longer deploys from the shared
- * pipeline, and the shared feed Worker loses its binding. Keep the file out of anything that is pushed until the
- * cutover is done (docs/tenant-split-runbook.md).
- */
-async function declare(siteId: string, accountOverride: string | undefined): Promise<void> {
-    const { infrastructure, sites, stacks } = await loadTenantConfig();
-    const site = siteById(sites, siteId);
-    if (site.deployment) throw new Error(`${siteId} already has tenants/${siteId}/deployment.json`);
-    const accountId = accountOverride ?? infrastructure.accountId;
-    if (!accountId || !/^[0-9a-f]{32}$/.test(accountId)) {
-        throw new Error("Name the account: set infrastructure.accountId in tenants.json (the account of the shared stack) or pass --account-id");
-    }
-    const path = join(REPOSITORY_ROOT, "tenants", siteId, "deployment.json");
-    await writeFile(path, `${JSON.stringify({ schemaVersion: 1, resourcePrefix: `${siteId}-prod`, ledger: "dedicated", accountId }, null, 2)}\n`, { flag: "wx" });
-    console.log(`Wrote ${relative(REPOSITORY_ROOT, path)} (resource prefix ${siteId}-prod, account pinned).`);
-    console.log("Keep it local: pushing it would redeploy the shared feed Worker without this site's binding while its frontend still runs on the shared stack.");
-    if (gallerySweeperId(stacks, infrastructure) === siteId) {
-        console.log(`${siteId} sweeps the shared public Gallery bucket: set infrastructure.gallerySweeper in tenants.json to a site that stays on the shared stack.`);
-    }
-}
-
-/**
- * The switch: check the move again, mint the gateway's token on the new Ledger, and deploy the gateway bound to it. The
- * token goes to the live gateway first, which still talks to the old Ledger until the deploy lands, so the two run
- * back to back. It stops before marking the old application moved (`fence --mode moved`).
- */
-async function cutover(siteId: string, skipAccess: boolean): Promise<void> {
-    const problems = await verificationProblemsFor(siteId, false);
-    if (problems.length) {
-        console.error(`Not cutting over; verification failed:\n  - ${problems.join("\n  - ")}`);
-        process.exit(1);
-    }
-    console.log("Verified. Minting the gateway token on the new Ledger, then deploying the gateway.");
-    // The Access application is the same one (same origin), so a run without CLOUDFLARE_API_TOKEN may leave it alone;
-    // the gateway keeps the audience secret it already holds.
-    await hearthlog(["ensure", "--site", siteId, "--rotate-token", ...(skipAccess ? ["--skip-access"] : [])]);
-    await hearthlog(["deploy", "--site", siteId]);
-    console.log(`\nThe ${siteId} gateway now talks to its own Ledger. Next: pnpm tenant:split -- fence --site ${siteId} --mode moved`);
-}
-
-async function main(argv: string[]): Promise<void> {
-    const args = argv.filter((argument) => argument !== "--");
-    const [command, ...rest] = args;
-    const value = (name: string) => {
-        const index = rest.indexOf(name);
-        return index === -1 ? undefined : rest[index + 1]?.trim();
-    };
-    const siteId = value("--site");
-    if (!command || !siteId) {
-        console.error("Usage: pnpm tenant:split -- <declare|fence|transfer|files|verify|cutover> --site <id> [--mode tenant_migrating|moved|off] [--allow-unfenced] [--skip-files] [--skip-access] [--account-id <id>]");
-        process.exit(1);
-    }
-    if (command === "declare") await declare(siteId, value("--account-id"));
-    else if (command === "fence") await fence(siteId, value("--mode") ?? "");
-    else if (command === "transfer") await transfer(siteId, rest.includes("--allow-unfenced"));
-    else if (command === "files") await files(siteId);
-    else if (command === "verify") await verify(siteId, rest.includes("--skip-files"));
-    else if (command === "cutover") await cutover(siteId, rest.includes("--skip-access"));
-    else throw new Error(`Unknown command "${command}"`);
-}
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main(process.argv.slice(2));

package/src/tenants/tenant-copy-plan.ts

@@ -1,119 +0,0 @@
-/**
- * What a tenant copy moves between buckets, as pure data.
- *
- * A copy gives the new tenant new app and log IDs, and private object keys
- * embed them: invoice files are `<prefix>/<appId>/<logId>/…` and Gallery
- * files `v1/<appId>/…`. Gallery publications are keyed by their own ID, but
- * their `owner.json` names the app and log. The generated-invoice cache
- * (`v1/<appId>/<logId>/invoices/…`) is not copied: it rebuilds on demand.
- * Calendar feeds are not copied: the new tenant creates its own.
- *
- * A **move** (the split of a shared tenant onto its own stack) keeps the app
- * and log IDs, so every key stays exactly as it is: `identity: true` copies
- * each prefix to the same name in the destination bucket, per app rather than
- * per log, and publication owner records are already correct and left alone.
- */
-
-export interface TenantCopyMapping {
-    sourceAppId: string;
-    targetAppId: string;
-    /** Source log ID to target log ID, for every copied log. Empty for an identity move. */
-    logs: Readonly<Record<string, string>>;
-    /** The destination keeps the app and log IDs, so keys are copied unchanged. */
-    identity?: true;
-}
-
-/** The mapping of a move that keeps every identity. */
-export function identityMapping(appId: string): TenantCopyMapping {
-    return { sourceAppId: appId, targetAppId: appId, logs: {}, identity: true };
-}
-
-export type BucketPair = "invoice-pdfs" | "gallery-files" | "gallery-public";
-
-export interface CopyJob {
-    pair: BucketPair;
-    fromPrefix: string;
-    toPrefix: string;
-    /** Rewrite `owner.json` objects under this prefix to the target app and log. */
-    rewriteOwner?: boolean;
-}
-
-const INVOICE_FILE_PREFIXES = ["received/v1", "received-isdoc/v1", "issued/v1", "issued-isdoc/v1"] as const;
-
-const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-function requireId(value: string, label: string): void {
-    if (!ID.test(value)) throw new Error(`${label} is not a UUID: ${value}`);
-}
-
-export function validateMapping(mapping: TenantCopyMapping): void {
-    requireId(mapping.sourceAppId, "source app");
-    requireId(mapping.targetAppId, "target app");
-    if (mapping.identity) {
-        if (mapping.sourceAppId !== mapping.targetAppId) throw new Error("an identity move keeps the app: source and target must be the same id");
-        if (Object.keys(mapping.logs).length) throw new Error("an identity move names no logs: every log keeps its id");
-        return;
-    }
-    if (mapping.sourceAppId === mapping.targetAppId) throw new Error("source and target apps are the same");
-    for (const [source, target] of Object.entries(mapping.logs)) {
-        requireId(source, "source log");
-        requireId(target, "target log");
-    }
-}
-
-/** Every prefix to copy, given the publications the source app owns. */
-export function planFileCopies(mapping: TenantCopyMapping, ownedPublications: readonly string[]): CopyJob[] {
-    validateMapping(mapping);
-    const jobs: CopyJob[] = [];
-    if (mapping.identity) {
-        for (const prefix of INVOICE_FILE_PREFIXES) {
-            const key = `${prefix}/${mapping.sourceAppId}/`;
-            jobs.push({ pair: "invoice-pdfs", fromPrefix: key, toPrefix: key });
-        }
-        jobs.push({ pair: "gallery-files", fromPrefix: `v1/${mapping.sourceAppId}/`, toPrefix: `v1/${mapping.sourceAppId}/` });
-        for (const publication of ownedPublications) {
-            requireId(publication, "publication");
-            const control = `v1/publications/${publication}/`;
-            jobs.push({ pair: "gallery-files", fromPrefix: control, toPrefix: control });
-            jobs.push({ pair: "gallery-public", fromPrefix: `v1/galleries/${publication}/`, toPrefix: `v1/galleries/${publication}/` });
-        }
-        return jobs;
-    }
-    for (const prefix of INVOICE_FILE_PREFIXES) {
-        for (const [sourceLog, targetLog] of Object.entries(mapping.logs)) {
-            jobs.push({
-                pair: "invoice-pdfs",
-                fromPrefix: `${prefix}/${mapping.sourceAppId}/${sourceLog}/`,
-                toPrefix: `${prefix}/${mapping.targetAppId}/${targetLog}/`,
-            });
-        }
-    }
-    jobs.push({ pair: "gallery-files", fromPrefix: `v1/${mapping.sourceAppId}/`, toPrefix: `v1/${mapping.targetAppId}/` });
-    for (const publication of ownedPublications) {
-        requireId(publication, "publication");
-        jobs.push({
-            pair: "gallery-files",
-            fromPrefix: `v1/publications/${publication}/`,
-            toPrefix: `v1/publications/${publication}/`,
-            rewriteOwner: true,
-        });
-        jobs.push({ pair: "gallery-public", fromPrefix: `v1/galleries/${publication}/`, toPrefix: `v1/galleries/${publication}/` });
-    }
-    return jobs;
-}
-
-export function isOwnerRecord(key: string): boolean {
-    return /^v1\/publications\/[^/]+\/owner\.json$/.test(key);
-}
-
-/** The owner record for the target tenant; throws for a log the copy left out. */
-export function rewriteOwner(record: unknown, mapping: TenantCopyMapping): { appId: string; logId: string } {
-    const owner = record as { appId?: unknown; logId?: unknown } | null;
-    if (!owner || typeof owner.appId !== "string" || typeof owner.logId !== "string") {
-        throw new Error("publication owner record is malformed");
-    }
-    if (owner.appId !== mapping.sourceAppId) throw new Error("publication belongs to another app");
-    const logId = mapping.logs[owner.logId];
-    if (!logId) throw new Error(`publication belongs to log ${owner.logId}, which was not copied`);
-    return { appId: mapping.targetAppId, logId };
-}