sealkeep 0.9.0 → 0.11.0

package/dist/src/stream-to-cloud.d.ts

@@ -1,4 +1,4 @@
-import type { ArchiveRecordV2 } from "./types.js";
+import { type ArchiveRecordV2 } from "./types.js";
 /**
  * Seal straight into the bucket: read a slice, compress it, encrypt it, send
  * it, forget it. The full ciphertext exists nowhere — not on this disk, not in
@@ -72,5 +72,9 @@ export declare function sealArchiveToCloud(dataDir: string, sourcePath: string,
     /** Resume an interrupted upload of this source when a journal for it exists. Defaults on; `--fresh` turns it off. */
     resume?: boolean;
     now?: number;
+    /** Storage-route identity stamped on the verified copy. */
+    targetId?: string;
+    project?: string | null;
+    projectKey?: string | null;
 }): Promise<StreamSealOutcome>;
 export {};

package/dist/src/stream-to-cloud.js

@@ -2,20 +2,22 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { open, stat } from "node:fs/promises";
 import { gzipSync } from "node:zlib";
 import { join, resolve } from "node:path";
-import { fail, isVaultlineError } from "./errors.js";
+import { fail, isSealkeepError } from "./errors.js";
 import { recordAudit } from "./audit.js";
 import { canonicalPhrase } from "./mnemonic.js";
-import { ADAPTER_VERSION, configuredRecipients, readConfig, writeRecord } from "./vault.js";
+import { isV2 } from "./types.js";
+import { ADAPTER_VERSION, configuredRecipients, mutateArchiveRecord, readConfig, teamSpaceOf } from "./vault.js";
+import { appendArchiveCopy } from "./archive-copies.js";
 import { uploadClientFromStore } from "./providers/index.js";
 import { compositeChecksum } from "./providers/s3.js";
 import { acquireSpoolLock, createSpool, findSpoolForSource, shredSpool, unwrapSpoolKey, updateSpool } from "./spool.js";
-import { DEFAULT_CHUNK_BYTES, ENVELOPE_VERSION, KEY_BYTES, StreamingSha256, TAG_BYTES, chunkAad, chunkNonce, hashFileRange, sealChunksToSink, wrapAll, zeroize } from "../packages/vaultline-crypto/src/index.js";
+import { DEFAULT_CHUNK_BYTES, ENVELOPE_VERSION, KEY_BYTES, StreamingSha256, TAG_BYTES, chunkAad, chunkNonce, hashFileRange, sealChunksToSink, wrapAll, zeroize } from "../packages/sealkeep-crypto/src/index.js";
 // The package's index deliberately exports formats and flows, not raw AEAD
 // primitives. Resuming needs exactly one primitive operation the flows do not
 // expose: re-producing a single chunk's ciphertext to prove the source still
 // seals to the bytes the provider already holds. Reaching into the package for
 // that beats re-implementing the cipher setup here and drifting from it.
-import { aeadCipher, aeadDecipher } from "../packages/vaultline-crypto/src/aead.js";
+import { aeadCipher, aeadDecipher } from "../packages/sealkeep-crypto/src/aead.js";
 const STREAMABLE = new Set(["s3", "r2", "b2", "gcs"]);
 const SEAL_SUITE = "chacha20-poly1305";
 const sha256hex = (input) => createHash("sha256").update(input).digest("hex");
@@ -123,7 +125,7 @@ function interpretProviderState(state) {
  * Anything else (network drop, full disk, a provider 5xx) keeps the journal.
  */
 function resumeRefused(error) {
-    if (!isVaultlineError(error))
+    if (!isSealkeepError(error))
         return false;
     return /cannot resume/i.test(error.message) || /resumable session/.test(error.message) || /NoSuchUpload/.test(error.message);
 }
@@ -182,7 +184,7 @@ export async function sealArchiveToCloud(dataDir, sourcePath, rawPhrase, agent,
         fail("invalid_argument", `The ${remoteStorage.provider} client cannot stream uploads`);
     }
     const client = rawClient;
-    const shared = { dataDir, client, config, remoteStorage, absolute, totalBytes: source.size, phrase, agent, now: options.now };
+    const shared = { dataDir, client, config, remoteStorage, absolute, totalBytes: source.size, phrase, agent, project: options.project ?? null, projectKey: options.projectKey ?? null, targetId: options.targetId, now: options.now };
     // Journal triage. Each pass either resumes the newest journal for this
     // source or abandons it with the reason and looks again, so a stack of
     // crashed attempts drains to the one worth continuing — or to none.
@@ -395,20 +397,38 @@ async function verifyAndRecord(ctx, flight) {
     const now = new Date(ctx.now ?? Date.now()).toISOString();
     // `remote.checksum` stays OUR whole-object stored SHA-256 (base64), resumed
     // or not — the resumable hasher covered every stored byte across processes.
-    const remote = { provider: ctx.remoteStorage.provider, bucket: ctx.remoteStorage.bucket, objectKey, bytes: flight.wholeStoredBytes, checksum: flight.hashers.stored.digestBase64(), verifiedAt: now };
-    const record = {
+    const remote = {
+        provider: ctx.remoteStorage.provider,
+        bucket: ctx.remoteStorage.bucket,
+        objectKey,
+        bytes: flight.wholeStoredBytes,
+        checksum: flight.hashers.stored.digestBase64(),
+        verifiedAt: now,
+        ...(ctx.targetId ? { targetId: ctx.targetId } : {})
+    };
+    const completed = {
         version: 2, id: archiveId, createdAt: flight.envelope.manifest.createdAt,
-        source: { path: ctx.absolute, agent: ctx.agent, bytes: ctx.totalBytes, sha256: flight.hashers.plaintext.digestHex() },
+        source: {
+            path: ctx.absolute, agent: ctx.agent, bytes: ctx.totalBytes, sha256: flight.hashers.plaintext.digestHex(),
+            ...(ctx.project ? { project: ctx.project } : {}),
+            ...(ctx.projectKey ? { projectKey: ctx.projectKey } : {}),
+            ...(teamSpaceOf(ctx.config, ctx.project, ctx.projectKey)?.spaceKey ? { projectScope: teamSpaceOf(ctx.config, ctx.project, ctx.projectKey).spaceKey } : {}),
+        },
         cipher: { algorithm: flight.envelope.suite, ciphertextSha256: flight.hashers.stored.digestHex(), storedBytes: flight.wholeStoredBytes, chunks: flight.envelope.chunks.length },
         envelope: flight.envelope,
         // Born offloaded: this path names where the blob would live, and the
         // offloaded marker says truthfully that no file is there — the same state
         // an uploaded-then-offloaded archive reaches, arrived at without the detour.
-        objectPath: join(ctx.config.storage.root, `${archiveId}.vlarchive`),
+        objectPath: join(ctx.config.storage.root, `${archiveId}.skarchive`),
         remote,
         offloaded: { at: now, provider: ctx.remoteStorage.provider, bucket: ctx.remoteStorage.bucket, objectKey }
     };
-    await writeRecord(ctx.config.storage.root, record);
+    const record = await mutateArchiveRecord(ctx.config.storage.root, archiveId, (current) => {
+        if (!isV2(current))
+            fail("invalid_argument", `Archive ${archiveId} uses format v1 and cannot receive a streamed copy`, { archiveId });
+        const { remote: _remote, copies: _copies, ...completedFacts } = completed;
+        return appendArchiveCopy({ ...current, ...completedFacts }, remote, { makePrimary: true });
+    }, { initial: completed });
     await recordAudit(ctx.dataDir, "archive.create", "allowed", { archiveId, agent: ctx.agent, bytes: ctx.totalBytes, recipients: flight.envelope.wrappedKeys.length, streamed: true, ...(flight.resumed ? { resumed: true } : {}) });
     await recordAudit(ctx.dataDir, "upload.verify", "allowed", { archiveId, objectKey, bytes: flight.wholeStoredBytes, provider: ctx.remoteStorage.provider, streamed: true, ...(flight.resumed ? { resumed: true } : {}) });
     await shredSpool(ctx.dataDir, archiveId);
@@ -419,10 +439,10 @@ async function verifyAndRecord(ctx, flight) {
 async function freshSeal(ctx) {
     const archiveId = randomUUID();
     const prefix = ctx.remoteStorage.prefix.replace(/^\/+|\/+$/g, "");
-    const objectKey = `${prefix}/${archiveId}.vlarchive`;
+    const objectKey = `${prefix}/${archiveId}.skarchive`;
     const chunkBytes = DEFAULT_CHUNK_BYTES;
     const totalChunks = Math.max(1, Math.ceil(ctx.totalBytes / chunkBytes));
-    const recipients = configuredRecipients(ctx.config, ctx.phrase);
+    const recipients = configuredRecipients(ctx.config, ctx.phrase, { project: ctx.project ?? undefined, projectKey: ctx.projectKey ?? undefined });
     // The key is minted here, not inside the seal, because the journal must
     // carry it (wrapped for the same recipients an envelope would name) BEFORE
     // the first byte goes out — a journal written any later could describe
@@ -520,7 +540,7 @@ async function resumeSeal(ctx, journal) {
     const archiveKey = unwrapSpoolKey(journal, { phrase: ctx.phrase });
     try {
         const suite = journal.suite;
-        const recipients = configuredRecipients(ctx.config, ctx.phrase);
+        const recipients = configuredRecipients(ctx.config, ctx.phrase, { project: ctx.project ?? undefined, projectKey: ctx.projectKey ?? undefined });
         /**
          * Re-seals chunks [0, count) from the CURRENT source, verifying each
          * against the journaled header — and, when the S3 part map is known,

package/dist/src/sync-rules.d.ts

@@ -31,7 +31,7 @@ export declare const DEFAULT_SYNC_RULES: SyncRules;
  * response, one file, everything it said.
  */
 export type AccountSnapshot = {
-    plan: "free" | "pro_lite" | "pro" | null;
+    plan: "free" | "pro_lite" | "pro" | "team" | null;
     email: string | null;
     quota: {
         usedBytes: number;
@@ -40,12 +40,39 @@ export type AccountSnapshot = {
     /** When the control plane last actually answered — this file's write time, in the data. */
     fetchedAt: string | null;
 };
-export declare function cacheSyncRules(dataDir: string, raw: unknown): Promise<SyncRules>;
+export declare function cacheSyncRules(dataDir: string, raw: unknown, options?: {
+    authGeneration?: string | null;
+}): Promise<SyncRules>;
 export declare function cachedSyncRules(dataDir: string): Promise<SyncRules | null>;
 /** The last account answer this machine ever received; null on a vault that never had one. */
 export declare function cachedAccount(dataDir: string): Promise<AccountSnapshot | null>;
 /** How long the last account answer is served as-is before asking again. */
 export declare const ACCOUNT_TTL_MS: number;
+/** How long dashboard polling backs off after a best-effort Cloud refresh fails. */
+export declare const ACCOUNT_REFRESH_RETRY_MS = 30000;
+/** A display refresh may be stale, but it may never remain in flight forever. */
+export declare const DASHBOARD_ACCOUNT_REQUEST_TIMEOUT_MS = 10000;
+export type AccountResolution = {
+    account: AccountSnapshot;
+    source: "account" | "cache" | "none";
+};
+type DashboardAccountDependencies = {
+    cloudAuthGeneration?: (dataDir: string) => Promise<string | null>;
+    accountStatus?: (dataDir: string, signal?: AbortSignal) => Promise<unknown>;
+    now?: () => number;
+    /** Deterministic test seam; production uses the fixed display deadline. */
+    requestTimeoutMs?: number;
+};
+/**
+ * Dashboard-only stale-while-refresh account resolution.
+ *
+ * A page render never waits for the control plane: a matching cached account
+ * is returned immediately (labelled `cache` when stale), while one detached
+ * refresh updates the next read. A never-linked vault returns `none`
+ * immediately. The blocking `resolveAccount` below intentionally keeps its old
+ * semantics for entitlement and action paths that require a live decision.
+ */
+export declare function resolveDashboardAccount(dataDir: string, dependencies?: DashboardAccountDependencies): Promise<AccountResolution>;
 /**
  * The account, remembered if recent, live if stale, remembered again if the
  * control plane is unreachable.
@@ -57,10 +84,7 @@ export declare const ACCOUNT_TTL_MS: number;
  * put a ~4-second network round trip inside GET /v1/status, which every page's
  * identity card and plan bar sat waiting on.
  */
-export declare function resolveAccount(dataDir: string): Promise<{
-    account: AccountSnapshot;
-    source: "account" | "cache" | "none";
-}>;
+export declare function resolveAccount(dataDir: string): Promise<AccountResolution>;
 /**
  * Reads the rules from the account, caching them; falls back to the last cached
  * copy when the control plane cannot be reached, and only to "everything" when
@@ -83,3 +107,4 @@ export declare function applySyncRules(found: readonly TranscriptCandidate[], ru
     heldBack: TranscriptCandidate[];
 };
 export declare function describeSyncRules(rules: SyncRules): string;
+export {};

package/dist/src/sync-rules.js

@@ -1,5 +1,5 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve as resolvePath } from "node:path";
 export const DEFAULT_SYNC_RULES = { mode: "all", keepLast: 20, minAgeDays: 7 };
 const CACHE = "sync-rules.json";
 function coerce(raw) {
@@ -14,7 +14,7 @@ function coerce(raw) {
 }
 /** Reads both shapes: the control plane's snake_case reply, and this file's own saved snapshot. */
 function coerceAccount(raw) {
-    const plan = raw?.plan === "pro" || raw?.plan === "pro_lite" || raw?.plan === "free" ? raw.plan : null;
+    const plan = raw?.plan === "team" || raw?.plan === "pro" || raw?.plan === "pro_lite" || raw?.plan === "free" ? raw.plan : null;
     const used = Number(raw?.quota?.usedBytes ?? raw?.used_bytes);
     const limit = Number(raw?.quota?.quotaBytes ?? raw?.quota_bytes);
     return {
@@ -24,10 +24,18 @@ function coerceAccount(raw) {
         fetchedAt: typeof raw?.fetchedAt === "string" ? raw.fetchedAt : null
     };
 }
-export async function cacheSyncRules(dataDir, raw) {
+export async function cacheSyncRules(dataDir, raw, options = {}) {
     const rules = coerce(raw);
     const account = coerceAccount(raw);
-    await writeFile(join(dataDir, CACHE), JSON.stringify({ ...rules, ...account, fetchedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+    // Account data must be tied to the Cloud login that produced it. Without
+    // this marker a logout followed by another person's login could briefly show
+    // the first person's email, plan and quota while /me was still in flight.
+    // Callers that already sampled the generation pass it explicitly; ordinary
+    // action paths pay only one local-file read here.
+    const authGeneration = Object.hasOwn(options, "authGeneration")
+        ? options.authGeneration ?? null
+        : await import("./cloud.js").then(({ cloudAuthGeneration }) => cloudAuthGeneration(dataDir)).catch(() => null);
+    await writeFile(join(dataDir, CACHE), JSON.stringify({ ...rules, ...account, authGeneration, fetchedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
     return rules;
 }
 export async function cachedSyncRules(dataDir) {
@@ -39,21 +47,140 @@ export async function cachedSyncRules(dataDir) {
         return null;
     }
 }
-/** The last account answer this machine ever received; null on a vault that never had one. */
-export async function cachedAccount(dataDir) {
+async function cachedAccountRecord(dataDir) {
     try {
         const saved = JSON.parse(await readFile(join(dataDir, CACHE), "utf8"));
         const account = coerceAccount(saved);
         // A pre-snapshot cache file (rules only) has no account half; report null
         // rather than an all-null snapshot pretending the account said nothing.
-        return account.plan === null && account.email === null && account.quota === null ? null : account;
+        if (account.plan === null && account.email === null && account.quota === null)
+            return null;
+        const authGeneration = typeof saved?.authGeneration === "string"
+            ? saved.authGeneration
+            : saved?.authGeneration === null
+                ? null
+                : undefined;
+        return { account, authGeneration };
     }
     catch {
         return null;
     }
 }
+/** The last account answer this machine ever received; null on a vault that never had one. */
+export async function cachedAccount(dataDir) {
+    return (await cachedAccountRecord(dataDir))?.account ?? null;
+}
 /** How long the last account answer is served as-is before asking again. */
 export const ACCOUNT_TTL_MS = 5 * 60_000;
+/** How long dashboard polling backs off after a best-effort Cloud refresh fails. */
+export const ACCOUNT_REFRESH_RETRY_MS = 30_000;
+/** A display refresh may be stale, but it may never remain in flight forever. */
+export const DASHBOARD_ACCOUNT_REQUEST_TIMEOUT_MS = 10_000;
+const NO_ACCOUNT = { plan: null, email: null, quota: null, fetchedAt: null };
+/** One live refresh per vault *and Cloud login*, shared by simultaneous UI reads. */
+const dashboardAccountRefreshes = new Map();
+/** A timestamp rather than a timer: this never keeps the daemon alive. */
+const dashboardAccountRetryAt = new Map();
+const accountIsFresh = (account, now) => {
+    if (!account.fetchedAt)
+        return false;
+    const fetchedAt = Date.parse(account.fetchedAt);
+    return Number.isFinite(fetchedAt) && now - fetchedAt < ACCOUNT_TTL_MS;
+};
+const cacheBelongsToGeneration = (record, generation) => (
+// A legacy cache can only be used on a legacy machine which has never
+// emitted an auth generation. Every login/logout/renewal now emits one.
+record.authGeneration === undefined ? generation === null : record.authGeneration === generation);
+async function dashboardCloudGeneration(dataDir, dependencies) {
+    if (dependencies.cloudAuthGeneration)
+        return dependencies.cloudAuthGeneration(dataDir);
+    const { cloudAuthGeneration } = await import("./cloud.js");
+    return cloudAuthGeneration(dataDir);
+}
+async function dashboardAccountStatus(dataDir, dependencies) {
+    const controller = new AbortController();
+    const timeoutMs = dependencies.requestTimeoutMs ?? DASHBOARD_ACCOUNT_REQUEST_TIMEOUT_MS;
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error("Sealkeep Cloud account display refresh timed out"));
+        }, timeoutMs);
+        timer.unref?.();
+    });
+    const work = dependencies.accountStatus
+        ? dependencies.accountStatus(dataDir, controller.signal)
+        : import("./cloud.js").then(({ accountStatus }) => accountStatus(dataDir, undefined, {
+            signal: controller.signal,
+            // A passive poll must not start the process-wide token renewal which a
+            // later write may need to await. An expired snapshot simply leaves the
+            // last authenticated account cache visible.
+            renewToken: false,
+        }));
+    try {
+        return await Promise.race([work, timedOut]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function refreshDashboardAccount(dataDir, authGeneration, dependencies) {
+    const key = `${resolvePath(dataDir)}\0${authGeneration ?? "<no-auth-generation>"}`;
+    if (dashboardAccountRefreshes.has(key))
+        return;
+    const now = dependencies.now?.() ?? Date.now();
+    if ((dashboardAccountRetryAt.get(key) ?? 0) > now)
+        return;
+    const refresh = (async () => {
+        try {
+            const raw = await dashboardAccountStatus(dataDir, dependencies);
+            // A /me request can outlive logout, another login, or token renewal.
+            // Never let that old answer overwrite the identity now using the vault.
+            if (await dashboardCloudGeneration(dataDir, dependencies) !== authGeneration)
+                return;
+            await cacheSyncRules(dataDir, raw, { authGeneration });
+            dashboardAccountRetryAt.delete(key);
+        }
+        catch {
+            // Dashboard refresh is deliberately best-effort. The stale local answer
+            // remains useful, and this detached promise must never become unhandled.
+            // Only back off the login which actually failed; if auth changed while
+            // /me was pending, the new login gets its own immediate refresh.
+            const currentGeneration = await dashboardCloudGeneration(dataDir, dependencies).catch(() => null);
+            if (currentGeneration === authGeneration) {
+                dashboardAccountRetryAt.set(key, (dependencies.now?.() ?? Date.now()) + ACCOUNT_REFRESH_RETRY_MS);
+            }
+        }
+    })();
+    dashboardAccountRefreshes.set(key, refresh);
+    void refresh.then(() => { if (dashboardAccountRefreshes.get(key) === refresh)
+        dashboardAccountRefreshes.delete(key); }, () => { if (dashboardAccountRefreshes.get(key) === refresh)
+        dashboardAccountRefreshes.delete(key); });
+}
+/**
+ * Dashboard-only stale-while-refresh account resolution.
+ *
+ * A page render never waits for the control plane: a matching cached account
+ * is returned immediately (labelled `cache` when stale), while one detached
+ * refresh updates the next read. A never-linked vault returns `none`
+ * immediately. The blocking `resolveAccount` below intentionally keeps its old
+ * semantics for entitlement and action paths that require a live decision.
+ */
+export async function resolveDashboardAccount(dataDir, dependencies = {}) {
+    const [authGeneration, cached] = await Promise.all([
+        dashboardCloudGeneration(dataDir, dependencies).catch(() => null),
+        cachedAccountRecord(dataDir),
+    ]);
+    const matching = cached && cacheBelongsToGeneration(cached, authGeneration) ? cached.account : null;
+    if (matching && accountIsFresh(matching, dependencies.now?.() ?? Date.now())) {
+        return { account: matching, source: "account" };
+    }
+    refreshDashboardAccount(dataDir, authGeneration, dependencies);
+    return matching
+        ? { account: matching, source: "cache" }
+        : { account: NO_ACCOUNT, source: "none" };
+}
 /**
  * The account, remembered if recent, live if stale, remembered again if the
  * control plane is unreachable.
@@ -66,21 +193,33 @@ export const ACCOUNT_TTL_MS = 5 * 60_000;
  * identity card and plan bar sat waiting on.
  */
 export async function resolveAccount(dataDir) {
-    const recent = await cachedAccount(dataDir);
-    if (recent?.fetchedAt && Date.now() - Date.parse(recent.fetchedAt) < ACCOUNT_TTL_MS) {
+    const authGeneration = await dashboardCloudGeneration(dataDir, {}).catch(() => null);
+    const cachedRecord = await cachedAccountRecord(dataDir);
+    const recent = cachedRecord && cacheBelongsToGeneration(cachedRecord, authGeneration)
+        ? cachedRecord.account
+        : null;
+    if (recent && accountIsFresh(recent, Date.now())) {
         return { account: recent, source: "account" };
     }
     try {
         const { accountStatus } = await import("./cloud.js");
         const raw = await accountStatus(dataDir);
-        await cacheSyncRules(dataDir, raw);
+        // The request authenticated before it left. If login/logout/renewal raced
+        // it, its answer belongs to the old session and must neither authorize an
+        // action nor overwrite the new session's cache.
+        if (await dashboardCloudGeneration(dataDir, {}).catch(() => null) !== authGeneration) {
+            return { account: NO_ACCOUNT, source: "none" };
+        }
+        await cacheSyncRules(dataDir, raw, { authGeneration });
         return { account: { ...coerceAccount(raw), fetchedAt: new Date().toISOString() }, source: "account" };
     }
     catch {
-        const cached = await cachedAccount(dataDir);
-        return cached
-            ? { account: cached, source: "cache" }
-            : { account: { plan: null, email: null, quota: null, fetchedAt: null }, source: "none" };
+        const currentGeneration = await dashboardCloudGeneration(dataDir, {}).catch(() => null);
+        const fallback = await cachedAccountRecord(dataDir);
+        const matching = fallback && cacheBelongsToGeneration(fallback, currentGeneration) ? fallback.account : null;
+        return matching
+            ? { account: matching, source: "cache" }
+            : { account: NO_ACCOUNT, source: "none" };
     }
 }
 /**

package/dist/src/team-backfill-scheduling.d.ts

@@ -0,0 +1,8 @@
+import type { TeamHistoryBackfillJob } from "./team-backfill.js";
+/**
+ * Prefer recent work, promoting every base it still needs. Every fourth claim
+ * instead takes the longest-waiting eligible job, so new work and repeated
+ * failures cannot monopolize that lane. This only orders candidates; dependency/auth/claim gates stay with
+ * the durable ledger owner.
+ */
+export declare function orderTeamBackfillJobs(jobs: TeamHistoryBackfillJob[], eligible: TeamHistoryBackfillJob[], sequence: number): TeamHistoryBackfillJob[];

package/dist/src/team-backfill-scheduling.js

@@ -0,0 +1,33 @@
+/**
+ * Prefer recent work, promoting every base it still needs. Every fourth claim
+ * instead takes the longest-waiting eligible job, so new work and repeated
+ * failures cannot monopolize that lane. This only orders candidates; dependency/auth/claim gates stay with
+ * the durable ledger owner.
+ */
+export function orderTeamBackfillJobs(jobs, eligible, sequence) {
+    const stamp = (job) => {
+        const value = Date.parse(job.sourceCreatedAt ?? job.createdAt);
+        return Number.isFinite(value) ? value : 0;
+    };
+    const oldest = (a, b) => (a.lastScheduledAt ?? a.createdAt).localeCompare(b.lastScheduledAt ?? b.createdAt)
+        || a.createdAt.localeCompare(b.createdAt) || stamp(a) - stamp(b) || a.id.localeCompare(b.id);
+    if (sequence % 4 === 3)
+        return [...eligible].sort(oldest);
+    const byId = new Map(jobs.map((job) => [job.id, job]));
+    const priority = new Map();
+    for (const source of [...jobs].sort((a, b) => stamp(b) - stamp(a))) {
+        const value = stamp(source);
+        const pending = [source.id];
+        while (pending.length) {
+            const id = pending.pop();
+            if (priority.has(id) && priority.get(id) >= value)
+                continue;
+            const job = byId.get(id);
+            if (!job)
+                continue;
+            priority.set(id, value);
+            pending.push(...job.dependencyJobIds);
+        }
+    }
+    return [...eligible].sort((a, b) => (priority.get(b.id) ?? 0) - (priority.get(a.id) ?? 0) || oldest(a, b));
+}

package/dist/src/team-backfill.d.ts

@@ -0,0 +1,116 @@
+import { type Envelope } from "../packages/sealkeep-crypto/src/index.js";
+import type { TeamRosterWire } from "./cloud.js";
+import { type ArchiveRecordV2, type RemoteObject } from "./types.js";
+export type TeamHistoryBackfillStage = "pending" | "prepared" | "uploaded" | "registered" | "indexed" | "blocked" | "superseded";
+export type TeamHistoryBackfillJob = {
+    version: 1;
+    id: string;
+    shareRef: string;
+    sourceArchiveId: string;
+    /** Source archive creation time, not the time a backlog was discovered. */
+    sourceCreatedAt?: string;
+    /** Scheduling fairness, separate from renewal/progress timestamps. */
+    lastScheduledAt?: string;
+    spaceKey: string;
+    project: string;
+    projectKey?: string;
+    rosterHash: string;
+    membership_version?: number;
+    memberPublicKeys: string[];
+    dependencyJobIds: string[];
+    dependencyRefs: string[];
+    stage: TeamHistoryBackfillStage;
+    createdAt: string;
+    updatedAt: string;
+    attempts: number;
+    nextAttemptAt?: string;
+    lastError?: string;
+    blockedReason?: string;
+    envelope?: Envelope;
+    remote?: RemoteObject;
+    claim?: {
+        token: string;
+        pid: number;
+        processId?: string;
+        processStart?: string;
+        at: number;
+    };
+    cleanupNeeded?: boolean;
+    cleanupError?: string;
+};
+export type TeamHistoryBackfillSpaceStatus = {
+    state: "idle" | "working" | "attention";
+    total: number;
+    indexed: number;
+    registered: number;
+    pending: number;
+    failed: number;
+    blocked: number;
+    activeArchiveId?: string;
+    lastError?: string;
+};
+export type TeamHistoryBackfillStatus = {
+    state: "idle" | "working" | "attention";
+    total: number;
+    indexed: number;
+    registered: number;
+    pending: number;
+    failed: number;
+    blocked: number;
+    lastError?: string;
+    spaces: Record<string, TeamHistoryBackfillSpaceStatus>;
+};
+export type TeamHistoryBackfillOutcome = TeamHistoryBackfillStatus & {
+    scheduled: number;
+    processed: number;
+    uploadedNow: number;
+    registeredNow: number;
+};
+export type TeamHistoryBackfillPublication = {
+    jobId: string;
+    sourceArchiveId: string;
+    record: ArchiveRecordV2;
+};
+export type TeamHistoryBackfillInventoryDependencies = {
+    readArchiveNames?: (storageRoot: string) => Promise<string[]>;
+    statArchive?: (path: string) => Promise<{
+        size: number;
+        mtimeMs: number;
+    } | null>;
+    yieldAfterStat?: () => Promise<void>;
+};
+/**
+ * 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 declare function scheduleTeamHistoryBackfill(dataDir: string, now?: number, inventory?: TeamHistoryBackfillInventoryDependencies, options?: {
+    signal?: AbortSignal;
+    idleMs?: number;
+}): Promise<number>;
+/** Drain a bounded number of durable jobs. Every stage is committed separately. */
+export declare function drainTeamHistoryBackfill(dataDir: string, rawPhrase: string, options?: {
+    limit?: number;
+    now?: () => number;
+    signal?: AbortSignal;
+    idleMs?: number;
+    maxBatchMs?: number;
+}): Promise<{
+    processed: number;
+    uploaded: number;
+    registered: number;
+}>;
+export declare function teamHistoryBackfillStatus(dataDir: string): Promise<TeamHistoryBackfillStatus>;
+export declare function reconcileTeamHistoryBackfill(dataDir: string, phrase: string, options?: {
+    limit?: number;
+    now?: () => number;
+    inventory?: TeamHistoryBackfillInventoryDependencies;
+    signal?: AbortSignal;
+    idleMs?: number;
+    maxBatchMs?: number;
+}): Promise<TeamHistoryBackfillOutcome>;
+/** Current, verified, membership-wrapped jobs suitable for a team shard. */
+export declare function teamHistoryBackfillPublications(dataDir: string, spaceKey: string, currentRosterSnapshot: TeamRosterWire): Promise<TeamHistoryBackfillPublication[]>;
+/** All refs ever produced for this space, used only to remove stale roster aliases. */
+export declare function allTeamHistoryBackfillRefs(dataDir: string, spaceKey: string): Promise<Set<string>>;
+export declare function markTeamHistoryBackfillsIndexed(dataDir: string, jobIds: readonly string[]): Promise<void>;