sealkeep 0.9.0 → 0.11.0

package/dist/src/team-backfill.js

@@ -0,0 +1,1429 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { execFile } from "node:child_process";
+import { copyFile, link, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { openForFlush } from "./flush.js";
+import { dirname, join } from "node:path";
+import { unwrapArchiveKey, wrapAll, x25519PrivateKeyFromRaw, x25519PublicKeyFromRaw, zeroize, NONCE_BYTES, } from "../packages/sealkeep-crypto/src/index.js";
+import { matchesPhraseCheck } from "./crypto.js";
+import { isSealkeepError } from "./errors.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { isV2 } from "./types.js";
+import { listArchives, readConfig } from "./vault.js";
+import { createProgressDeadline } from "./progress-deadline.js";
+import { backgroundUploadBytesPerSecond, readLocalSettings } from "./machine-settings.js";
+import { orderTeamBackfillJobs } from "./team-backfill-scheduling.js";
+import { createBackgroundCpuYield } from "./background-cpu.js";
+import { unframeChunks } from "./byte-stream.js";
+const STABLE_PROJECT_KEY = /^(?:g1|p1):[a-f0-9]{64}$/;
+const LEDGER_VERSION = 1;
+const CLAIM_LEASE_MS = 30 * 60_000;
+const CLAIM_RENEW_MS = 60_000;
+const PROCESS_INSTANCE_ID = randomUUID();
+const LEDGER_CORRUPT = "team_history_backfill_state_corrupt";
+const ledgerPath = (dataDir) => join(dataDir, "team-history-backfill.json");
+const ledgerBackupPath = (dataDir) => `${ledgerPath(dataDir)}.bak`;
+const lockPath = (dataDir) => `${ledgerPath(dataDir)}.lock`;
+const processMarkerPath = (dataDir, pid) => join(dataDir, "runtime", `team-backfill-process-${pid}.json`);
+let processStartIdentity;
+function emptyLedger() {
+    return { version: LEDGER_VERSION, jobs: {}, scopes: {} };
+}
+class TeamBackfillLedgerError extends Error {
+    constructor(message = LEDGER_CORRUPT) { super(message); this.name = "TeamBackfillLedgerError"; }
+}
+class TeamBackfillConflictError extends Error {
+    constructor() { super("derived_ref_conflict"); this.name = "derived_ref_conflict"; }
+}
+function ledgerPayload(ledger) {
+    return JSON.stringify({ version: LEDGER_VERSION, jobs: ledger.jobs, scopes: ledger.scopes,
+        ...(ledger.scheduleSequence !== undefined ? { scheduleSequence: ledger.scheduleSequence } : {}),
+    });
+}
+function ledgerChecksum(ledger) {
+    return createHash("sha256").update(`sealkeep-team-backfill-ledger-v1\0${ledgerPayload(ledger)}`).digest("hex");
+}
+function isObject(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function validJob(value) {
+    if (!isObject(value) || value.version !== 1)
+        return false;
+    const strings = ["id", "shareRef", "sourceArchiveId", "spaceKey", "project", "rosterHash", "stage", "createdAt", "updatedAt"];
+    if (strings.some((key) => typeof value[key] !== "string"))
+        return false;
+    if (!/^[0-9a-f]{64}$/.test(String(value.id)) || !/^[0-9a-f]{64}$/.test(String(value.rosterHash)))
+        return false;
+    if (!new Set(["pending", "prepared", "uploaded", "registered", "indexed", "blocked", "superseded"]).has(value.stage))
+        return false;
+    if (!Array.isArray(value.memberPublicKeys) || value.memberPublicKeys.some((key) => typeof key !== "string"))
+        return false;
+    if (!Array.isArray(value.dependencyJobIds) || value.dependencyJobIds.some((id) => typeof id !== "string"))
+        return false;
+    if (!Array.isArray(value.dependencyRefs) || value.dependencyRefs.some((id) => typeof id !== "string"))
+        return false;
+    if (!Number.isSafeInteger(value.attempts) || Number(value.attempts) < 0)
+        return false;
+    if (value.sourceCreatedAt !== undefined && (typeof value.sourceCreatedAt !== "string" || !Number.isFinite(Date.parse(value.sourceCreatedAt))))
+        return false;
+    if (value.lastScheduledAt !== undefined && (typeof value.lastScheduledAt !== "string" || !Number.isFinite(Date.parse(value.lastScheduledAt))))
+        return false;
+    if (value.membership_version !== undefined && (!Number.isSafeInteger(value.membership_version) || Number(value.membership_version) <= 0))
+        return false;
+    const identity = jobIdentity(String(value.spaceKey), String(value.rosterHash), String(value.sourceArchiveId));
+    if (identity.id !== value.id || identity.shareRef !== value.shareRef)
+        return false;
+    if (value.claim !== undefined) {
+        if (!isObject(value.claim) || typeof value.claim.token !== "string" || !Number.isSafeInteger(value.claim.pid)
+            || !Number.isFinite(value.claim.at) || (value.claim.processId !== undefined && typeof value.claim.processId !== "string"))
+            return false;
+        if (value.claim.processStart !== undefined && typeof value.claim.processStart !== "string")
+            return false;
+    }
+    return true;
+}
+function parseLedger(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isObject(value) || value.version !== LEDGER_VERSION || !isObject(value.jobs) || !isObject(value.scopes))
+        return null;
+    const ledger = value;
+    if (ledger.scheduleSequence !== undefined && (!Number.isSafeInteger(ledger.scheduleSequence) || ledger.scheduleSequence < 0))
+        return null;
+    if (Object.values(ledger.jobs).some((job) => !validJob(job)))
+        return null;
+    for (const [spaceKey, scope] of Object.entries(ledger.scopes)) {
+        if (!isObject(scope) || !spaceKey || typeof scope.rosterHash !== "string" || !/^[0-9a-f]{64}$/.test(scope.rosterHash)
+            || !Array.isArray(scope.sourceArchiveIds) || scope.sourceArchiveIds.some((id) => typeof id !== "string")
+            || typeof scope.observedAt !== "string")
+            return null;
+        if (scope.membership_version !== undefined && (!Number.isSafeInteger(scope.membership_version) || Number(scope.membership_version) <= 0))
+            return null;
+    }
+    if (ledger.checksum !== undefined && ledger.checksum !== ledgerChecksum(ledger))
+        return null;
+    return { version: LEDGER_VERSION, jobs: ledger.jobs, scopes: ledger.scopes, ...(ledger.checksum ? { checksum: ledger.checksum } : {}),
+        ...(ledger.scheduleSequence !== undefined ? { scheduleSequence: ledger.scheduleSequence } : {}),
+    };
+}
+async function readLedgerFile(path) {
+    try {
+        return { exists: true, ledger: parseLedger(await readFile(path, "utf8")) };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { exists: false, ledger: null };
+        return { exists: true, ledger: null };
+    }
+}
+async function readLedger(dataDir) {
+    const primary = await readLedgerFile(ledgerPath(dataDir));
+    if (primary.ledger)
+        return primary.ledger;
+    const backup = await readLedgerFile(ledgerBackupPath(dataDir));
+    if (backup.ledger)
+        return backup.ledger;
+    if (!primary.exists && !backup.exists)
+        return emptyLedger();
+    throw new TeamBackfillLedgerError();
+}
+async function writeLedger(dataDir, ledger) {
+    const path = ledgerPath(dataDir);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    ledger.checksum = ledgerChecksum(ledger);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(ledger, null, 2) + "\n");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    // Preserve only a validated previous generation. A corrupt primary must
+    // never overwrite the last usable backup on the way to recovery.
+    const previous = await readLedgerFile(path);
+    if (previous.ledger) {
+        const backupTemporary = `${ledgerBackupPath(dataDir)}.${randomUUID()}.tmp`;
+        await copyFile(path, backupTemporary);
+        const { handle: backupHandle } = await openForFlush(backupTemporary);
+        try {
+            await backupHandle.sync();
+        }
+        finally {
+            await backupHandle.close();
+        }
+        await rename(backupTemporary, ledgerBackupPath(dataDir));
+    }
+    await rename(temporary, path);
+    if (!previous.ledger && !(await readLedgerFile(ledgerBackupPath(dataDir))).ledger) {
+        const initialBackup = `${ledgerBackupPath(dataDir)}.${randomUUID()}.tmp`;
+        await copyFile(path, initialBackup);
+        const { handle: backupHandle } = await openForFlush(initialBackup);
+        try {
+            await backupHandle.sync();
+        }
+        finally {
+            await backupHandle.close();
+        }
+        await rename(initialBackup, ledgerBackupPath(dataDir));
+    }
+    const directory = await open(dirname(path), "r").catch(() => null);
+    try {
+        await directory?.sync();
+    }
+    finally {
+        await directory?.close();
+    }
+}
+function processAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function osProcessStart(pid) {
+    return new Promise((resolve) => {
+        execFile("ps", ["-p", String(pid), "-o", "lstart="], { timeout: 1_000, maxBuffer: 4_096 }, (error, stdout) => {
+            resolve(error ? null : stdout.trim() || null);
+        });
+    });
+}
+async function currentProcessStart() {
+    if (processStartIdentity === undefined)
+        processStartIdentity = await osProcessStart(process.pid);
+    return processStartIdentity;
+}
+async function ensureProcessMarker(dataDir) {
+    const path = processMarkerPath(dataDir, process.pid);
+    const processStart = await currentProcessStart();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    // Multiple lanes in one process can request the ledger before its lock is
+    // acquired. Each marker publication must own its temporary file; sharing a
+    // PID-scoped temporary lets one rename consume another lane's pending write.
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify({ pid: process.pid, processId: PROCESS_INSTANCE_ID, processStart, startedAt: new Date().toISOString() }) + "\n", { mode: 0o600, flag: "wx" });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+    return processStart;
+}
+async function processOwnerAlive(dataDir, owner) {
+    const pid = Number(owner.pid);
+    if (!Number.isSafeInteger(pid) || pid <= 0 || !processAlive(pid))
+        return false;
+    if (!owner.processId)
+        return true; // legacy claims fail safe while that PID exists
+    if (pid === process.pid)
+        return owner.processId === PROCESS_INSTANCE_ID;
+    if (owner.processStart) {
+        const actualStart = await osProcessStart(pid);
+        if (actualStart && actualStart !== owner.processStart)
+            return false;
+    }
+    const marker = await readFile(processMarkerPath(dataDir, pid), "utf8")
+        .then((raw) => JSON.parse(raw)).catch(() => null);
+    // A Sealkeep PID reused by another Sealkeep process has a different marker.
+    // A live process without a marker remains live rather than being stolen.
+    return marker ? marker.processId === owner.processId : true;
+}
+async function quarantineLock(path, expected) {
+    const quarantine = `${path}.${randomUUID()}.stale`;
+    try {
+        await rename(path, quarantine);
+    }
+    catch (error) {
+        if (["ENOENT", "EACCES", "EPERM"].includes(error.code ?? ""))
+            return false;
+        throw error;
+    }
+    const moved = await lstat(quarantine).catch(() => null);
+    if (moved && moved.dev === expected.dev && moved.ino === expected.ino) {
+        await rm(quarantine, { force: true }).catch(() => undefined);
+        return true;
+    }
+    // Another contender replaced the name between inspection and rename. A
+    // hard-link restore is create-only: unlike rename(), it can never overwrite
+    // a third contender that has already acquired the public lock name.
+    const restored = await link(quarantine, path).then(() => true, () => false);
+    if (restored)
+        await rm(quarantine, { force: true }).catch(() => undefined);
+    return false;
+}
+async function withLedgerLock(dataDir, work) {
+    const path = lockPath(dataDir);
+    const token = randomUUID();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const processStart = await ensureProcessMarker(dataDir);
+    let handle = null;
+    const started = Date.now();
+    while (!handle) {
+        let candidate = null;
+        try {
+            candidate = await open(path, "wx", 0o600);
+            await candidate.writeFile(JSON.stringify({ token, pid: process.pid, processId: PROCESS_INSTANCE_ID, processStart, at: Date.now() }));
+            await candidate.sync();
+            handle = candidate;
+        }
+        catch (error) {
+            if (candidate) {
+                const created = await candidate.stat().catch(() => null);
+                await candidate.close().catch(() => undefined);
+                if (created)
+                    await quarantineLock(path, created).catch(() => false);
+            }
+            if (error.code !== "EEXIST")
+                throw error;
+            const snapshot = await lstat(path).catch(() => null);
+            const owner = snapshot
+                ? await readFile(path, "utf8").then((raw) => JSON.parse(raw)).catch(() => null)
+                : null;
+            const age = Date.now() - (owner?.at ?? snapshot?.mtimeMs ?? Date.now());
+            // Age alone never revokes a proven live owner. Malformed locks get a
+            // generous grace period; a crashed/reused-PID owner can be recovered.
+            const stale = snapshot && (owner ? !await processOwnerAlive(dataDir, owner) : age > CLAIM_LEASE_MS);
+            const stillSame = snapshot
+                ? await lstat(path).then((current) => current.dev === snapshot.dev && current.ino === snapshot.ino, () => false)
+                : false;
+            if (snapshot && stale && stillSame && await quarantineLock(path, snapshot)) {
+                continue;
+            }
+            if (Date.now() - started > 30_000)
+                throw new Error("Timed out waiting for team history state");
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+    try {
+        return await work(await readLedger(dataDir));
+    }
+    finally {
+        const held = await handle.stat().catch(() => null);
+        await handle.close().catch(() => undefined);
+        const owner = await readFile(path, "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+        if (held && owner?.token === token)
+            await quarantineLock(path, held).catch(() => false);
+    }
+}
+async function mutateLedger(dataDir, change) {
+    return withLedgerLock(dataDir, async (ledger) => {
+        const answer = await change(ledger);
+        await writeLedger(dataDir, ledger);
+        return answer;
+    });
+}
+function rosterHash(members, membershipVersion) {
+    const facts = members.map((member) => typeof member === "string"
+        ? `legacy-key:${member}`
+        : `${member.account_id}:${member.key_version}:${member.role}:${member.public_key}`);
+    return createHash("sha256").update([
+        `membership-version:${membershipVersion ?? "legacy"}`,
+        ...[...new Set(facts)].sort(),
+    ].join("\0")).digest("hex");
+}
+function archiveWrapsExactlyMembers(record, publicKeys) {
+    const wanted = [...new Set(publicKeys)].sort();
+    const entries = record.envelope?.wrappedKeys ?? [];
+    if (wanted.length === 0 || entries.some((entry) => entry.type !== "x25519"))
+        return false;
+    const actual = entries.map((entry) => entry.type === "x25519" ? entry.recipientPublicKey : "").sort();
+    return actual.length === wanted.length && actual.every((key, index) => key === wanted[index]);
+}
+/**
+ * Re-wraps without changing ciphertext and without introducing a new random
+ * frame for the same durable job. The per-wrap nonce and ephemeral X25519 key
+ * come from an HMAC keyed by the archive key, domain-separated by job,
+ * recipient and purpose. They are therefore unpredictable without the source
+ * secret, unique across roster generations, and byte-identical after a crash
+ * even if the ledger disappeared after PUT but before completion.
+ */
+function deterministicTeamEnvelope(source, phrase, job) {
+    const archiveKey = unwrapArchiveKey(source.envelope.wrappedKeys, source.envelope.suite, source.envelope.archiveId, { phrase });
+    const privateSeeds = [];
+    try {
+        const derive = (publicKey, purpose) => createHmac("sha256", archiveKey)
+            .update("sealkeep-team-history-wrap-v1\0")
+            .update(job.id)
+            .update("\0")
+            .update(publicKey)
+            .update("\0")
+            .update(purpose)
+            .digest();
+        const recipients = job.memberPublicKeys.map((publicKey) => ({
+            kind: "x25519",
+            publicKey: x25519PublicKeyFromRaw(Buffer.from(publicKey, "base64")),
+        }));
+        const wrapNonces = job.memberPublicKeys.map((publicKey) => derive(publicKey, "nonce").subarray(0, NONCE_BYTES));
+        const ephemeralPrivateKeys = job.memberPublicKeys.map((publicKey) => {
+            const raw = derive(publicKey, "ephemeral");
+            privateSeeds.push(raw);
+            return x25519PrivateKeyFromRaw(raw);
+        });
+        const wrappedKeys = wrapAll(archiveKey, recipients, source.envelope.suite, source.envelope.archiveId, {
+            archiveKey,
+            noncePrefix: Buffer.alloc(4),
+            wrapSalts: [],
+            wrapNonces,
+            ephemeralPrivateKeys,
+        });
+        return { ...source.envelope, wrappedKeys };
+    }
+    finally {
+        zeroize(archiveKey, ...privateSeeds);
+    }
+}
+async function mapLimit(values, limit, work, yieldAfterWork) {
+    const output = new Array(values.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(Math.max(1, limit), values.length) }, async () => {
+        for (;;) {
+            const index = cursor++;
+            if (index >= values.length)
+                return;
+            output[index] = await work(values[index]);
+            await yieldAfterWork?.();
+        }
+    });
+    await Promise.all(workers);
+    return output;
+}
+function ledgerIsEmpty(ledger) {
+    return Object.keys(ledger.jobs).length === 0 && Object.keys(ledger.scopes).length === 0;
+}
+function hasConfirmedTeamBinding(config) {
+    return Object.values(config.teamSpaces ?? {}).some((binding) => binding.localConfirmed === true);
+}
+async function unconfiguredEmptyBackfill(dataDir) {
+    const config = await readConfig(dataDir);
+    if (hasConfirmedTeamBinding(config))
+        return false;
+    return ledgerIsEmpty(await readLedger(dataDir));
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+function uuidFromDigest(value) {
+    const hex = createHash("sha256").update(value).digest("hex");
+    // A deterministic UUID-shaped ref keeps retry/create-only storage semantics
+    // stable without reusing the private archive's account-scoped object key.
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+function jobIdentity(spaceKey, currentRoster, sourceArchiveId) {
+    const seed = `sealkeep-team-history-v1\0${spaceKey}\0${currentRoster}\0${sourceArchiveId}`;
+    const firstRef = uuidFromDigest(`${seed}\0object`);
+    // Never let the cleanup path name the private source object, even for a
+    // deliberately crafted/imported source id that collides with the first
+    // deterministic locator.
+    const shareRef = firstRef === sourceArchiveId ? uuidFromDigest(`${seed}\0object-alternate`) : firstRef;
+    const id = createHash("sha256").update(`${seed}\0job`).digest("hex");
+    return { id, shareRef };
+}
+function retryAt(attempts, now) {
+    const delay = Math.min(60 * 60_000, 5_000 * 2 ** Math.min(Math.max(0, attempts - 1), 10));
+    return new Date(now + delay).toISOString();
+}
+function errorCode(error) {
+    if (isSealkeepError(error))
+        return error.code;
+    const code = error?.code;
+    if (typeof code === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(code))
+        return code;
+    const name = error instanceof Error ? error.name : "unexpected_error";
+    return /^[A-Za-z0-9_-]{1,64}$/.test(name) ? name : "unexpected_error";
+}
+function jobIsCurrent(ledger, job) {
+    const scope = ledger.scopes[job.spaceKey];
+    return Boolean(scope
+        && scope.rosterHash === job.rosterHash
+        && scope.membership_version !== undefined
+        && scope.membership_version === job.membership_version
+        && scope.sourceArchiveIds.includes(job.sourceArchiveId));
+}
+async function claimExpired(dataDir, job, now) {
+    if (!job.claim)
+        return true;
+    if (job.claim.processId)
+        return !await processOwnerAlive(dataDir, job.claim);
+    // A legacy claim has no start/instance marker, so a live PID is the only
+    // evidence available. Age must not steal work from that live owner; the
+    // conservative cost is that PID reuse can hold a pre-upgrade claim until
+    // that unrelated process exits. Every new claim is identity-fenced above.
+    void now;
+    return !processAlive(job.claim.pid);
+}
+/**
+ * Discover exact old-history work and persist it before any bytes move.
+ * Network failures leave the previous durable plan alone; they never turn an
+ * unknown roster into a guessed recipient set.
+ */
+export async function scheduleTeamHistoryBackfill(dataDir, now = Date.now(), inventory = {}, options = {}) {
+    options.signal?.throwIfAborted();
+    const config = await readConfig(dataDir);
+    if (config.storageMode === "plain")
+        return 0;
+    const bindings = Object.entries(config.teamSpaces ?? {}).filter(([, binding]) => binding.localConfirmed === true);
+    const previous = await readLedger(dataDir);
+    // A fresh daemon has no team-history work until a folder is confirmed. Do
+    // not turn the independent three-second lane into an exhaustive archive
+    // inventory poll (or rewrite an already-empty ledger) in that common state.
+    if (bindings.length === 0 && ledgerIsEmpty(previous))
+        return 0;
+    const activeSpaceKeys = new Set(bindings.map(([, binding]) => binding.spaceKey));
+    const grouped = new Map();
+    for (const [bindingKey, binding] of bindings) {
+        const keyed = STABLE_PROJECT_KEY.test(bindingKey);
+        const existing = grouped.get(binding.spaceKey);
+        if (existing) {
+            if (keyed)
+                existing.projectKeys.add(bindingKey);
+            else
+                existing.legacyProjects.add(bindingKey);
+            continue;
+        }
+        grouped.set(binding.spaceKey, {
+            spaceKey: binding.spaceKey,
+            project: binding.localProject ?? bindingKey,
+            ...(keyed ? { projectKey: bindingKey } : {}),
+            projectKeys: new Set(keyed ? [bindingKey] : []),
+            legacyProjects: new Set(keyed ? [] : [bindingKey]),
+        });
+    }
+    const { getTeamRoster, listTeamArchives } = await import("./cloud.js");
+    const remote = (operation, action) => {
+        const deadline = createProgressDeadline({
+            operation,
+            idleMs: Math.max(100, options.idleMs ?? 2 * 60_000),
+            signal: options.signal,
+        });
+        return deadline.wait(action(deadline.signal)).finally(() => deadline.close());
+    };
+    const plans = [];
+    let planningError;
+    for (const group of grouped.values()) {
+        try {
+            const roster = await remote("Reading the team roster for history sharing", (signal) => getTeamRoster(dataDir, group.spaceKey, undefined, { signal }));
+            const members = roster.members;
+            const memberPublicKeys = [...new Set(members.map((member) => member.public_key).filter(Boolean))].sort();
+            // A real space always includes its owner. Empty means the roster could
+            // not be proven, never "share to nobody".
+            if (!memberPublicKeys.length)
+                continue;
+            plans.push({
+                ...group,
+                members,
+                membership_version: roster.membership_version,
+                memberPublicKeys,
+                rosterHash: rosterHash(members, roster.membership_version),
+                grants: new Set(),
+                bindingHash: createHash("sha256").update([
+                    ...[...group.projectKeys].map((key) => `key:${key}`),
+                    ...[...group.legacyProjects].map((label) => `legacy:${label}`),
+                ].sort().join("\0")).digest("hex"),
+            });
+        }
+        catch (error) {
+            // Keep the durable scope unchanged, but do not report a stale roster as
+            // successfully reconciled. The daemon turns this failure into visible
+            // attention state and retries on its independent background lane.
+            planningError ??= error;
+        }
+    }
+    if (planningError)
+        throw planningError;
+    // Archive creation changes the storage-root directory entry set.  Once a
+    // confirmed binding + roster has been scanned, this cheap filename digest
+    // avoids reopening and re-deriving every historical transcript every three
+    // seconds. Upload/status metadata edits keep the same filenames and do not
+    // cause a pointless full rescan.
+    const readArchiveNames = inventory.readArchiveNames ?? ((storageRoot) => readdir(storageRoot));
+    const statArchive = inventory.statArchive ?? (async (path) => {
+        const item = await stat(path).catch(() => null);
+        return item ? { size: item.size, mtimeMs: item.mtimeMs } : null;
+    });
+    const archiveNames = (await readArchiveNames(config.storage.root).catch(() => []))
+        .filter((name) => name.endsWith(".json")).sort();
+    const archiveStats = await mapLimit(archiveNames, 24, async (name) => {
+        options.signal?.throwIfAborted();
+        const item = await statArchive(join(config.storage.root, name)).catch(() => null);
+        return item ? `${name}:${item.size}:${item.mtimeMs}` : `${name}:missing`;
+    }, inventory.yieldAfterStat ?? yieldToEventLoop);
+    // Directory mtimes also change for temporary/upload metadata and caused a
+    // full identity scan every few seconds. Record-file facts change only when
+    // the actual archive inventory or a record repair changes.
+    const archiveInventoryHash = createHash("sha256").update(archiveStats.join("\0")).digest("hex");
+    const needsScan = Object.keys(previous.scopes).some((spaceKey) => !activeSpaceKeys.has(spaceKey))
+        || plans.some((plan) => {
+            const prior = previous.scopes[plan.spaceKey];
+            return !prior
+                || prior.rosterHash !== plan.rosterHash
+                || prior.membership_version !== plan.membership_version
+                || prior.bindingHash !== plan.bindingHash
+                || prior.archiveInventoryHash !== archiveInventoryHash;
+        });
+    if (!needsScan)
+        return 0;
+    // An unchanged plan does not consume grant inventory. Keep the roster read
+    // fresh on every pass, but fetch grants only for an actual scan, before any
+    // ledger mutation. A failed read must preserve the previous durable plan.
+    for (const plan of plans) {
+        const grants = await remote("Reading existing team history grants", (signal) => listTeamArchives(dataDir, plan.spaceKey, undefined, { signal }));
+        plan.grants = new Set(grants
+            .filter((grant) => grant.membership_version === plan.membership_version)
+            .map((grant) => grant.vault_ref));
+    }
+    if (plans.length === 0) {
+        return mutateLedger(dataDir, (ledger) => {
+            for (const [spaceKey] of Object.entries(ledger.scopes)) {
+                if (!activeSpaceKeys.has(spaceKey))
+                    delete ledger.scopes[spaceKey];
+            }
+            for (const job of Object.values(ledger.jobs)) {
+                if (!activeSpaceKeys.has(job.spaceKey) && job.stage !== "superseded") {
+                    job.cleanupNeeded = true;
+                    job.stage = "superseded";
+                    job.updatedAt = new Date(now).toISOString();
+                }
+            }
+            return 0;
+        });
+    }
+    const records = (await listArchives(dataDir)).filter(isV2);
+    const { projectIdentityOfRecord } = await import("./adapters.js");
+    const identities = new Map();
+    await mapLimit(records, 12, async (record) => {
+        options.signal?.throwIfAborted();
+        identities.set(record.id, await projectIdentityOfRecord(record).catch(() => ({ project: null, projectKey: null, projectPath: null })));
+    });
+    const recordsById = new Map(records.map((record) => [record.id, record]));
+    const observed = new Map();
+    for (const plan of plans) {
+        const candidates = new Map();
+        for (const record of records) {
+            const identity = identities.get(record.id);
+            const matches = record.source.projectScope
+                ? record.source.projectScope === plan.spaceKey
+                : identity.projectKey
+                    ? plan.projectKeys.has(identity.projectKey)
+                    : Boolean(identity.project && plan.legacyProjects.has(identity.project));
+            if (!matches)
+                continue;
+            // Only a roster-exclusive object represents this exact generation.
+            // "Contains every current key" is insufficient: it can retain a removed
+            // teammate as an extra recipient and become readable again on re-add.
+            if (archiveWrapsExactlyMembers(record, plan.memberPublicKeys) && plan.grants.has(record.id))
+                continue;
+            candidates.set(record.id, record);
+        }
+        // A delta authorizes its proven prefix as part of the same logical
+        // session. Pull the complete chain into the plan even when an older base
+        // predates project metadata; never inherit across a different source path
+        // or agent. Without this closure the head would advertise a base ref the
+        // team cannot fetch, which is worse than visibly blocking the chain.
+        const includeBases = (record, seen = new Set()) => {
+            if (!record.delta || seen.has(record.id))
+                return;
+            seen.add(record.id);
+            const base = recordsById.get(record.delta.baseArchiveId);
+            if (!base
+                || base.source.bytes !== record.delta.baseBytes
+                || base.source.path !== record.source.path
+                || base.source.agent !== record.source.agent)
+                return;
+            candidates.set(base.id, base);
+            includeBases(base, seen);
+        };
+        for (const record of [...candidates.values()])
+            includeBases(record);
+        observed.set(plan.spaceKey, { plan, candidates });
+    }
+    return mutateLedger(dataDir, async (ledger) => {
+        let scheduled = 0;
+        // A local unbind is definitive. A cloud outage is not: only retire an
+        // absent scope when it is no longer configured locally at all.
+        for (const [spaceKey] of Object.entries(ledger.scopes)) {
+            if (!activeSpaceKeys.has(spaceKey))
+                delete ledger.scopes[spaceKey];
+        }
+        for (const job of Object.values(ledger.jobs)) {
+            if (!activeSpaceKeys.has(job.spaceKey) && job.stage !== "superseded") {
+                job.cleanupNeeded = true;
+                job.stage = "superseded";
+                job.updatedAt = new Date(now).toISOString();
+            }
+        }
+        for (const [spaceKey, { plan, candidates }] of observed) {
+            const sourceIds = [...candidates.keys()].sort();
+            ledger.scopes[spaceKey] = {
+                rosterHash: plan.rosterHash,
+                membership_version: plan.membership_version,
+                sourceArchiveIds: sourceIds,
+                observedAt: new Date(now).toISOString(),
+                bindingHash: plan.bindingHash,
+                archiveInventoryHash,
+            };
+            for (const job of Object.values(ledger.jobs)) {
+                if (job.spaceKey !== spaceKey)
+                    continue;
+                if (job.rosterHash !== plan.rosterHash || !sourceIds.includes(job.sourceArchiveId)) {
+                    job.cleanupNeeded = true;
+                    if (job.stage === "superseded")
+                        continue;
+                    job.stage = "superseded";
+                    job.updatedAt = new Date(now).toISOString();
+                }
+            }
+            // A blocked dependency graph is a snapshot, not a terminal verdict.
+            // Rebuild it whenever archive record facts changed so a repaired or
+            // newly restored delta base can unblock the same roster automatically.
+            for (const [jobId, job] of Object.entries(ledger.jobs)) {
+                if (job.spaceKey === spaceKey && job.rosterHash === plan.rosterHash && job.stage === "blocked") {
+                    delete ledger.jobs[jobId];
+                }
+            }
+            const visiting = new Set();
+            const ensureJob = (record) => {
+                const identity = jobIdentity(spaceKey, plan.rosterHash, record.id);
+                const sourceIdentity = identities.get(record.id);
+                const sourceProject = sourceIdentity?.project ?? record.source.project ?? plan.project;
+                const sourceProjectKey = sourceIdentity?.projectKey ?? record.source.projectKey ?? undefined;
+                const existing = ledger.jobs[identity.id];
+                if (existing) {
+                    existing.sourceCreatedAt = record.createdAt;
+                    // A ledger written before roster CAS has no membership version and
+                    // therefore cannot prove that a prior grant was attested for this
+                    // snapshot. Preserve its verified object, but force registration
+                    // through the strict versioned path before it can be published.
+                    if (existing.membership_version !== plan.membership_version) {
+                        existing.membership_version = plan.membership_version;
+                        existing.memberPublicKeys = plan.memberPublicKeys;
+                        existing.stage = existing.remote?.verifiedAt
+                            ? "uploaded"
+                            : existing.envelope ? "prepared" : "pending";
+                        existing.cleanupNeeded = false;
+                        delete existing.cleanupError;
+                        delete existing.blockedReason;
+                        delete existing.claim;
+                        delete existing.nextAttemptAt;
+                        delete existing.lastError;
+                        existing.updatedAt = new Date(now).toISOString();
+                    }
+                    if (existing.stage === "superseded") {
+                        if (existing.claim && existing.cleanupNeeded)
+                            return existing;
+                        existing.cleanupNeeded = false;
+                        delete existing.cleanupError;
+                        existing.stage = existing.remote?.verifiedAt
+                            ? (plan.grants.has(existing.shareRef) ? "registered" : "uploaded")
+                            : existing.envelope ? "prepared" : "pending";
+                        existing.updatedAt = new Date(now).toISOString();
+                    }
+                    return existing;
+                }
+                if (visiting.has(record.id)) {
+                    const circular = {
+                        version: 1, ...identity, sourceArchiveId: record.id, spaceKey,
+                        project: sourceProject, ...(sourceProjectKey ? { projectKey: sourceProjectKey } : {}),
+                        rosterHash: plan.rosterHash, memberPublicKeys: plan.memberPublicKeys,
+                        membership_version: plan.membership_version,
+                        dependencyJobIds: [], dependencyRefs: [], stage: "blocked",
+                        blockedReason: "delta_cycle", attempts: 0,
+                        createdAt: new Date(now).toISOString(), updatedAt: new Date(now).toISOString(),
+                    };
+                    ledger.jobs[identity.id] = circular;
+                    scheduled += 1;
+                    return circular;
+                }
+                visiting.add(record.id);
+                const dependencyJobs = [];
+                let blockedReason;
+                if (record.delta) {
+                    const base = candidates.get(record.delta.baseArchiveId);
+                    if (!base)
+                        blockedReason = recordsById.has(record.delta.baseArchiveId) ? "delta_base_outside_project" : "delta_base_missing";
+                    else if (base.source.bytes !== record.delta.baseBytes)
+                        blockedReason = "delta_base_length_mismatch";
+                    else if (base.source.path !== record.source.path || base.source.agent !== record.source.agent)
+                        blockedReason = "delta_base_identity_mismatch";
+                    else
+                        dependencyJobs.push(ensureJob(base));
+                }
+                visiting.delete(record.id);
+                const job = {
+                    version: 1, ...identity, sourceArchiveId: record.id, spaceKey,
+                    sourceCreatedAt: record.createdAt,
+                    project: sourceProject, ...(sourceProjectKey ? { projectKey: sourceProjectKey } : {}),
+                    rosterHash: plan.rosterHash, memberPublicKeys: plan.memberPublicKeys,
+                    membership_version: plan.membership_version,
+                    dependencyJobIds: dependencyJobs.map((dependency) => dependency.id),
+                    dependencyRefs: dependencyJobs.map((dependency) => dependency.shareRef),
+                    stage: blockedReason || dependencyJobs.some((dependency) => dependency.stage === "blocked") ? "blocked" : "pending",
+                    ...(blockedReason ? { blockedReason } : dependencyJobs.some((dependency) => dependency.stage === "blocked") ? { blockedReason: "delta_base_blocked" } : {}),
+                    attempts: 0,
+                    createdAt: new Date(now).toISOString(), updatedAt: new Date(now).toISOString(),
+                };
+                ledger.jobs[job.id] = job;
+                scheduled += 1;
+                return job;
+            };
+            for (const record of candidates.values())
+                ensureJob(record);
+        }
+        return scheduled;
+    });
+}
+async function claimNextJob(dataDir, now) {
+    return mutateLedger(dataDir, async (ledger) => {
+        const waiting = Object.values(ledger.jobs)
+            .filter((job) => ["pending", "prepared", "uploaded"].includes(job.stage))
+            .filter((job) => jobIsCurrent(ledger, job));
+        const eligible = waiting
+            .filter((job) => !job.nextAttemptAt || Date.parse(job.nextAttemptAt) <= now)
+            .filter((job) => job.dependencyJobIds.every((id) => {
+            const dependency = ledger.jobs[id];
+            return dependency && ["registered", "indexed"].includes(dependency.stage);
+        }));
+        const candidates = orderTeamBackfillJobs(waiting, eligible, ledger.scheduleSequence ?? 0);
+        let job;
+        for (const candidate of candidates) {
+            if (await claimExpired(dataDir, candidate, now)) {
+                job = candidate;
+                break;
+            }
+        }
+        if (!job)
+            return null;
+        ledger.scheduleSequence = ((ledger.scheduleSequence ?? 0) + 1) % 4;
+        job.lastScheduledAt = new Date(now).toISOString();
+        const processStart = await currentProcessStart();
+        job.claim = {
+            token: randomUUID(), pid: process.pid, processId: PROCESS_INSTANCE_ID,
+            ...(processStart ? { processStart } : {}), at: now,
+        };
+        job.updatedAt = new Date(now).toISOString();
+        return structuredClone(job);
+    });
+}
+async function renewClaim(dataDir, claimed) {
+    return mutateLedger(dataDir, (ledger) => {
+        const job = ledger.jobs[claimed.id];
+        const claim = job?.claim;
+        if (!job || !claim || claim.token !== claimed.claim?.token || claim.processId !== PROCESS_INSTANCE_ID)
+            return false;
+        claim.at = Date.now();
+        job.updatedAt = new Date().toISOString();
+        return true;
+    });
+}
+function keepClaimRenewed(dataDir, claimed) {
+    let lastProgressAt = Date.now();
+    const timer = setInterval(() => {
+        // A clock alone must never keep a wedged provider operation's ownership
+        // alive forever. Renew only while bytes or durable stages have advanced
+        // since the preceding renewal window; an idle deadline then releases the
+        // claim for a clean retry.
+        if (Date.now() - lastProgressAt > CLAIM_RENEW_MS + 5_000)
+            return;
+        void renewClaim(dataDir, claimed).catch(() => undefined);
+    }, CLAIM_RENEW_MS);
+    timer.unref();
+    return {
+        progress: () => { lastProgressAt = Date.now(); },
+        stop: () => clearInterval(timer),
+    };
+}
+async function claimNextCleanup(dataDir, now) {
+    return mutateLedger(dataDir, async (ledger) => {
+        const candidates = Object.values(ledger.jobs)
+            .filter((job) => job.stage === "superseded" && job.cleanupNeeded)
+            .filter((job) => !job.nextAttemptAt || Date.parse(job.nextAttemptAt) <= now)
+            .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt) || left.id.localeCompare(right.id));
+        let job;
+        for (const candidate of candidates) {
+            if (await claimExpired(dataDir, candidate, now)) {
+                job = candidate;
+                break;
+            }
+        }
+        if (!job)
+            return null;
+        const processStart = await currentProcessStart();
+        job.claim = {
+            token: randomUUID(), pid: process.pid, processId: PROCESS_INSTANCE_ID,
+            ...(processStart ? { processStart } : {}), at: now,
+        };
+        return structuredClone(job);
+    });
+}
+async function commitClaim(dataDir, claimed, change) {
+    return mutateLedger(dataDir, (ledger) => {
+        const job = ledger.jobs[claimed.id];
+        if (!job || job.claim?.token !== claimed.claim?.token)
+            return null;
+        change(job, ledger);
+        job.updatedAt = new Date().toISOString();
+        if (job.claim)
+            job.claim.at = Date.now();
+        return structuredClone(job);
+    });
+}
+async function rosterIsCurrent(dataDir, job, work) {
+    work.signal.throwIfAborted();
+    const config = await readConfig(dataDir);
+    const stillBound = Object.values(config.teamSpaces ?? {})
+        .some((binding) => binding.spaceKey === job.spaceKey && binding.localConfirmed === true);
+    if (!stillBound)
+        return false;
+    const { getTeamRoster } = await import("./cloud.js");
+    const roster = await getTeamRoster(dataDir, job.spaceKey, undefined, { signal: work.signal });
+    work.progress();
+    return roster.membership_version === job.membership_version
+        && rosterHash(roster.members, roster.membership_version) === job.rosterHash;
+}
+function sameSealedDescriptor(left, right) {
+    const withoutWraps = (value) => {
+        const { wrappedKeys: _ignored, ...descriptor } = value;
+        return descriptor;
+    };
+    return JSON.stringify(withoutWraps(left)) === JSON.stringify(withoutWraps(right));
+}
+async function recoverExistingHostedFrame(dataDir, claimed, source, phrase, work) {
+    const cloud = await import("./cloud.js");
+    const present = await cloud.statCiphertext(dataDir, claimed.shareRef, undefined, { signal: work.signal, allowIncomplete: true });
+    work.progress();
+    if (!present.exists)
+        return present.incompleteUpload ? { incompleteUpload: present.incompleteUpload } : null;
+    const rate = backgroundUploadBytesPerSecond(await readLocalSettings(dataDir));
+    const cooperate = createBackgroundCpuYield({ target: 0.30, signal: work.signal });
+    const pacedRead = {
+        signal: work.signal, maxBytesPerSecond: rate,
+        onProgress: () => work.progress(), onYield: cooperate,
+    };
+    const prefix = await cloud.pullCiphertextRange(dataDir, claimed.shareRef, 0, 8, undefined, pacedRead);
+    work.progress();
+    if (prefix.length !== 8 || prefix.subarray(0, 4).toString("ascii") !== "VLA1")
+        throw new TeamBackfillConflictError();
+    const metadataBytes = prefix.readUInt32BE(4);
+    const { MAX_FRAME_METADATA_BYTES } = await import("./byte-stream.js");
+    if (metadataBytes <= 0 || metadataBytes > MAX_FRAME_METADATA_BYTES)
+        throw new TeamBackfillConflictError();
+    const header = await cloud.pullCiphertextRange(dataDir, claimed.shareRef, 0, 8 + metadataBytes, undefined, {
+        ...pacedRead, maxBytes: MAX_FRAME_METADATA_BYTES + 8,
+    });
+    work.progress();
+    if (header.length !== 8 + metadataBytes)
+        throw new TeamBackfillConflictError();
+    let candidate;
+    try {
+        candidate = cloud.unframeObject(header).envelope;
+    }
+    catch {
+        throw new TeamBackfillConflictError();
+    }
+    if (!candidate || !sameSealedDescriptor(candidate, source.envelope))
+        throw new TeamBackfillConflictError();
+    const virtual = { ...source, envelope: candidate };
+    if (!archiveWrapsExactlyMembers(virtual, claimed.memberPublicKeys))
+        throw new TeamBackfillConflictError();
+    const bodyHash = createHash("sha256");
+    const framedHash = createHash("sha256").update(header);
+    let bodyBytes = 0;
+    const framed = await cloud.pullCiphertextStream(dataDir, claimed.shareRef, undefined, {
+        ...pacedRead,
+        maxBytes: present.bytes,
+    });
+    // Pace the complete framed object before removing metadata. A retry must
+    // share the same vault-wide budget as uploads, not download an entire
+    // completed archive at line speed just to adopt its prior ledger entry.
+    for await (const chunk of unframeChunks(framed)) {
+        bodyHash.update(chunk);
+        framedHash.update(chunk);
+        bodyBytes += chunk.length;
+        work.progress();
+        await cooperate();
+    }
+    if (bodyBytes !== source.cipher.storedBytes || bodyHash.digest("hex") !== source.cipher.ciphertextSha256) {
+        throw new TeamBackfillConflictError();
+    }
+    // New jobs are deterministic, so an exact regenerated envelope already
+    // proves every wrap. Keep the key-opening path for frames written by the
+    // earlier randomized implementation and safely adopt those too.
+    if (JSON.stringify(candidate) === JSON.stringify(claimed.envelope)) {
+        return {
+            envelope: candidate,
+            remote: {
+                provider: "vaultline", bucket: "vaultline-managed", objectKey: claimed.shareRef,
+                bytes: present.bytes, checksum: framedHash.digest("hex"), verifiedAt: new Date().toISOString(),
+            },
+        };
+    }
+    const { ensureTeamIdentity } = await import("./team-presence.js");
+    const privateRaw = Buffer.from((await ensureTeamIdentity(dataDir, phrase)).privateKey, "base64");
+    let sourceKey;
+    let candidateKey;
+    try {
+        // Descriptor equality proves the ciphertext identity; key equality proves
+        // the hosted recipient wraps actually open that same archive key.
+        sourceKey = unwrapArchiveKey(source.envelope.wrappedKeys, source.envelope.suite, source.envelope.archiveId, { phrase });
+        candidateKey = unwrapArchiveKey(candidate.wrappedKeys, candidate.suite, candidate.archiveId, { privateKey: x25519PrivateKeyFromRaw(privateRaw) });
+        if (sourceKey.length !== candidateKey.length || !timingSafeEqual(sourceKey, candidateKey))
+            throw new TeamBackfillConflictError();
+    }
+    catch {
+        throw new TeamBackfillConflictError();
+    }
+    finally {
+        sourceKey?.fill(0);
+        candidateKey?.fill(0);
+        privateRaw.fill(0);
+    }
+    return {
+        envelope: candidate,
+        remote: {
+            provider: "vaultline", bucket: "vaultline-managed", objectKey: claimed.shareRef,
+            bytes: present.bytes, checksum: framedHash.digest("hex"), verifiedAt: new Date().toISOString(),
+        },
+    };
+}
+async function processClaim(dataDir, phrase, initial, recordsById, work) {
+    let claimed = initial;
+    let uploaded = false;
+    let registered = false;
+    for (;;) {
+        work.signal.throwIfAborted();
+        const source = recordsById.get(claimed.sourceArchiveId);
+        if (!source)
+            throw new Error("source_archive_missing");
+        if (claimed.stage === "pending") {
+            const envelope = deterministicTeamEnvelope(source, phrase, claimed);
+            const next = await commitClaim(dataDir, claimed, (job, ledger) => {
+                if (!jobIsCurrent(ledger, job)) {
+                    job.stage = "superseded";
+                    delete job.claim;
+                    return;
+                }
+                job.envelope = envelope;
+                job.stage = "prepared";
+                delete job.nextAttemptAt;
+                delete job.lastError;
+            });
+            work.progress();
+            if (!next || next.stage === "superseded")
+                return { uploaded, registered };
+            claimed = next;
+            continue;
+        }
+        if (claimed.stage === "prepared") {
+            if (!claimed.envelope)
+                throw new Error("prepared_envelope_missing");
+            if (!await rosterIsCurrent(dataDir, claimed, work)) {
+                await commitClaim(dataDir, claimed, (job) => { job.stage = "superseded"; delete job.claim; });
+                return { uploaded, registered };
+            }
+            // The deterministic locator may already hold a completed upload from a
+            // worker that crashed before its ledger commit, or from a lost ledger.
+            // Adopt only a fully verified, descriptor-identical frame. A different
+            // object is a permanent conflict and is never overwritten/granted.
+            const recovered = await recoverExistingHostedFrame(dataDir, claimed, source, phrase, work);
+            if (recovered && !('incompleteUpload' in recovered)) {
+                const next = await commitClaim(dataDir, claimed, (job, ledger) => {
+                    if (!jobIsCurrent(ledger, job)) {
+                        job.stage = "superseded";
+                        job.cleanupNeeded = true;
+                        delete job.claim;
+                        return;
+                    }
+                    job.envelope = recovered.envelope;
+                    job.remote = recovered.remote;
+                    job.stage = "uploaded";
+                    delete job.nextAttemptAt;
+                    delete job.lastError;
+                });
+                work.progress();
+                if (!next || next.stage === "superseded")
+                    return { uploaded, registered };
+                claimed = next;
+                continue;
+            }
+            const { materialiseArchive } = await import("./offload.js");
+            const materialised = await materialiseArchive(dataDir, source, undefined, {
+                signal: work.signal,
+                onProgress: () => work.progress(),
+                maxBytesPerSecond: backgroundUploadBytesPerSecond(await readLocalSettings(dataDir)),
+                onYield: createBackgroundCpuYield({ target: 0.30, signal: work.signal }),
+            });
+            try {
+                const { pushFramedArchive } = await import("./cloud.js");
+                const result = await pushFramedArchive(dataDir, {
+                    vaultRef: claimed.shareRef,
+                    envelope: claimed.envelope,
+                    ciphertextPath: materialised.path,
+                    ciphertextSha256: source.cipher.ciphertextSha256,
+                    ciphertextBytes: source.cipher.storedBytes,
+                }, undefined, {
+                    signal: work.signal,
+                    incompleteUpload: recovered && 'incompleteUpload' in recovered ? recovered.incompleteUpload : undefined,
+                    onProgress: () => work.progress(),
+                    maxBytesPerSecond: backgroundUploadBytesPerSecond(await readLocalSettings(dataDir)),
+                    onYield: createBackgroundCpuYield({ target: 0.30, signal: work.signal }),
+                });
+                work.progress();
+                if (!result.durable)
+                    throw new Error("managed_copy_not_verified");
+                const next = await commitClaim(dataDir, claimed, (job, ledger) => {
+                    if (!jobIsCurrent(ledger, job)) {
+                        job.stage = "superseded";
+                        job.cleanupNeeded = true;
+                        delete job.claim;
+                        return;
+                    }
+                    job.remote = {
+                        provider: "vaultline", bucket: "vaultline-managed", objectKey: result.objectKey,
+                        bytes: result.bytes, checksum: result.checksum ?? "", verifiedAt: new Date().toISOString(),
+                    };
+                    job.stage = "uploaded";
+                    delete job.nextAttemptAt;
+                    delete job.lastError;
+                });
+                work.progress();
+                uploaded = true;
+                if (!next || next.stage === "superseded")
+                    return { uploaded, registered };
+                claimed = next;
+            }
+            finally {
+                await materialised.release();
+            }
+            continue;
+        }
+        if (claimed.stage === "uploaded") {
+            if (!claimed.envelope || !claimed.remote?.verifiedAt)
+                throw new Error("verified_copy_missing");
+            if (!await rosterIsCurrent(dataDir, claimed, work)) {
+                await commitClaim(dataDir, claimed, (job) => { job.stage = "superseded"; job.cleanupNeeded = true; delete job.claim; });
+                return { uploaded, registered };
+            }
+            const { listTeamArchives, registerTeamArchive } = await import("./cloud.js");
+            if (!claimed.membership_version)
+                throw new Error("team_roster_version_missing");
+            const existing = await listTeamArchives(dataDir, claimed.spaceKey, undefined, { signal: work.signal });
+            work.progress();
+            if (!existing.some((row) => row.vault_ref === claimed.shareRef && row.membership_version === claimed.membership_version)) {
+                await registerTeamArchive(dataDir, claimed.spaceKey, claimed.shareRef, claimed.membership_version, undefined, { signal: work.signal });
+                work.progress();
+            }
+            // The hosted registration CAS closes changes that commit before this
+            // grant. A change can still commit immediately afterwards, so the
+            // post-check remains the publication fence and queues durable cleanup.
+            if (!await rosterIsCurrent(dataDir, claimed, work)) {
+                await commitClaim(dataDir, claimed, (job) => {
+                    job.stage = "superseded";
+                    job.cleanupNeeded = true;
+                    job.blockedReason = "roster_changed_during_registration";
+                    delete job.claim;
+                });
+                return { uploaded, registered: false };
+            }
+            await commitClaim(dataDir, claimed, (job, ledger) => {
+                if (!jobIsCurrent(ledger, job)) {
+                    job.stage = "superseded";
+                    job.cleanupNeeded = true;
+                    delete job.claim;
+                    return;
+                }
+                job.stage = "registered";
+                job.attempts = 0;
+                delete job.claim;
+                delete job.nextAttemptAt;
+                delete job.lastError;
+            });
+            work.progress();
+            registered = true;
+            return { uploaded, registered };
+        }
+        return { uploaded, registered };
+    }
+}
+async function processCleanupClaim(dataDir, claimed, work) {
+    const { deleteCloudArchive, getTeamRoster, statCiphertext, unregisterTeamArchive } = await import("./cloud.js");
+    const roster = await getTeamRoster(dataDir, claimed.spaceKey, undefined, { signal: work.signal });
+    work.progress();
+    await unregisterTeamArchive(dataDir, claimed.spaceKey, claimed.shareRef, roster.membership_version, undefined, { signal: work.signal });
+    work.progress();
+    const present = await statCiphertext(dataDir, claimed.shareRef, undefined, { signal: work.signal });
+    work.progress();
+    if (present.exists) {
+        await deleteCloudArchive(dataDir, claimed.shareRef, undefined, { signal: work.signal });
+        work.progress();
+    }
+    await commitClaim(dataDir, claimed, (job, ledger) => {
+        const currentAgain = jobIsCurrent(ledger, job);
+        job.cleanupNeeded = false;
+        delete job.cleanupError;
+        delete job.remote;
+        delete job.claim;
+        delete job.nextAttemptAt;
+        if (currentAgain)
+            job.stage = job.envelope ? "prepared" : "pending";
+    });
+    work.progress();
+}
+/** Drain a bounded number of durable jobs. Every stage is committed separately. */
+export async function drainTeamHistoryBackfill(dataDir, rawPhrase, options = {}) {
+    options.signal?.throwIfAborted();
+    const phrase = canonicalPhrase(rawPhrase);
+    const config = await readConfig(dataDir);
+    if (!matchesPhraseCheck(config.recovery.phraseCheck, phrase))
+        throw new Error("recovery_phrase_mismatch");
+    const requestedLimit = options.limit ?? 1;
+    if (!Number.isSafeInteger(requestedLimit) || requestedLimit < 0)
+        throw new Error("invalid_backfill_limit");
+    const limit = Math.min(128, requestedLimit);
+    if (options.maxBatchMs !== undefined && (!Number.isFinite(options.maxBatchMs) || options.maxBatchMs <= 0))
+        throw new Error("invalid_backfill_batch_budget");
+    // A batch budget prevents starting more work; it never abandons an archive
+    // halfway through its durable publication or weakens the per-job deadline.
+    const batchStarted = performance.now();
+    const batchExpired = () => processed > 0 && options.maxBatchMs !== undefined && performance.now() - batchStarted >= options.maxBatchMs;
+    const clock = options.now ?? Date.now;
+    let processed = 0;
+    let uploaded = 0;
+    let registered = 0;
+    const recordsById = new Map((await listArchives(dataDir)).filter(isV2).map((record) => [record.id, record]));
+    const runClaim = async (claimed, operation, action) => {
+        const renewal = keepClaimRenewed(dataDir, claimed);
+        const deadline = createProgressDeadline({
+            operation,
+            idleMs: Math.max(100, options.idleMs ?? 2 * 60_000),
+            signal: options.signal,
+        });
+        const progress = () => {
+            renewal.progress();
+            deadline.progress();
+        };
+        try {
+            return await deadline.wait(action({ signal: deadline.signal, progress }));
+        }
+        finally {
+            deadline.close();
+            renewal.stop();
+        }
+    };
+    while (processed < limit && !batchExpired()) {
+        options.signal?.throwIfAborted();
+        const claimed = await claimNextJob(dataDir, clock());
+        if (!claimed)
+            break;
+        processed += 1;
+        try {
+            const outcome = await runClaim(claimed, "Sharing earlier project memory", (work) => processClaim(dataDir, phrase, claimed, recordsById, work));
+            if (outcome.uploaded)
+                uploaded += 1;
+            if (outcome.registered)
+                registered += 1;
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                await commitClaim(dataDir, claimed, (job) => {
+                    delete job.claim;
+                    job.nextAttemptAt = new Date(clock()).toISOString();
+                });
+                throw options.signal.reason ?? error;
+            }
+            await commitClaim(dataDir, claimed, (job) => {
+                job.attempts += 1;
+                job.lastError = errorCode(error);
+                if (job.lastError === "derived_ref_conflict") {
+                    job.stage = "blocked";
+                    job.blockedReason = "derived_ref_conflict";
+                    delete job.nextAttemptAt;
+                }
+                else {
+                    job.nextAttemptAt = retryAt(job.attempts, clock());
+                }
+                delete job.claim;
+            });
+        }
+    }
+    while (processed < limit && !batchExpired()) {
+        options.signal?.throwIfAborted();
+        const claimed = await claimNextCleanup(dataDir, clock());
+        if (!claimed)
+            break;
+        processed += 1;
+        try {
+            await runClaim(claimed, "Removing obsolete shared project memory", (work) => processCleanupClaim(dataDir, claimed, work));
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                await commitClaim(dataDir, claimed, (job) => {
+                    delete job.claim;
+                    job.nextAttemptAt = new Date(clock()).toISOString();
+                });
+                throw options.signal.reason ?? error;
+            }
+            await commitClaim(dataDir, claimed, (job) => {
+                job.cleanupError = errorCode(error);
+                job.attempts += 1;
+                job.nextAttemptAt = retryAt(job.attempts, clock());
+                delete job.claim;
+            });
+        }
+    }
+    return { processed, uploaded, registered };
+}
+function summarizeJobs(jobs) {
+    const current = jobs.filter((job) => job.stage !== "superseded");
+    const cleanup = jobs.filter((job) => job.stage === "superseded" && job.cleanupNeeded);
+    const indexed = current.filter((job) => job.stage === "indexed").length;
+    const registered = current.filter((job) => job.stage === "registered").length;
+    const blocked = current.filter((job) => job.stage === "blocked").length;
+    const failed = current.filter((job) => Boolean(job.lastError)).length + cleanup.filter((job) => Boolean(job.cleanupError)).length;
+    const pending = current.length - indexed - blocked + cleanup.length;
+    const active = jobs.find((job) => job.claim);
+    const lastFailure = current.find((job) => job.lastError)?.lastError ?? cleanup.find((job) => job.cleanupError)?.cleanupError;
+    return {
+        state: blocked || failed ? "attention" : pending ? "working" : "idle",
+        total: current.length + cleanup.length, indexed, registered, pending, failed, blocked,
+        ...(active ? { activeArchiveId: active.sourceArchiveId } : {}),
+        ...(lastFailure ? { lastError: lastFailure } : {}),
+    };
+}
+export async function teamHistoryBackfillStatus(dataDir) {
+    let ledger;
+    try {
+        ledger = await readLedger(dataDir);
+    }
+    catch (error) {
+        if (!(error instanceof TeamBackfillLedgerError))
+            throw error;
+        return {
+            state: "attention", total: 0, indexed: 0, registered: 0, pending: 0, failed: 1, blocked: 0,
+            lastError: LEDGER_CORRUPT, spaces: {},
+        };
+    }
+    const spaces = {};
+    const spaceKeys = new Set([
+        ...Object.keys(ledger.scopes),
+        ...Object.values(ledger.jobs).filter((job) => job.stage !== "superseded" || job.cleanupNeeded).map((job) => job.spaceKey),
+    ]);
+    for (const spaceKey of spaceKeys) {
+        const scope = ledger.scopes[spaceKey];
+        spaces[spaceKey] = summarizeJobs(Object.values(ledger.jobs).filter((job) => job.spaceKey === spaceKey && (job.cleanupNeeded || Boolean(scope
+            && job.rosterHash === scope.rosterHash
+            && scope.sourceArchiveIds.includes(job.sourceArchiveId)))));
+    }
+    const total = Object.values(spaces).reduce((sum, item) => sum + item.total, 0);
+    const indexed = Object.values(spaces).reduce((sum, item) => sum + item.indexed, 0);
+    const registered = Object.values(spaces).reduce((sum, item) => sum + item.registered, 0);
+    const pending = Object.values(spaces).reduce((sum, item) => sum + item.pending, 0);
+    const failed = Object.values(spaces).reduce((sum, item) => sum + item.failed, 0);
+    const blocked = Object.values(spaces).reduce((sum, item) => sum + item.blocked, 0);
+    const lastError = Object.values(spaces).find((space) => space.lastError)?.lastError;
+    return {
+        state: blocked || failed ? "attention" : pending ? "working" : "idle",
+        total, indexed, registered, pending, failed, blocked,
+        ...(lastError ? { lastError } : {}),
+        spaces,
+    };
+}
+export async function reconcileTeamHistoryBackfill(dataDir, phrase, options = {}) {
+    options.signal?.throwIfAborted();
+    // Complete an accepted invitation's captured old-roster history before
+    // ordinary current-roster publications can establish a partial new head.
+    const { reconcileTeamInvitationHandoffs } = await import("./team-offboarding.js");
+    await reconcileTeamInvitationHandoffs(dataDir, phrase);
+    options.signal?.throwIfAborted();
+    if (await unconfiguredEmptyBackfill(dataDir)) {
+        const config = await readConfig(dataDir);
+        if (!matchesPhraseCheck(config.recovery.phraseCheck, canonicalPhrase(phrase)))
+            throw new Error("recovery_phrase_mismatch");
+        return {
+            state: "idle", total: 0, indexed: 0, registered: 0, pending: 0, failed: 0, blocked: 0,
+            spaces: {}, scheduled: 0, processed: 0, uploadedNow: 0, registeredNow: 0,
+        };
+    }
+    const scheduled = await scheduleTeamHistoryBackfill(dataDir, options.now?.() ?? Date.now(), options.inventory, { signal: options.signal, idleMs: options.idleMs });
+    options.signal?.throwIfAborted();
+    const drained = await drainTeamHistoryBackfill(dataDir, phrase, options);
+    return {
+        ...await teamHistoryBackfillStatus(dataDir),
+        scheduled,
+        processed: drained.processed,
+        uploadedNow: drained.uploaded,
+        registeredNow: drained.registered,
+    };
+}
+/** Current, verified, membership-wrapped jobs suitable for a team shard. */
+export async function teamHistoryBackfillPublications(dataDir, spaceKey, currentRosterSnapshot) {
+    const ledger = await readLedger(dataDir);
+    const scope = ledger.scopes[spaceKey];
+    const currentMembers = currentRosterSnapshot.members;
+    const currentRoster = rosterHash(currentMembers, currentRosterSnapshot.membership_version);
+    const currentMemberPublicKeys = currentMembers.map((member) => member.public_key);
+    if (!scope || scope.rosterHash !== currentRoster || scope.membership_version !== currentRosterSnapshot.membership_version)
+        return [];
+    const records = await listArchives(dataDir);
+    const recordsById = new Map(records.filter(isV2).map((record) => [record.id, record]));
+    const publications = [];
+    for (const job of Object.values(ledger.jobs)) {
+        if (job.spaceKey !== spaceKey || job.rosterHash !== currentRoster || job.membership_version !== currentRosterSnapshot.membership_version
+            || !scope.sourceArchiveIds.includes(job.sourceArchiveId))
+            continue;
+        if (!["registered", "indexed"].includes(job.stage) || !job.envelope || !job.remote?.verifiedAt)
+            continue;
+        const source = recordsById.get(job.sourceArchiveId);
+        if (!source)
+            continue;
+        const record = {
+            ...source,
+            id: job.shareRef,
+            source: { ...source.source, project: job.project, ...(job.projectKey ? { projectKey: job.projectKey } : {}), projectScope: spaceKey },
+            envelope: job.envelope,
+            objectPath: source.objectPath,
+            remote: job.remote,
+            copies: undefined,
+            offloaded: undefined,
+            ...(source.delta ? { delta: { ...source.delta, baseArchiveId: job.dependencyRefs[0] ?? source.delta.baseArchiveId } } : {}),
+        };
+        // Owner custody is private phrase-wrapped provenance for the source
+        // object. A roster alias has a distinct envelope and grant; carrying the
+        // marker across would both misclassify it and expose a private-custody fact
+        // in the shared catalog.
+        delete record.teamCustody;
+        if (!archiveWrapsExactlyMembers(record, currentMemberPublicKeys))
+            continue;
+        publications.push({ jobId: job.id, sourceArchiveId: job.sourceArchiveId, record });
+    }
+    return publications;
+}
+/** All refs ever produced for this space, used only to remove stale roster aliases. */
+export async function allTeamHistoryBackfillRefs(dataDir, spaceKey) {
+    const ledger = await readLedger(dataDir);
+    return new Set(Object.values(ledger.jobs).filter((job) => job.spaceKey === spaceKey).map((job) => job.shareRef));
+}
+export async function markTeamHistoryBackfillsIndexed(dataDir, jobIds) {
+    if (!jobIds.length)
+        return;
+    const selected = new Set(jobIds);
+    await mutateLedger(dataDir, (ledger) => {
+        for (const job of Object.values(ledger.jobs)) {
+            if (!selected.has(job.id) || job.stage !== "registered" || !jobIsCurrent(ledger, job))
+                continue;
+            job.stage = "indexed";
+            job.updatedAt = new Date().toISOString();
+            delete job.lastError;
+            delete job.nextAttemptAt;
+        }
+    });
+}