sealkeep 0.5.0

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

@@ -0,0 +1,85 @@
+import type { TranscriptCandidate } from "./adapters.js";
+/**
+ * What leaves this machine.
+ *
+ * The rules are set in the account panel and enforced here, on the machine,
+ * before anything is queued — so a session the customer excluded is never read,
+ * never sealed, and never uploaded. Deciding this server-side would be theatre:
+ * by the time the server could refuse an upload, the bytes would already be in
+ * flight.
+ *
+ * The last fetched copy is cached beside the vault so autopilot keeps honouring
+ * the customer's choice while the control plane is unreachable. Falling back to
+ * "upload everything" when we cannot read the rules would upload exactly what
+ * someone chose to hold back, so the cache is the answer rather than a default.
+ */
+export type SyncMode = "all" | "recent" | "settled";
+export type SyncRules = {
+    mode: SyncMode;
+    keepLast: number;
+    minAgeDays: number;
+};
+export declare const DEFAULT_SYNC_RULES: SyncRules;
+/**
+ * The whole cached answer, not just the rules.
+ *
+ * The account's reply already carries plan, email and quota alongside the sync
+ * fields, and for a long time those were thrown away — so the dashboard asked
+ * the control plane again (a second identical request per settings read), and a
+ * machine that went offline forgot its owner was a paying customer: the plan
+ * badge vanished and every plan-gated surface degraded to the free look. One
+ * response, one file, everything it said.
+ */
+export type AccountSnapshot = {
+    plan: "free" | "pro_lite" | "pro" | null;
+    email: string | null;
+    quota: {
+        usedBytes: number;
+        quotaBytes: number;
+    } | null;
+    /** 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 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;
+/**
+ * The account, remembered if recent, live if stale, remembered again if the
+ * control plane is unreachable.
+ *
+ * `source: "account"` means this is the account's answer — just now, or within
+ * the TTL; `"cache"` is an old answer being served because nothing fresher can
+ * be had (with `fetchedAt` saying how old); `"none"` is a vault that has never
+ * been linked. The TTL matters more than it looks: asking live on every read
+ * 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";
+}>;
+/**
+ * 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
+ * this machine has never successfully read them.
+ */
+export declare function resolveSyncRules(dataDir: string): Promise<{
+    rules: SyncRules;
+    source: "account" | "cache" | "default";
+}>;
+/**
+ * Applies the rules to what was found on disk.
+ *
+ * `recent` keeps the newest N by modification time. `settled` keeps only what
+ * has not been touched for `minAgeDays`, so work still in progress stays put.
+ * Both are computed against `now` rather than read from the clock directly, so
+ * the behaviour is testable.
+ */
+export declare function applySyncRules(found: readonly TranscriptCandidate[], rules: SyncRules, now?: number): {
+    included: TranscriptCandidate[];
+    heldBack: TranscriptCandidate[];
+};
+export declare function describeSyncRules(rules: SyncRules): string;

package/dist/src/sync-rules.js

@@ -0,0 +1,125 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const DEFAULT_SYNC_RULES = { mode: "all", keepLast: 20, minAgeDays: 7 };
+const CACHE = "sync-rules.json";
+function coerce(raw) {
+    const mode = raw?.sync_mode === "recent" || raw?.sync_mode === "settled" ? raw.sync_mode : "all";
+    const keepLast = Number(raw?.sync_keep_last);
+    const minAgeDays = Number(raw?.sync_min_age_days);
+    return {
+        mode,
+        keepLast: Number.isFinite(keepLast) && keepLast > 0 ? Math.floor(keepLast) : DEFAULT_SYNC_RULES.keepLast,
+        minAgeDays: Number.isFinite(minAgeDays) && minAgeDays > 0 ? minAgeDays : DEFAULT_SYNC_RULES.minAgeDays
+    };
+}
+/** 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 used = Number(raw?.quota?.usedBytes ?? raw?.used_bytes);
+    const limit = Number(raw?.quota?.quotaBytes ?? raw?.quota_bytes);
+    return {
+        plan,
+        email: typeof raw?.email === "string" && raw.email.includes("@") ? raw.email : null,
+        quota: Number.isFinite(used) && Number.isFinite(limit) ? { usedBytes: used, quotaBytes: limit } : null,
+        fetchedAt: typeof raw?.fetchedAt === "string" ? raw.fetchedAt : null
+    };
+}
+export async function cacheSyncRules(dataDir, raw) {
+    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 });
+    return rules;
+}
+export async function cachedSyncRules(dataDir) {
+    try {
+        const saved = JSON.parse(await readFile(join(dataDir, CACHE), "utf8"));
+        return coerce({ sync_mode: saved.mode, sync_keep_last: saved.keepLast, sync_min_age_days: saved.minAgeDays });
+    }
+    catch {
+        return null;
+    }
+}
+/** The last account answer this machine ever received; null on a vault that never had one. */
+export async function cachedAccount(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;
+    }
+    catch {
+        return null;
+    }
+}
+/** How long the last account answer is served as-is before asking again. */
+export const ACCOUNT_TTL_MS = 5 * 60_000;
+/**
+ * The account, remembered if recent, live if stale, remembered again if the
+ * control plane is unreachable.
+ *
+ * `source: "account"` means this is the account's answer — just now, or within
+ * the TTL; `"cache"` is an old answer being served because nothing fresher can
+ * be had (with `fetchedAt` saying how old); `"none"` is a vault that has never
+ * been linked. The TTL matters more than it looks: asking live on every read
+ * put a ~4-second network round trip inside GET /v1/status, which every page's
+ * 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) {
+        return { account: recent, source: "account" };
+    }
+    try {
+        const { accountStatus } = await import("./cloud.js");
+        const raw = await accountStatus(dataDir);
+        await cacheSyncRules(dataDir, raw);
+        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" };
+    }
+}
+/**
+ * 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
+ * this machine has never successfully read them.
+ */
+export async function resolveSyncRules(dataDir) {
+    try {
+        const { accountStatus } = await import("./cloud.js");
+        return { rules: await cacheSyncRules(dataDir, await accountStatus(dataDir)), source: "account" };
+    }
+    catch {
+        const cached = await cachedSyncRules(dataDir);
+        return cached ? { rules: cached, source: "cache" } : { rules: DEFAULT_SYNC_RULES, source: "default" };
+    }
+}
+/**
+ * Applies the rules to what was found on disk.
+ *
+ * `recent` keeps the newest N by modification time. `settled` keeps only what
+ * has not been touched for `minAgeDays`, so work still in progress stays put.
+ * Both are computed against `now` rather than read from the clock directly, so
+ * the behaviour is testable.
+ */
+export function applySyncRules(found, rules, now = Date.now()) {
+    if (rules.mode === "all")
+        return { included: [...found], heldBack: [] };
+    const newestFirst = [...found].sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+    const included = rules.mode === "recent"
+        ? newestFirst.slice(0, rules.keepLast)
+        : newestFirst.filter((item) => now - Date.parse(item.modifiedAt) >= rules.minAgeDays * 86_400_000);
+    const keep = new Set(included.map((item) => item.path));
+    return { included, heldBack: newestFirst.filter((item) => !keep.has(item.path)) };
+}
+export function describeSyncRules(rules) {
+    if (rules.mode === "recent")
+        return `the ${rules.keepLast} most recent sessions`;
+    if (rules.mode === "settled")
+        return `sessions untouched for ${rules.minAgeDays} days`;
+    return "every session";
+}

package/dist/src/trash.d.ts

@@ -0,0 +1,15 @@
+export type TrashResult = {
+    movedTo: string;
+    strategy: "macos-trash" | "xdg-trash" | "windows-recycle-bin" | "vaultline-trash";
+};
+/**
+ * Moves a reclaimed source to the operating system's trash, so a mistake is
+ * recoverable by the user without Sealkeep's help. Nothing here ever unlinks a
+ * file: the worst case is a move into a Sealkeep-owned trash directory.
+ */
+export declare function moveToTrash(path: string, options: {
+    dataDir: string;
+    home?: string;
+    strategy?: TrashResult["strategy"];
+}): Promise<TrashResult>;
+export declare function defaultStrategy(): TrashResult["strategy"];

package/dist/src/trash.js

@@ -0,0 +1,63 @@
+import { execFile } from "node:child_process";
+import { mkdir, rename, stat, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { fail } from "./errors.js";
+const run = promisify(execFile);
+async function uniquePath(directory, name) {
+    let candidate = join(directory, name);
+    for (let suffix = 1; suffix < 1000; suffix += 1) {
+        if (!(await stat(candidate).catch(() => null)))
+            return candidate;
+        candidate = join(directory, `${name}.${suffix}`);
+    }
+    return join(directory, `${name}.${Date.now()}`);
+}
+/**
+ * Moves a reclaimed source to the operating system's trash, so a mistake is
+ * recoverable by the user without Sealkeep's help. Nothing here ever unlinks a
+ * file: the worst case is a move into a Sealkeep-owned trash directory.
+ */
+export async function moveToTrash(path, options) {
+    const home = options.home ?? homedir();
+    const strategy = options.strategy ?? defaultStrategy();
+    const name = basename(path);
+    if (!(await stat(path).catch(() => null)))
+        fail("source_unreadable", `Nothing to reclaim at ${path}`, { path });
+    if (strategy === "macos-trash") {
+        const target = await uniquePath(join(home, ".Trash"), name);
+        await mkdir(join(home, ".Trash"), { recursive: true });
+        await rename(path, target);
+        return { movedTo: target, strategy };
+    }
+    if (strategy === "xdg-trash") {
+        const root = process.env.XDG_DATA_HOME ? join(process.env.XDG_DATA_HOME, "Trash") : join(home, ".local", "share", "Trash");
+        await mkdir(join(root, "files"), { recursive: true });
+        await mkdir(join(root, "info"), { recursive: true });
+        const target = await uniquePath(join(root, "files"), name);
+        // The .trashinfo sidecar is what lets a desktop file manager offer "restore".
+        await writeFile(`${join(root, "info", basename(target))}.trashinfo`, `[Trash Info]\nPath=${path}\nDeletionDate=${new Date().toISOString().replace(/\.\d{3}Z$/, "")}\n`, { mode: 0o600 });
+        await rename(path, target);
+        return { movedTo: target, strategy };
+    }
+    if (strategy === "windows-recycle-bin") {
+        const script = `Add-Type -AssemblyName Microsoft.VisualBasic; [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($env:VL_PATH,'OnlyErrorDialogs','SendToRecycleBin')`;
+        await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script], { env: { ...process.env, VL_PATH: path } });
+        return { movedTo: "Recycle Bin", strategy };
+    }
+    const root = join(options.dataDir, "trash", new Date().toISOString().slice(0, 10));
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const target = await uniquePath(root, name);
+    await rename(path, target);
+    return { movedTo: target, strategy: "vaultline-trash" };
+}
+export function defaultStrategy() {
+    if (platform() === "darwin")
+        return "macos-trash";
+    if (platform() === "linux")
+        return "xdg-trash";
+    if (platform() === "win32")
+        return "windows-recycle-bin";
+    return "vaultline-trash";
+}

package/dist/src/tui.d.ts

@@ -0,0 +1,18 @@
+export type View = "overview" | "queue" | "archives" | "retention" | "health";
+export declare const VIEWS: View[];
+export type TuiClient = {
+    get(path: string): Promise<any>;
+};
+export declare function apiClient(base: string, token: string): TuiClient;
+export declare function formatBytes(value: number): string;
+/** Renders one frame. Pure so it can be tested without a terminal. */
+export declare function renderFrame(view: View, state: Record<string, any>, width?: number): string;
+export declare function loadState(client: TuiClient): Promise<Record<string, any>>;
+export type TuiOptions = {
+    base?: string;
+    token?: string;
+    out?: NodeJS.WriteStream;
+    input?: NodeJS.ReadStream;
+};
+/** Starts the interactive loop. Resolves when the user quits. */
+export declare function runTui(dataDir: string, options?: TuiOptions): Promise<void>;

package/dist/src/tui.js

@@ -0,0 +1,179 @@
+import { PRODUCT_MARK, PRODUCT_NAME } from "./branding.js";
+import { emitKeypressEvents } from "node:readline";
+import { createLocalApiServer, localApiToken } from "./local-api.js";
+import { freePort } from "./net.js";
+/**
+ * A keyboard-first terminal view over the local API.
+ *
+ * It renders with plain ANSI and reads only from `/v1`, so it shows exactly what
+ * the dashboard shows and works unchanged over SSH. If no agent is listening it
+ * starts a private one on a loopback port for the lifetime of the session.
+ */
+const ESC = "[";
+const RESET = `${ESC}0m`;
+const DIM = `${ESC}2m`;
+const BOLD = `${ESC}1m`;
+const GREEN = `${ESC}32m`;
+const YELLOW = `${ESC}33m`;
+const RED = `${ESC}31m`;
+const BLUE = `${ESC}34m`;
+export const VIEWS = ["overview", "queue", "archives", "retention", "health"];
+export function apiClient(base, token) {
+    return {
+        async get(path) {
+            const response = await fetch(`${base}${path}`, { headers: { authorization: `Bearer ${token}` } });
+            const body = await response.json().catch(() => ({}));
+            if (!response.ok)
+                throw new Error(body?.error?.message ?? `${response.status} ${response.statusText}`);
+            return body;
+        }
+    };
+}
+export function formatBytes(value) {
+    if (!Number.isFinite(value))
+        return "-";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let size = value;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? size : size.toFixed(1)}${units[unit]}`;
+}
+function truncate(value, width) {
+    if (value.length <= width)
+        return value.padEnd(width);
+    return `…${value.slice(-(width - 1))}`;
+}
+function statusColour(status) {
+    if (status === "done" || status === "pass")
+        return GREEN;
+    if (status === "failed" || status === "fail")
+        return RED;
+    if (status === "warn" || status === "leased")
+        return YELLOW;
+    return "";
+}
+/** Renders one frame. Pure so it can be tested without a terminal. */
+export function renderFrame(view, state, width = 100) {
+    const lines = [];
+    const tabs = VIEWS.map((name, index) => (name === view ? `${BLUE}${BOLD}[${index + 1} ${name}]${RESET}` : `${DIM}${index + 1} ${name}${RESET}`)).join("  ");
+    lines.push(`${BOLD}${PRODUCT_MARK} ${PRODUCT_NAME}${RESET}  ${DIM}${state.status?.vaultId?.slice(0, 8) ?? "no vault"}${RESET}`);
+    lines.push(tabs);
+    lines.push("─".repeat(Math.min(width, 100)));
+    if (view === "overview") {
+        const status = state.status ?? {};
+        const retention = state.retention ?? {};
+        lines.push(`Archives   ${BOLD}${status.archiveCount ?? 0}${RESET}  (${formatBytes(status.archivedBytes ?? 0)} of source preserved)`);
+        lines.push(`Queue      ${status.queue?.ready ?? 0} ready · ${status.queue?.leased ?? 0} in flight · ${status.queue?.done ?? 0} archived · ${status.queue?.failed ?? 0} failed`);
+        lines.push(`Remote     ${status.remoteStorage ? `${status.remoteStorage.provider}://${status.remoteStorage.bucket}/${status.remoteStorage.prefix}` : `${DIM}none configured${RESET}`}`);
+        lines.push(`Retention  policy ${retention.policy ?? "?"} · ${formatBytes(retention.reclaimableBytes ?? 0)} reclaimable`);
+        lines.push("");
+        for (const agent of state.agents ?? []) {
+            lines.push(`${agent.detected ? `${GREEN}✓${RESET}` : `${DIM}·${RESET}`} ${agent.agent.padEnd(8)} ${DIM}${agent.root}${RESET}`);
+        }
+    }
+    if (view === "queue") {
+        const jobs = state.queue ?? [];
+        lines.push(`${DIM}${"status".padEnd(9)}${"agent".padEnd(9)}${"event".padEnd(13)}${"tries".padEnd(7)}source${RESET}`);
+        if (jobs.length === 0)
+            lines.push(`${DIM}Nothing queued.${RESET}`);
+        for (const job of jobs.slice(0, 20)) {
+            lines.push(`${statusColour(job.status)}${job.status.padEnd(9)}${RESET}${job.agent.padEnd(9)}${job.event.padEnd(13)}${String(job.attempts).padEnd(7)}${truncate(job.sourcePath, 46)}`);
+        }
+    }
+    if (view === "archives") {
+        const archives = state.archives ?? [];
+        lines.push(`${DIM}${"created".padEnd(22)}${"agent".padEnd(9)}${"bytes".padEnd(9)}${"remote".padEnd(11)}source${RESET}`);
+        if (archives.length === 0)
+            lines.push(`${DIM}No archives yet.${RESET}`);
+        for (const archive of archives.slice(0, 20)) {
+            const remote = archive.remote ? `${GREEN}verified${RESET}   ` : `${DIM}local${RESET}      `;
+            lines.push(`${new Date(archive.createdAt).toISOString().slice(0, 19).replace("T", " ").padEnd(22)}${archive.agent.padEnd(9)}${formatBytes(archive.bytes).padEnd(9)}${remote}${truncate(archive.path, 38)}`);
+        }
+    }
+    if (view === "retention") {
+        const retention = state.retention ?? {};
+        lines.push(`Policy ${BOLD}${retention.policy ?? "?"}${RESET} · older than ${retention.olderThanDays ?? "?"} days · ${retention.graceDays ?? "?"}-day grace`);
+        lines.push(`${DIM}Reclaimed sources move to the OS trash. Preview never touches the disk.${RESET}`);
+        lines.push("");
+        for (const candidate of (retention.candidates ?? []).slice(0, 15)) {
+            lines.push(`${candidate.eligible ? `${GREEN}eligible${RESET}` : `${DIM}held    ${RESET}`} ${truncate(candidate.path, 40)} ${DIM}${candidate.blockers?.[0] ?? ""}${RESET}`);
+        }
+        if ((retention.candidates ?? []).length === 0)
+            lines.push(`${DIM}No local sources are tracked for reclamation.${RESET}`);
+    }
+    if (view === "health") {
+        for (const check of state.doctor?.checks ?? []) {
+            lines.push(`${statusColour(check.status)}${check.status.padEnd(6)}${RESET}${check.name.padEnd(20)}${DIM}${check.detail}${RESET}`);
+        }
+    }
+    lines.push("");
+    lines.push(`${DIM}1-5 switch view · r refresh · q quit${RESET}`);
+    if (state.error)
+        lines.push(`${RED}${state.error}${RESET}`);
+    return lines.join("\n");
+}
+export async function loadState(client) {
+    const [status, queue, archives, retention, doctor, agents] = await Promise.all([
+        client.get("/v1/status"), client.get("/v1/queue"), client.get("/v1/archives"),
+        client.get("/v1/retention"), client.get("/v1/doctor"), client.get("/v1/agents")
+    ]);
+    return { status, queue, archives, retention, doctor, agents };
+}
+/** Starts the interactive loop. Resolves when the user quits. */
+export async function runTui(dataDir, options = {}) {
+    const out = options.out ?? process.stdout;
+    const input = options.input ?? process.stdin;
+    let owned;
+    let base = options.base;
+    const token = options.token ?? await localApiToken(dataDir);
+    if (!base) {
+        owned = createLocalApiServer(dataDir, token);
+        const port = await freePort(4190);
+        await new Promise((ready) => owned.listen(port, "127.0.0.1", ready));
+        base = `http://127.0.0.1:${port}`;
+    }
+    const client = apiClient(base, token);
+    let view = "overview";
+    let state = {};
+    async function draw() {
+        try {
+            state = { ...(await loadState(client)) };
+        }
+        catch (error) {
+            state = { ...state, error: error instanceof Error ? error.message : "could not read local state" };
+        }
+        out.write(`${ESC}2J${ESC}H${renderFrame(view, state, out.columns ?? 100)}\n`);
+    }
+    emitKeypressEvents(input);
+    if (input.isTTY)
+        input.setRawMode(true);
+    input.resume();
+    await draw();
+    await new Promise((done) => {
+        const onKey = (_chunk, key) => {
+            if (key?.name === "q" || (key?.ctrl && key?.name === "c")) {
+                input.off("keypress", onKey);
+                if (input.isTTY)
+                    input.setRawMode(false);
+                input.pause();
+                out.write(`${ESC}0m\n`);
+                done();
+                return;
+            }
+            if (key?.name === "r") {
+                void draw();
+                return;
+            }
+            const index = Number(key?.sequence ?? key?.name);
+            if (Number.isInteger(index) && index >= 1 && index <= VIEWS.length) {
+                view = VIEWS[index - 1];
+                void draw();
+            }
+        };
+        input.on("keypress", onKey);
+    });
+    await new Promise((closed) => (owned ? owned.close(() => closed()) : closed()));
+}

package/dist/src/types.d.ts

@@ -0,0 +1,191 @@
+import type { Envelope, Suite } from "../packages/vaultline-crypto/src/index.js";
+/** The original prototype envelope. Still readable; never written by this build. */
+export type ArchiveRecordV1 = {
+    version: 1;
+    id: string;
+    createdAt: string;
+    source: {
+        path: string;
+        agent: string;
+        bytes: number;
+        sha256: string;
+    };
+    cipher: {
+        algorithm: "aes-256-gcm";
+        nonce: string;
+        authTag: string;
+        ciphertextSha256: string;
+        compression: "none";
+    };
+    wrappedKey: {
+        algorithm: "scrypt-aes-256-gcm";
+        salt: string;
+        nonce: string;
+        authTag: string;
+        ciphertext: string;
+    };
+    objectPath: string;
+};
+/** A remote copy the client uploaded and then verified. Written only after verification. */
+export type RemoteObject = {
+    provider: string;
+    bucket: string;
+    /** Single-object layout: the object's key. Chunk layout: the FOLDER prefix (no trailing slash). */
+    objectKey: string;
+    bytes: number;
+    /** Base64 SHA-256 of the stored ciphertext, confirmed against the provider. */
+    checksum: string;
+    verifiedAt: string;
+    /**
+     * Present when the remote is a FOLDER of chunk objects (`chunk-000000`…)
+     * plus an `envelope.vlmeta` sidecar, instead of one blob. Every chunk is
+     * independently sealed and independently fetchable; the sidecar makes the
+     * folder self-recovering with nothing but the recovery phrase. Absent means
+     * the original single-object layout, which stays readable forever.
+     */
+    layout?: {
+        kind: "chunks";
+        chunkCount: number;
+    };
+    /** Which configured storage target this copy went to, for usage accounting. */
+    targetId?: string;
+};
+/** The current record: a `vaultline-crypto` v2 envelope plus local bookkeeping. */
+export type ArchiveRecordV2 = {
+    version: 2;
+    id: string;
+    createdAt: string;
+    source: {
+        path: string;
+        agent: string;
+        bytes: number;
+        sha256: string;
+    };
+    /** Summary of the stored object, shared with v1 so callers can treat both alike. */
+    cipher: {
+        algorithm: Suite;
+        ciphertextSha256: string;
+        storedBytes: number;
+        chunks: number;
+    };
+    envelope: Envelope;
+    objectPath: string;
+    remote?: RemoteObject;
+    /** Set once the local source has been moved to the trash. The archive itself stays. */
+    reclaimed?: {
+        at: string;
+        trashPath: string;
+        strategy: string;
+    };
+    /**
+     * Set once the local *archive* has been removed because a verified remote
+     * copy exists. The archive is not gone — it is in the bucket, and restoring
+     * fetches it back — but `objectPath` no longer names a file.
+     *
+     * This is what makes reclaiming actually free the disk. Removing the source
+     * alone leaves a sealed copy that is about two thirds of it on real
+     * transcripts, so a machine with 78 GB of sessions kept 54 GB of archives and
+     * got back a quarter of what it was promised.
+     */
+    offloaded?: {
+        at: string;
+        provider: string;
+        bucket: string;
+        objectKey: string;
+    };
+    /**
+     * The archive whose bytes this one re-archived, and how many of them.
+     *
+     * Agent transcripts only ever grow, so a snapshot taken after another one has
+     * that archive's whole content inside it — a 4 GB session snapshotted ten
+     * times spends 40 GB of storage on 4 GB of transcript. This names the
+     * redundancy where it can be seen, proved at archive time by re-reading and
+     * hashing the earlier archive's byte range (`provenAppendOffset`).
+     *
+     * It changes nothing about how the archive is read: every archive is still
+     * complete and standalone, which is why the record version does not move. It
+     * is the pointer a delta archive would seal from.
+     */
+    supersedes?: {
+        archiveId: string;
+        bytes: number;
+    };
+    /**
+     * Present only on a delta archive: this record's ciphertext holds bytes
+     * `[baseBytes, source.bytes)` of the transcript, and the named base archive
+     * (itself possibly a delta) holds the rest. `source` still describes the
+     * WHOLE file, so dedupe, retention's size gate and prefix-proofs stay
+     * honest. A delta NEEDS its base — which is why a delta never writes
+     * `supersedes`: that field offers its target for deletion.
+     */
+    delta?: {
+        baseArchiveId: string;
+        baseBytes: number;
+    };
+};
+export type ArchiveRecord = ArchiveRecordV1 | ArchiveRecordV2;
+export type StorageTargetConfig = {
+    id: string;
+    provider: "vaultline" | "s3" | "r2" | "b2" | "gcs" | "gdrive";
+    bucket?: string;
+    prefix?: string;
+    region?: string;
+    maxGb?: number;
+    projects?: string[];
+    priority?: number;
+};
+export declare function isV2(record: ArchiveRecord): record is ArchiveRecordV2;
+export type VaultConfig = {
+    version: 1;
+    vaultId: string;
+    storage: {
+        provider: "local";
+        root: string;
+    };
+    /**
+     * Chosen once, at creation. Absent means sealed, so every vault written
+     * before this field existed keeps loading — and keeps being read as
+     * encrypted, which is what it is. "plain" stores archives as bare gzip for
+     * people who want portable, readable memory; the recovery phrase still
+     * exists and still identifies the vault, but protects nothing in this mode.
+     */
+    storageMode?: "sealed" | "plain";
+    /** Desired remote target. Credentials and signed URLs never live here. */
+    remoteStorage?: {
+        provider: "vaultline" | "s3" | "r2" | "b2" | "gcs" | "gdrive";
+        bucket: string;
+        prefix: string;
+        region?: string;
+    };
+    /** Multiple simultaneous storage targets with routing rules; wins over remoteStorage when present. */
+    storageTargets?: StorageTargetConfig[];
+    recovery: {
+        phraseCheck: string;
+    };
+    /** X25519 recipients that may also open new archives: devices and extra recovery keys. */
+    recipients?: {
+        id: string;
+        label: string;
+        publicKey: string;
+        addedAt: string;
+        group?: string;
+    }[];
+    /** `deleteAfterDays` is optional so vaults written before archive lifecycle existed still load; absent means never. */
+    retention?: {
+        policy: "local-only" | "sync-only" | "archive-and-reclaim" | "manual-approval";
+        olderThanDays: number;
+        graceDays: number;
+        deleteAfterDays?: number | null;
+    };
+    /** Ed25519 public keys, by key id, that may sign a release this client will accept. */
+    updateKeys?: Record<string, string>;
+    /** How many seals may run at once (1–4). Absent means one at a time. */
+    sealConcurrency?: number;
+    /**
+     * How chunk-folder remotes are named. "readable" (default): project/date/
+     * session as words — browsable in your own bucket's console. "hashed":
+     * the same structure with every segment HMAC'd under a phrase-derived key —
+     * grouping without meaning, for buckets where names would leak.
+     */
+    remoteNaming?: "readable" | "hashed";
+};