sealkeep 0.5.0

package/dist/src/providers/sigv4.js

@@ -0,0 +1,112 @@
+import { createHash, createHmac } from "node:crypto";
+/**
+ * AWS Signature Version 4 for S3-compatible endpoints (S3, R2, MinIO).
+ *
+ * Implemented from the published specification and checked against AWS's own
+ * documented example in `test/sigv4.test.ts`, including the intermediate canonical
+ * request and string-to-sign, so a regression is caught at the step that broke.
+ */
+export const ALGORITHM = "AWS4-HMAC-SHA256";
+export const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+const hex = (value) => (typeof value === "string" ? Buffer.from(value) : value).toString("hex");
+const sha256hex = (value) => createHash("sha256").update(value).digest("hex");
+const hmac = (key, value) => createHmac("sha256", key).update(value, "utf8").digest();
+/** RFC 3986 unreserved characters stay literal; everything else is percent-encoded. */
+export function uriEncode(value, encodeSlash = true) {
+    let output = "";
+    for (const byte of Buffer.from(value, "utf8")) {
+        const char = String.fromCharCode(byte);
+        if (/[A-Za-z0-9\-_.~]/.test(char))
+            output += char;
+        else if (char === "/" && !encodeSlash)
+            output += char;
+        else
+            output += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+    return output;
+}
+export function canonicalUri(path) {
+    if (!path || path === "/")
+        return "/";
+    return uriEncode(path.startsWith("/") ? path : `/${path}`, false);
+}
+export function canonicalQuery(query) {
+    return [...query]
+        .map(([key, value]) => [uriEncode(key), uriEncode(value)])
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0))
+        .map(([key, value]) => `${key}=${value}`)
+        .join("&");
+}
+export function canonicalHeaders(headers) {
+    const entries = Object.entries(headers)
+        .map(([name, value]) => [name.toLowerCase().trim(), value.trim().replace(/\s+/g, " ")])
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    return { canonical: entries.map(([name, value]) => `${name}:${value}\n`).join(""), signed: entries.map(([name]) => name).join(";") };
+}
+export function canonicalRequest(input) {
+    const { canonical, signed } = canonicalHeaders(input.headers);
+    return {
+        request: [input.method.toUpperCase(), canonicalUri(input.path), canonicalQuery(input.query), canonical, signed, input.payloadHash].join("\n"),
+        signedHeaders: signed
+    };
+}
+export function credentialScope(date, region, service) {
+    return `${date}/${region}/${service}/aws4_request`;
+}
+export function stringToSign(amzDate, scope, request) {
+    return [ALGORITHM, amzDate, scope, sha256hex(request)].join("\n");
+}
+export function signingKey(secretAccessKey, date, region, service) {
+    return hmac(hmac(hmac(hmac(`AWS4${secretAccessKey}`, date), region), service), "aws4_request");
+}
+export function sign(secretAccessKey, date, region, service, toSign) {
+    return hex(hmac(signingKey(secretAccessKey, date, region, service), toSign));
+}
+/** `20130524T000000Z` and its `20130524` date portion. */
+export function amzDates(when) {
+    const amzDate = `${when.toISOString().replace(/[:-]|\.\d{3}/g, "")}`;
+    return { amzDate, date: amzDate.slice(0, 8) };
+}
+/**
+ * Produces a presigned URL. Host is always signed; any extra header supplied here
+ * is signed too and must be sent verbatim by the uploader or the request is rejected.
+ */
+export function presign(input) {
+    const service = input.service ?? "s3";
+    const when = input.when ?? new Date();
+    const { amzDate, date } = amzDates(when);
+    const expires = input.expiresInSeconds ?? 900;
+    const scope = credentialScope(date, input.region, service);
+    const headers = { host: input.port ? `${input.host}:${input.port}` : input.host, ...input.headers };
+    const query = new Map(Object.entries(input.query ?? {}));
+    query.set("X-Amz-Algorithm", ALGORITHM);
+    query.set("X-Amz-Credential", `${input.credentials.accessKeyId}/${scope}`);
+    query.set("X-Amz-Date", amzDate);
+    query.set("X-Amz-Expires", String(expires));
+    const { canonical: _c, signed } = canonicalHeaders(headers);
+    query.set("X-Amz-SignedHeaders", signed);
+    if (input.credentials.sessionToken)
+        query.set("X-Amz-Security-Token", input.credentials.sessionToken);
+    const { request } = canonicalRequest({ method: input.method, path: input.path, query, headers, payloadHash: input.payloadHash ?? UNSIGNED_PAYLOAD });
+    const toSign = stringToSign(amzDate, scope, request);
+    const signature = sign(input.credentials.secretAccessKey, date, input.region, service, toSign);
+    const protocol = input.protocol ?? "https";
+    const authority = input.port ? `${input.host}:${input.port}` : input.host;
+    const url = `${protocol}://${authority}${canonicalUri(input.path)}?${canonicalQuery(query)}&X-Amz-Signature=${signature}`;
+    return { url, signature, canonicalRequest: request, stringToSign: toSign, signedHeaders: signed, expiresAt: new Date(when.getTime() + expires * 1000).toISOString() };
+}
+/** Recomputes a presigned signature so a server can verify it. Used by the test emulator. */
+export function verifyPresigned(input) {
+    const query = new Map();
+    for (const [key, value] of input.url.searchParams)
+        if (key !== "X-Amz-Signature")
+            query.set(key, value);
+    const presented = input.url.searchParams.get("X-Amz-Signature");
+    const amzDate = query.get("X-Amz-Date");
+    if (!presented || !amzDate)
+        return false;
+    const headers = { host: input.url.host, ...input.extraHeaders };
+    const { request } = canonicalRequest({ method: input.method, path: decodeURIComponent(input.url.pathname), query, headers, payloadHash: UNSIGNED_PAYLOAD });
+    const expected = sign(input.credentials.secretAccessKey, amzDate.slice(0, 8), input.region, input.service ?? "s3", stringToSign(amzDate, credentialScope(amzDate.slice(0, 8), input.region, input.service ?? "s3"), request));
+    return expected === presented;
+}

package/dist/src/queue.d.ts

@@ -0,0 +1,185 @@
+export type JobStatus = "ready" | "leased" | "done" | "failed";
+export type ArchiveJob = {
+    version: 1;
+    /** Content-addressed: agent + resolved source path + byte length + mtime. */
+    id: string;
+    status: JobStatus;
+    agent: string;
+    sourcePath: string;
+    /** The lifecycle event that first created this job. Duplicates never rewrite it. */
+    event: string;
+    sessionId?: string;
+    sourceBytes: number;
+    sourceModifiedAt: string;
+    enqueuedAt: string;
+    updatedAt: string;
+    attempts: number;
+    nextAttemptAt: string;
+    lastError?: {
+        code: string;
+        message: string;
+    };
+    /** Live seal progress while leased: bytes of the source read so far, of its total. Written throttled by the worker; the queue view turns it into a percentage. */
+    progress?: {
+        bytes: number;
+        of: number;
+    };
+    lease?: {
+        id: string;
+        owner: string;
+        acquiredAt: string;
+        expiresAt: string;
+    };
+    result?: {
+        archiveId: string;
+        ciphertextSha256: string;
+        bytes: number;
+        deduplicated?: boolean;
+        completedAt: string;
+    };
+    /** Set instead of `result` when a later snapshot of the same transcript took this job's place. */
+    supersededBy?: string;
+};
+export type EnqueueRequest = {
+    sourcePath: string;
+    agent: string;
+    event: string;
+    sessionId?: string;
+};
+export type QueueOptions = {
+    now?: () => number;
+    leaseMs?: number;
+    maxAttempts?: number;
+    backoffMs?: number;
+    maxBackoffMs?: number;
+};
+export declare function queueDir(dataDir: string): string;
+/**
+ * Two lifecycle events describing the same unchanged transcript produce the same
+ * key, so a `PostCompact` followed by a `SessionEnd` archives once.
+ */
+export declare function jobId(input: {
+    agent: string;
+    sourcePath: string;
+    bytes: number;
+    modifiedAtMs: number;
+}): string;
+/**
+ * A restart-safe, file-backed work queue. Each job is one atomically written
+ * file named by its content-addressed id, so concurrent hook processes cannot
+ * create duplicates and an interrupted worker leaves recoverable state.
+ */
+export declare class ArchiveQueue {
+    private readonly root;
+    private readonly now;
+    private readonly leaseMs;
+    private readonly maxAttempts;
+    private readonly backoffMs;
+    private readonly maxBackoffMs;
+    constructor(dataDir: string, options?: QueueOptions);
+    private path;
+    private stamp;
+    private writeAtomic;
+    /** Creates the file only if the id is unseen; the content is complete before it becomes visible. */
+    private createExclusive;
+    get(id: string): Promise<ArchiveJob | null>;
+    private require;
+    list(filter?: {
+        status?: JobStatus;
+    }): Promise<ArchiveJob[]>;
+    stats(): Promise<{
+        total: number;
+        ready: number;
+        leased: number;
+        done: number;
+        failed: number;
+    }>;
+    /**
+     * Whether `candidate` describes a later state of the transcript than `over`.
+     *
+     * A total order over snapshots of one file, so two hook processes enqueueing
+     * at once reach the same verdict and the most advanced snapshot is never the
+     * one superseded. Bytes lead because a transcript that has grown has strictly
+     * more in it; mtime settles a same-length rewrite. Equal on all three means
+     * the same content address, which is the same job.
+     */
+    private advances;
+    /**
+     * Retires queued snapshots of the same transcript that this one has overtaken.
+     *
+     * A ready job holds a path, not bytes: whenever a worker gets to it, it
+     * archives whatever that path holds *then*. So two ready jobs for one
+     * transcript read, compress and seal the same file twice — the second run
+     * dedupes, but only after paying for the whole thing again. On a session that
+     * is appended to every few seconds that is the difference between archiving a
+     * 4 GB rollout once and archiving it on every write gap, which is how
+     * ~/.codex/sessions reached 78 GB across 13 active days.
+     *
+     * Nothing is lost by dropping the earlier job: the bytes it would have
+     * archived are the bytes still on disk, and the surviving job archives those.
+     * Only `ready` jobs are retired — a leased job may already be mid-archive, and
+     * a done or failed job is the record of something that actually happened.
+     */
+    private supersede;
+    /** Records intent to archive a transcript. It never reads transcript contents. */
+    enqueue(request: EnqueueRequest): Promise<{
+        job: ArchiveJob;
+        deduped: boolean;
+        superseded: string[];
+    }>;
+    private claimable;
+    /** Claims from this instance run one at a time; see `claim`. */
+    private claimTurn;
+    /**
+     * Hands out one job under a time-boxed lease. An expired lease is reclaimed
+     * automatically. `excluding` lets a drain reach past jobs it has already
+     * refused this pass — without it, one transcript too large for the free disk
+     * sat at the head of the queue and starved every smaller job behind it.
+     *
+     * Claims through one queue instance are serialised. A parallel drain runs
+     * several workers against the same instance, and two claims listing the
+     * directory at the same moment would pick the same candidate and both write
+     * a lease on it — the loser then failing its own job with a lease error.
+     * Serialising costs nothing next to the seal that follows, and cross-process
+     * claims keep the protection they always had: whoever renames second wins,
+     * and archiving is idempotent by source bytes.
+     */
+    claim(owner: string, excluding?: ReadonlySet<string>): Promise<ArchiveJob | null>;
+    private claimNext;
+    private assertLease;
+    complete(id: string, leaseId: string, result: {
+        archiveId: string;
+        ciphertextSha256: string;
+        bytes: number;
+        deduplicated?: boolean;
+    }): Promise<ArchiveJob>;
+    /**
+     * Puts a claimed job back without spending an attempt.
+     *
+     * `fail` is for a job that went wrong; this is for one that was never tried.
+     * The difference matters when the reason is transient and external — no room
+     * on the disk to seal it safely — because routing that through `fail` would
+     * count attempts against a job that has nothing wrong with it and eventually
+     * dead-letter a perfectly good transcript for being unlucky about timing.
+     */
+    /** Progress on the job being worked — visible, not merely true. */
+    progress(id: string, leaseId: string, bytes: number, of: number): Promise<void>;
+    /**
+     * Takes a waiting job back out of the queue. Only `ready` and `failed` jobs
+     * can go: a leased one is being sealed this moment and will finish or fail
+     * on its own, and a done one is not in the queue anymore — it is an archive,
+     * and removing that is a different, bigger decision made elsewhere.
+     */
+    remove(id: string): Promise<ArchiveJob>;
+    release(id: string, leaseId: string, reason?: {
+        code: string;
+        message: string;
+    }): Promise<ArchiveJob>;
+    /** Reschedules with exponential backoff, or dead-letters once attempts are exhausted. */
+    fail(id: string, leaseId: string, error: {
+        code: string;
+        message: string;
+    }): Promise<ArchiveJob>;
+    /** Explicit operator action: a dead-lettered job never revives itself. */
+    retry(id: string): Promise<ArchiveJob>;
+}

package/dist/src/queue.js

@@ -0,0 +1,286 @@
+import { link, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import { fail } from "./errors.js";
+const JOB_VERSION = 1;
+export function queueDir(dataDir) { return join(dataDir, "queue"); }
+/**
+ * Two lifecycle events describing the same unchanged transcript produce the same
+ * key, so a `PostCompact` followed by a `SessionEnd` archives once.
+ */
+export function jobId(input) {
+    return createHash("sha256").update(`vaultline-job:v1\n${input.agent}\n${resolve(input.sourcePath)}\n${input.bytes}\n${Math.trunc(input.modifiedAtMs)}`).digest("hex");
+}
+/**
+ * A restart-safe, file-backed work queue. Each job is one atomically written
+ * file named by its content-addressed id, so concurrent hook processes cannot
+ * create duplicates and an interrupted worker leaves recoverable state.
+ */
+export class ArchiveQueue {
+    root;
+    now;
+    leaseMs;
+    maxAttempts;
+    backoffMs;
+    maxBackoffMs;
+    constructor(dataDir, options = {}) {
+        this.root = queueDir(dataDir);
+        this.now = options.now ?? Date.now;
+        this.leaseMs = options.leaseMs ?? 5 * 60_000;
+        this.maxAttempts = options.maxAttempts ?? 5;
+        this.backoffMs = options.backoffMs ?? 15_000;
+        this.maxBackoffMs = options.maxBackoffMs ?? 30 * 60_000;
+    }
+    path(id) { return join(this.root, `${id}.json`); }
+    stamp() { return new Date(this.now()).toISOString(); }
+    async writeAtomic(job) {
+        const target = this.path(job.id);
+        const temp = `${target}.${randomUUID()}.tmp`;
+        await writeFile(temp, JSON.stringify(job, null, 2) + "\n", { mode: 0o600 });
+        await rename(temp, target);
+    }
+    /** Creates the file only if the id is unseen; the content is complete before it becomes visible. */
+    async createExclusive(job) {
+        const target = this.path(job.id);
+        const temp = `${target}.${randomUUID()}.tmp`;
+        await writeFile(temp, JSON.stringify(job, null, 2) + "\n", { mode: 0o600 });
+        try {
+            await link(temp, target);
+            return true;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+    }
+    async get(id) {
+        try {
+            return JSON.parse(await readFile(this.path(id), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    async require(id) {
+        const job = await this.get(id);
+        return job ?? fail("queue_job_not_found", `No queued job with id ${id}`, { jobId: id });
+    }
+    async list(filter) {
+        let names;
+        try {
+            names = await readdir(this.root);
+        }
+        catch {
+            return [];
+        }
+        const jobs = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            try {
+                jobs.push(JSON.parse(await readFile(join(this.root, name), "utf8")));
+            }
+            catch {
+                continue;
+            }
+        }
+        return jobs.filter((job) => !filter?.status || job.status === filter.status).sort((a, b) => a.enqueuedAt.localeCompare(b.enqueuedAt) || a.id.localeCompare(b.id));
+    }
+    async stats() {
+        const jobs = await this.list();
+        const count = (status) => jobs.filter((job) => job.status === status).length;
+        return { total: jobs.length, ready: count("ready"), leased: count("leased"), done: count("done"), failed: count("failed") };
+    }
+    /**
+     * Whether `candidate` describes a later state of the transcript than `over`.
+     *
+     * A total order over snapshots of one file, so two hook processes enqueueing
+     * at once reach the same verdict and the most advanced snapshot is never the
+     * one superseded. Bytes lead because a transcript that has grown has strictly
+     * more in it; mtime settles a same-length rewrite. Equal on all three means
+     * the same content address, which is the same job.
+     */
+    advances(candidate, over) {
+        if (candidate.sourceBytes !== over.sourceBytes)
+            return candidate.sourceBytes > over.sourceBytes;
+        const [later, earlier] = [Date.parse(candidate.sourceModifiedAt), Date.parse(over.sourceModifiedAt)];
+        if (later !== earlier)
+            return later > earlier;
+        return candidate.id > over.id;
+    }
+    /**
+     * Retires queued snapshots of the same transcript that this one has overtaken.
+     *
+     * A ready job holds a path, not bytes: whenever a worker gets to it, it
+     * archives whatever that path holds *then*. So two ready jobs for one
+     * transcript read, compress and seal the same file twice — the second run
+     * dedupes, but only after paying for the whole thing again. On a session that
+     * is appended to every few seconds that is the difference between archiving a
+     * 4 GB rollout once and archiving it on every write gap, which is how
+     * ~/.codex/sessions reached 78 GB across 13 active days.
+     *
+     * Nothing is lost by dropping the earlier job: the bytes it would have
+     * archived are the bytes still on disk, and the surviving job archives those.
+     * Only `ready` jobs are retired — a leased job may already be mid-archive, and
+     * a done or failed job is the record of something that actually happened.
+     */
+    async supersede(winner) {
+        // A dead-lettered job archives nothing, so it may not retire work either.
+        if (winner.status === "failed")
+            return [];
+        const retired = [];
+        for (const job of await this.list({ status: "ready" })) {
+            if (job.id === winner.id || job.agent !== winner.agent || job.sourcePath !== winner.sourcePath)
+                continue;
+            if (!this.advances(winner, job))
+                continue;
+            await this.writeAtomic({ ...job, status: "done", updatedAt: this.stamp(), lease: undefined, supersededBy: winner.id });
+            retired.push(job.id);
+        }
+        return retired;
+    }
+    /** Records intent to archive a transcript. It never reads transcript contents. */
+    async enqueue(request) {
+        const absolute = resolve(request.sourcePath);
+        let source;
+        try {
+            source = await stat(absolute);
+        }
+        catch {
+            return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
+        }
+        if (!source.isFile())
+            fail("source_unreadable", `Transcript is not a file: ${absolute}`, { sourcePath: absolute });
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        const id = jobId({ agent: request.agent, sourcePath: absolute, bytes: source.size, modifiedAtMs: source.mtimeMs });
+        const timestamp = this.stamp();
+        const job = {
+            version: JOB_VERSION, id, status: "ready", agent: request.agent, sourcePath: absolute, event: request.event, sessionId: request.sessionId,
+            sourceBytes: source.size, sourceModifiedAt: new Date(source.mtimeMs).toISOString(),
+            enqueuedAt: timestamp, updatedAt: timestamp, attempts: 0, nextAttemptAt: timestamp
+        };
+        if (await this.createExclusive(job))
+            return { job, deduped: false, superseded: await this.supersede(job) };
+        const existing = await this.require(id);
+        return { job: existing, deduped: true, superseded: await this.supersede(existing) };
+    }
+    claimable(job, at) {
+        if (job.status === "ready")
+            return Date.parse(job.nextAttemptAt) <= at;
+        if (job.status === "leased")
+            return !job.lease || Date.parse(job.lease.expiresAt) <= at;
+        return false;
+    }
+    /** Claims from this instance run one at a time; see `claim`. */
+    claimTurn = Promise.resolve();
+    /**
+     * Hands out one job under a time-boxed lease. An expired lease is reclaimed
+     * automatically. `excluding` lets a drain reach past jobs it has already
+     * refused this pass — without it, one transcript too large for the free disk
+     * sat at the head of the queue and starved every smaller job behind it.
+     *
+     * Claims through one queue instance are serialised. A parallel drain runs
+     * several workers against the same instance, and two claims listing the
+     * directory at the same moment would pick the same candidate and both write
+     * a lease on it — the loser then failing its own job with a lease error.
+     * Serialising costs nothing next to the seal that follows, and cross-process
+     * claims keep the protection they always had: whoever renames second wins,
+     * and archiving is idempotent by source bytes.
+     */
+    async claim(owner, excluding) {
+        const turn = this.claimTurn.then(() => this.claimNext(owner, excluding));
+        this.claimTurn = turn.then(() => undefined, () => undefined);
+        return turn;
+    }
+    async claimNext(owner, excluding) {
+        const at = this.now();
+        const candidate = (await this.list()).find((job) => this.claimable(job, at) && !excluding?.has(job.id));
+        if (!candidate)
+            return null;
+        const leased = {
+            ...candidate, status: "leased", attempts: candidate.attempts + 1, updatedAt: new Date(at).toISOString(),
+            lease: { id: randomUUID(), owner, acquiredAt: new Date(at).toISOString(), expiresAt: new Date(at + this.leaseMs).toISOString() }
+        };
+        await this.writeAtomic(leased);
+        return leased;
+    }
+    assertLease(job, leaseId) {
+        if (job.status !== "leased" || !job.lease)
+            fail("queue_lease_invalid", `Job ${job.id} is not leased`, { jobId: job.id, status: job.status });
+        if (job.lease.id !== leaseId)
+            fail("queue_lease_invalid", `Lease does not match job ${job.id}`, { jobId: job.id });
+        if (Date.parse(job.lease.expiresAt) <= this.now())
+            fail("queue_lease_expired", `Lease for job ${job.id} expired at ${job.lease.expiresAt}`, { jobId: job.id, expiresAt: job.lease.expiresAt });
+        return job;
+    }
+    async complete(id, leaseId, result) {
+        const job = this.assertLease(await this.require(id), leaseId);
+        const done = { ...job, status: "done", updatedAt: this.stamp(), lease: undefined, lastError: undefined, result: { ...result, completedAt: this.stamp() } };
+        await this.writeAtomic(done);
+        return done;
+    }
+    /**
+     * Puts a claimed job back without spending an attempt.
+     *
+     * `fail` is for a job that went wrong; this is for one that was never tried.
+     * The difference matters when the reason is transient and external — no room
+     * on the disk to seal it safely — because routing that through `fail` would
+     * count attempts against a job that has nothing wrong with it and eventually
+     * dead-letter a perfectly good transcript for being unlucky about timing.
+     */
+    /** Progress on the job being worked — visible, not merely true. */
+    async progress(id, leaseId, bytes, of) {
+        const job = this.assertLease(await this.require(id), leaseId);
+        await this.writeAtomic({ ...job, progress: { bytes, of }, updatedAt: this.stamp() });
+    }
+    /**
+     * Takes a waiting job back out of the queue. Only `ready` and `failed` jobs
+     * can go: a leased one is being sealed this moment and will finish or fail
+     * on its own, and a done one is not in the queue anymore — it is an archive,
+     * and removing that is a different, bigger decision made elsewhere.
+     */
+    async remove(id) {
+        const job = await this.require(id);
+        if (job.status === "leased")
+            fail("invalid_argument", "This one is being sealed right now — it finishes (or fails) on its own in a moment.", { jobId: id });
+        if (job.status === "done")
+            fail("invalid_argument", "Already sealed. What exists now is an archive; delete that from the vault, not from the queue.", { jobId: id });
+        await rm(this.path(id), { force: true });
+        return { ...job, status: "failed", updatedAt: this.stamp(), lastError: { code: "removed", message: "Taken out of the queue by hand" } };
+    }
+    async release(id, leaseId, reason) {
+        const job = this.assertLease(await this.require(id), leaseId);
+        const back = {
+            ...job, status: "ready", updatedAt: this.stamp(), lease: undefined,
+            attempts: Math.max(0, job.attempts - 1),
+            ...(reason ? { lastError: reason } : {})
+        };
+        await this.writeAtomic(back);
+        return back;
+    }
+    /** Reschedules with exponential backoff, or dead-letters once attempts are exhausted. */
+    async fail(id, leaseId, error) {
+        const job = this.assertLease(await this.require(id), leaseId);
+        const exhausted = job.attempts >= this.maxAttempts;
+        const delay = Math.min(this.backoffMs * 2 ** Math.max(0, job.attempts - 1), this.maxBackoffMs);
+        const next = {
+            ...job, status: exhausted ? "failed" : "ready", updatedAt: this.stamp(), lease: undefined, lastError: error,
+            nextAttemptAt: exhausted ? job.nextAttemptAt : new Date(this.now() + delay).toISOString()
+        };
+        await this.writeAtomic(next);
+        return next;
+    }
+    /** Explicit operator action: a dead-lettered job never revives itself. */
+    async retry(id) {
+        const job = await this.require(id);
+        if (job.status === "done")
+            fail("invalid_argument", `Job ${id} already completed`, { jobId: id });
+        const revived = { ...job, status: "ready", attempts: 0, updatedAt: this.stamp(), nextAttemptAt: this.stamp(), lease: undefined };
+        await this.writeAtomic(revived);
+        return revived;
+    }
+}

package/dist/src/recovery.d.ts

@@ -0,0 +1,40 @@
+import { isMnemonic, PHRASE_WORDS } from "./mnemonic.js";
+import type { VaultConfig } from "./types.js";
+/**
+ * The recovery kit.
+ *
+ * Everything a person needs to get their archives back, except the one thing that
+ * must never be stored: the phrase itself. The sheet leaves numbered blanks for it,
+ * because the point of a written kit is that it lives on paper, in a drawer, far
+ * from the machine it unlocks.
+ */
+/**
+ * The sheet someone reads during an actual disaster.
+ *
+ * `managed` says this vault pushes to Sealkeep Cloud. Without it the kit told
+ * a paying customer "Storage: this machine only" and left the cloud steps out
+ * of the restore instructions — so the one document they reach for after
+ * losing the laptop would tell them their archives went with it.
+ */
+export declare function recoveryKit(config: VaultConfig, options?: {
+    now?: Date;
+    managed?: {
+        email: string;
+    } | null;
+}): string;
+export type VerifyResult = {
+    valid: boolean;
+    matchesVault: boolean;
+    problems: string[];
+};
+/** Checks a typed phrase for shape, checksum, and whether it opens this vault. */
+export declare function verifyPhrase(config: VaultConfig, typed: string): VerifyResult;
+/**
+ * Asks the person to type their phrase back, the way a wallet does.
+ *
+ * Input is read without echo so it does not end up in a screenshot or a scrollback
+ * buffer, and it is never written anywhere.
+ */
+export declare function promptForPhrase(prompt?: string): Promise<string>;
+export declare function verifyAgainstVault(dataDir: string, typed: string): Promise<VerifyResult>;
+export { isMnemonic, PHRASE_WORDS };