@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

package/dist/backup/core/homes.js

@@ -0,0 +1,54 @@
+/**
+ * Agent homes a per-home backup target runs for.
+ *
+ * A home is `<root>/<ownerType>/<ownerId>/agents/<agentId>/` holding the
+ * target's marker file (presence keeps each agent's inner world there). The
+ * root comes from the target, resolved on the caller's runtime roots; nothing
+ * reads the process home or guesses an agent.
+ */
+import { CapabilityError, CaughtFailureSchema } from "@vibesdotdev/kernel";
+import { backupEntryKind } from "./io.js";
+/** `<ownerType>/<ownerId>/<agentId>`: how a home is named in results and provenance. */
+export function agentHomeLabel(home) {
+    return `${home.ownerType}/${home.ownerId}/${home.agentId}`;
+}
+/** Real subdirectories of `dir`, sorted; links are not homes and are never followed. */
+async function subdirectories(io, dir) {
+    const entries = await io.fs.list(dir);
+    return entries.filter((entry) => entry.kind === "directory").map((entry) => entry.name).sort();
+}
+/**
+ * Every agent home under `root` that holds `marker` (a regular file, not a
+ * link). A missing root is no homes; a root or owner directory that cannot be
+ * read refuses with `backup-agent-homes-unreadable` rather than backing up a
+ * partial set silently.
+ */
+export async function listBackupAgentHomes(io, root, marker) {
+    if ((await backupEntryKind(io, root)) !== "directory")
+        return [];
+    const homes = [];
+    try {
+        for (const ownerType of await subdirectories(io, root)) {
+            for (const ownerId of await subdirectories(io, io.path.join(root, ownerType))) {
+                const agentsDir = io.path.join(root, ownerType, ownerId, "agents");
+                if ((await backupEntryKind(io, agentsDir)) !== "directory")
+                    continue;
+                for (const agentId of await subdirectories(io, agentsDir)) {
+                    const dir = io.path.join(agentsDir, agentId);
+                    if ((await backupEntryKind(io, io.path.join(dir, marker))) === "file")
+                        homes.push({ ownerType, ownerId, agentId, dir });
+                }
+            }
+        }
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        throw new CapabilityError("The agent homes for a per-home backup target could not be listed.", "UNAVAILABLE", {
+            reason: "backup-agent-homes-unreadable",
+            details: { root, marker },
+            cause: failure instanceof Error ? failure : undefined,
+        });
+    }
+    return homes;
+}
+//# sourceMappingURL=homes.js.map

package/dist/backup/core/homes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"homes.js","sourceRoot":"","sources":["../../../src/backup/core/homes.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAiB,MAAM,SAAS,CAAC;AAEzD,wFAAwF;AACxF,MAAM,UAAU,cAAc,CAAC,IAAqB;IAClD,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;AAC7D,CAAC;AAED,wFAAwF;AACxF,KAAK,UAAU,cAAc,CAAC,EAAY,EAAE,GAAW;IACrD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AACjG,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,EAAY,EAAE,IAAY,EAAE,MAAc;IACnF,IAAI,CAAC,MAAM,eAAe,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,KAAK,WAAW;QAAE,OAAO,EAAE,CAAC;IACjE,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,KAAK,MAAM,SAAS,IAAI,MAAM,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC;YACvD,KAAK,MAAM,OAAO,IAAI,MAAM,cAAc,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;gBAC9E,MAAM,SAAS,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;gBACnE,IAAI,CAAC,MAAM,eAAe,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,KAAK,WAAW;oBAAE,SAAS;gBACrE,KAAK,MAAM,OAAO,IAAI,MAAM,cAAc,CAAC,EAAE,EAAE,SAAS,CAAC,EAAE,CAAC;oBAC1D,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;oBAC7C,IAAI,CAAC,MAAM,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM;wBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC1H,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjD,MAAM,IAAI,eAAe,CAAC,mEAAmE,EAAE,aAAa,EAAE;YAC5G,MAAM,EAAE,+BAA+B;YACvC,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;YACzB,KAAK,EAAE,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SACtD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/backup/core/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Backup core barrel
+ */
+export { expandPath, resolveDestinationDir, resolveTargetPaths, backupPathRoots, snapshotPathFor, } from "./paths.ts";
+export { backupIoOf, backupEntryKind, BACKUP_FILE_MODE } from "./io.ts";
+export type { BackupIo, BackupEntryKind } from "./io.ts";
+export type { BackupPathRoots, BackupPathRuntime, ResolvedTargetPaths } from "./paths.ts";
+export { sha256OfFile } from "./hash.ts";
+export type { RotationDecision } from "./rotation.ts";
+export { planRotation } from "./rotation.ts";
+export type { RunSnapshotOptions, SnapshotCoreResult } from "./snapshot.ts";
+export { runSnapshot, BACKUP_TARGET_EMPTY, BACKUP_SOURCE_SYMLINK } from "./snapshot.ts";
+export { listBackupTargets } from "./registry.ts";
+export { verifyRecoveryDrillEvidence } from "./recovery.ts";
+export type { RecoveryDrillVerification } from "./recovery.ts";
+export { evaluateRecoveryReadiness } from "./readiness.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/backup/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backup/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,UAAU,EACV,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACxE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACzD,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAC5D,YAAY,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/backup/core/index.js

@@ -0,0 +1,12 @@
+/**
+ * Backup core barrel
+ */
+export { expandPath, resolveDestinationDir, resolveTargetPaths, backupPathRoots, snapshotPathFor, } from "./paths.js";
+export { backupIoOf, backupEntryKind, BACKUP_FILE_MODE } from "./io.js";
+export { sha256OfFile } from "./hash.js";
+export { planRotation } from "./rotation.js";
+export { runSnapshot, BACKUP_TARGET_EMPTY, BACKUP_SOURCE_SYMLINK } from "./snapshot.js";
+export { listBackupTargets } from "./registry.js";
+export { verifyRecoveryDrillEvidence } from "./recovery.js";
+export { evaluateRecoveryReadiness } from "./readiness.js";
+//# sourceMappingURL=index.js.map

package/dist/backup/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/backup/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,UAAU,EACV,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGxE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAE5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/backup/core/io.d.ts

@@ -0,0 +1,76 @@
+import type { HashedFile, CopyExpectation } from '../schemas/core.ts';
+export type { HashedFile, CopyExpectation } from '../schemas/core.ts';
+/**
+ * Backup I/O through the runtime's own kinds.
+ *
+ * Backup reads and writes host files at absolute paths (the Vibes home and
+ * its backups directory), so it uses the host filesystem adapter
+ * (`filesystem/adapter`, unbound) for bytes and for its path mechanics, and
+ * LocalDB's SQLite driver kind (`localdb/sqlite-driver`) for SQLite
+ * snapshots. It holds no host API of its own.
+ *
+ * Files are moved in bounded chunks, never held whole: a snapshot can be
+ * gigabytes (awareness.db). A file up to one chunk is read with
+ * `readFileNoFollow` (which refuses a final symlink atomically); a larger one
+ * is classified with the adapter's no-follow `stat`, read in ranges, and
+ * stat'ed again afterwards: a source that became a link, or changed size or
+ * time while it was read, refuses and nothing is published (copies go through
+ * `writeFileStream`, which renames a finished temporary file into place).
+ * Hashes are computed incrementally (`createSha256` from shared).
+ *
+ * Every link refusal is the typed, value-free `PERMISSION_DENIED
+ * backup-source-symlink`.
+ */
+import { CapabilityError, type RuntimeRef } from "@vibesdotdev/kernel";
+import { sqliteDriverOf } from "@vibesdotdev/localdb";
+import { type HostEntryKind, type HostFileSystem, type HostPathOps } from "../../host-files.ts";
+/** The runtime backup I/O resolves on. */
+export type BackupIoRuntime = RuntimeRef;
+/** LocalDB's SQLite driver contract, as its kind resolves it. */
+export type BackupSqliteDriver = Awaited<ReturnType<typeof sqliteDriverOf>>;
+/** The host path mechanics backup uses: the filesystem adapter's own. */
+export type BackupPathOps = HostPathOps;
+/** The host capabilities a backup run uses, resolved once per run from its runtime. */
+export interface BackupIo {
+    readonly fs: HostFileSystem;
+    readonly path: BackupPathOps;
+    /** Resolved on first use: only SQLite sources need it. */
+    readonly sqlite: () => Promise<BackupSqliteDriver>;
+}
+/** Mode of every file a snapshot or a restore writes: owner read/write only. */
+export declare const BACKUP_FILE_MODE = 384;
+/** Walk bounds for a `directory` source: deeper or larger trees refuse typed. */
+export declare const BACKUP_DIRECTORY_MAX_DEPTH = 32;
+export declare const BACKUP_DIRECTORY_MAX_ENTRIES = 100000;
+/** The largest piece of a file held in memory at once. */
+export declare const BACKUP_CHUNK_BYTES: number;
+/** The unbound host filesystem adapter (absolute host paths, never a workspace binding). */
+export declare function backupFileSystemOf(runtime: RuntimeRef): Promise<HostFileSystem>;
+export declare function backupIoOf(runtime: BackupIoRuntime): Promise<BackupIo>;
+/** What a source path is, read without following a link. */
+export type BackupEntryKind = HostEntryKind;
+/** Classify `path` without following a link; only a confirmed absence is `missing`. */
+export declare function backupEntryKind(io: BackupIo, path: string): Promise<BackupEntryKind>;
+/** The refusal for a link where a backup or restore expects a file or directory. */
+export declare function backupSymlinkRefusal(targetId: string, cause?: Error): CapabilityError;
+/**
+ * A regular file's bytes, chunk by chunk (each at most {@link BACKUP_CHUNK_BYTES}),
+ * never through a link. A larger file is re-checked after its last chunk:
+ * one that became a link or changed while read refuses typed, so a consumer
+ * that publishes only after the last chunk never publishes it.
+ */
+export declare function readChunksNoFollow(io: BackupIo, path: string, targetId: string): AsyncGenerator<Uint8Array>;
+/** A file's size and SHA-256, read in chunks without following a link. */
+/** Hash a regular file in chunks, never through a link. */
+export declare function hashFileNoFollow(io: BackupIo, path: string, targetId: string): Promise<HashedFile>;
+/** What a copy must match: a mismatch publishes nothing. */
+/** The refusal for a copied file that does not match what was recorded. */
+export declare function backupCopyMismatch(targetId: string): CapabilityError;
+/**
+ * Copy a regular file to `destPath` (owner-only, its directory created) in
+ * chunks, never through a link, hashing as it goes. The destination appears
+ * only once every byte is written and every check passed (the stream write's
+ * temporary file is renamed into place); a refusal leaves nothing there.
+ */
+export declare function copyFileNoFollow(io: BackupIo, sourcePath: string, destPath: string, targetId: string, expect?: CopyExpectation): Promise<HashedFile>;
+//# sourceMappingURL=io.d.ts.map

package/dist/backup/core/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../../src/backup/core/io.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtE;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,eAAe,EAA0C,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE/G,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAA6C,KAAK,aAAa,EAAsB,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE/J,0CAA0C;AAC1C,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC;AAEzC,iEAAiE;AACjE,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;AAE5E,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC;AAExC,uFAAuF;AACvF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACpD;AAED,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAEtC,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,QAAkC,CAAC;AAElE,4FAA4F;AAC5F,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAErF;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAI5E;AAED,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,aAAa,CAAC;AAE5C,uFAAuF;AACvF,wBAAsB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAE1F;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,eAAe,CAMrF;AAyCD;;;;;GAKG;AACH,wBAAuB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAkBlH;AAED,0EAA0E;AAG1E,2DAA2D;AAC3D,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAQxG;AAED,4DAA4D;AAG5D,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAMpE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,QAAQ,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,UAAU,CAAC,CAgCrB"}

package/dist/backup/core/io.js

@@ -0,0 +1,177 @@
+/**
+ * Backup I/O through the runtime's own kinds.
+ *
+ * Backup reads and writes host files at absolute paths (the Vibes home and
+ * its backups directory), so it uses the host filesystem adapter
+ * (`filesystem/adapter`, unbound) for bytes and for its path mechanics, and
+ * LocalDB's SQLite driver kind (`localdb/sqlite-driver`) for SQLite
+ * snapshots. It holds no host API of its own.
+ *
+ * Files are moved in bounded chunks, never held whole: a snapshot can be
+ * gigabytes (awareness.db). A file up to one chunk is read with
+ * `readFileNoFollow` (which refuses a final symlink atomically); a larger one
+ * is classified with the adapter's no-follow `stat`, read in ranges, and
+ * stat'ed again afterwards: a source that became a link, or changed size or
+ * time while it was read, refuses and nothing is published (copies go through
+ * `writeFileStream`, which renames a finished temporary file into place).
+ * Hashes are computed incrementally (`createSha256` from shared).
+ *
+ * Every link refusal is the typed, value-free `PERMISSION_DENIED
+ * backup-source-symlink`.
+ */
+import { CapabilityError, CaughtFailureSchema, isCapabilityError } from "@vibesdotdev/kernel";
+import { FILESYSTEM_READ_RANGE_MAX_BYTES, readFileNoFollow, readFileRangeChecked, writeFileStream } from "@vibesdotdev/filesystem";
+import { sqliteDriverOf } from "@vibesdotdev/localdb";
+import { createSha256 } from "@vibesdotdev/shared/hashing";
+import { hostEntryKind, hostFileSystemOf, hostStat } from "../../host-files.js";
+/** Mode of every file a snapshot or a restore writes: owner read/write only. */
+export const BACKUP_FILE_MODE = 0o600;
+/** Walk bounds for a `directory` source: deeper or larger trees refuse typed. */
+export const BACKUP_DIRECTORY_MAX_DEPTH = 32;
+export const BACKUP_DIRECTORY_MAX_ENTRIES = 100_000;
+/** The largest piece of a file held in memory at once. */
+export const BACKUP_CHUNK_BYTES = FILESYSTEM_READ_RANGE_MAX_BYTES;
+/** The unbound host filesystem adapter (absolute host paths, never a workspace binding). */
+export async function backupFileSystemOf(runtime) {
+    return hostFileSystemOf(runtime, "backup-filesystem-unavailable");
+}
+export async function backupIoOf(runtime) {
+    const fs = await backupFileSystemOf(runtime);
+    let driver;
+    return { fs, path: fs, sqlite: () => (driver ??= sqliteDriverOf(runtime)) };
+}
+/** Classify `path` without following a link; only a confirmed absence is `missing`. */
+export async function backupEntryKind(io, path) {
+    return hostEntryKind(io.fs, path);
+}
+/** The refusal for a link where a backup or restore expects a file or directory. */
+export function backupSymlinkRefusal(targetId, cause) {
+    return new CapabilityError("A backup source entry is a symbolic link; links are never followed or copied.", "PERMISSION_DENIED", { reason: "backup-source-symlink", retryable: false, details: { targetId }, cause });
+}
+/** A file that is not there, or not a regular file, where one was expected. */
+function notRegularFile(targetId, found) {
+    return new CapabilityError("A backup file is missing or is not a regular file.", found === "missing" ? "NOT_FOUND" : "INVALID_INPUT", {
+        reason: found === "missing" ? "backup-file-missing" : "backup-file-not-regular",
+        retryable: false,
+        details: { targetId, found },
+    });
+}
+/** A file whose size or modification time moved while it was read. */
+function changedWhileRead(targetId) {
+    return new CapabilityError("A backup file changed while it was being read; nothing was kept from it.", "CONFLICT", {
+        reason: "backup-file-changed",
+        retryable: true,
+        details: { targetId },
+    });
+}
+/** The no-follow stat of a regular file at `path`, or the typed refusal for what is there instead. */
+async function regularFileStat(io, path, targetId) {
+    const stat = await hostStat(io.fs, path);
+    if (stat?.kind === "symlink")
+        throw backupSymlinkRefusal(targetId);
+    if (!stat || stat.kind !== "file")
+        throw notRegularFile(targetId, stat?.kind ?? "missing");
+    return stat;
+}
+/** A single-chunk no-follow read; a link found by the atomic read is the backup refusal. */
+async function readSmallNoFollow(io, path, targetId) {
+    try {
+        return (await readFileNoFollow(io.fs, path)).bytes;
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        if (failure instanceof Error && isCapabilityError(failure) && failure.reason === "filesystem-read-symlink") {
+            throw backupSymlinkRefusal(targetId, failure);
+        }
+        throw error;
+    }
+}
+/**
+ * A regular file's bytes, chunk by chunk (each at most {@link BACKUP_CHUNK_BYTES}),
+ * never through a link. A larger file is re-checked after its last chunk:
+ * one that became a link or changed while read refuses typed, so a consumer
+ * that publishes only after the last chunk never publishes it.
+ */
+export async function* readChunksNoFollow(io, path, targetId) {
+    const before = await regularFileStat(io, path, targetId);
+    if (before.size <= BACKUP_CHUNK_BYTES) {
+        yield await readSmallNoFollow(io, path, targetId);
+        return;
+    }
+    let offset = 0;
+    for (;;) {
+        const chunk = await readFileRangeChecked(io.fs, path, { offset, length: BACKUP_CHUNK_BYTES });
+        if (chunk.byteLength > 0)
+            yield chunk;
+        offset += chunk.byteLength;
+        if (chunk.byteLength < BACKUP_CHUNK_BYTES)
+            break;
+    }
+    const after = await hostStat(io.fs, path);
+    if (after?.kind === "symlink")
+        throw backupSymlinkRefusal(targetId);
+    if (!after || after.kind !== "file" || after.size !== before.size || after.mtime !== before.mtime || offset !== before.size) {
+        throw changedWhileRead(targetId);
+    }
+}
+/** A file's size and SHA-256, read in chunks without following a link. */
+/** Hash a regular file in chunks, never through a link. */
+export async function hashFileNoFollow(io, path, targetId) {
+    const hasher = createSha256();
+    let bytes = 0;
+    for await (const chunk of readChunksNoFollow(io, path, targetId)) {
+        hasher.update(chunk);
+        bytes += chunk.byteLength;
+    }
+    return { bytes, sha256: hasher.digestHex() };
+}
+/** What a copy must match: a mismatch publishes nothing. */
+/** The refusal for a copied file that does not match what was recorded. */
+export function backupCopyMismatch(targetId) {
+    return new CapabilityError("A backup file does not match its recorded size or hash.", "INTERNAL", {
+        reason: "backup-file-corrupt",
+        retryable: false,
+        details: { targetId },
+    });
+}
+/**
+ * Copy a regular file to `destPath` (owner-only, its directory created) in
+ * chunks, never through a link, hashing as it goes. The destination appears
+ * only once every byte is written and every check passed (the stream write's
+ * temporary file is renamed into place); a refusal leaves nothing there.
+ */
+export async function copyFileNoFollow(io, sourcePath, destPath, targetId, expect) {
+    await io.fs.mkdir(io.path.dirname(destPath), { recursive: true, mode: 0o700 });
+    const hasher = createSha256();
+    let bytes = 0;
+    let sha256 = "";
+    const chunks = readChunksNoFollow(io, sourcePath, targetId);
+    const source = new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await chunks.next();
+                if (next.done) {
+                    sha256 = hasher.digestHex();
+                    if (expect && (bytes !== expect.bytes || (expect.sha256 !== undefined && sha256 !== expect.sha256))) {
+                        controller.error(backupCopyMismatch(targetId));
+                        return;
+                    }
+                    controller.close();
+                    return;
+                }
+                hasher.update(next.value);
+                bytes += next.value.byteLength;
+                controller.enqueue(next.value);
+            }
+            catch (error) {
+                controller.error(CaughtFailureSchema.parse(error));
+            }
+        },
+        async cancel() {
+            await chunks.return(undefined);
+        },
+    });
+    await writeFileStream(io.fs, destPath, source, { mode: BACKUP_FILE_MODE });
+    return { bytes, sha256 };
+}
+//# sourceMappingURL=io.js.map

package/dist/backup/core/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../../src/backup/core/io.ts"],"names":[],"mappings":"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"}

package/dist/backup/core/paths.d.ts

@@ -0,0 +1,50 @@
+import type { ResolvedTargetPaths } from '../schemas/core.ts';
+export type { ResolvedTargetPaths } from '../schemas/core.ts';
+/**
+ * Path interpolation + destination resolution for backup targets.
+ *
+ * Every root comes from the runtime the caller was handed; nothing reads the
+ * process home or the environment, and no agent is guessed.
+ *
+ * Source and destination paths support:
+ *  - absolute paths
+ *  - `{vibesHome}/...` — the runtime's Vibes home (`paths/roots`)
+ *  - `~/...` and `{userHome}/...` — the runtime's user home (`paths/roots`)
+ *  - `{agentId}` — the agent the invocation acts as (`agent/identity`). A
+ *    target that names it on an invocation with no agent fails with the
+ *    context's typed `AUTH_REQUIRED` error instead of backing up someone
+ *    else's state.
+ *  - `{agentHome}` — the agent home a per-home target is running for
+ *    (`source.agentHomes`). It is bound only by that run; elsewhere (e.g. a
+ *    status listing) it stays literal, and resolving a target's paths without
+ *    it refuses `backup-agent-home-unbound`.
+ *
+ * Destinations default to `{vibesHome}/backups/{targetId}/`, and to
+ * `{vibesHome}/backups/{targetId}/<ownerType>/<ownerId>/<agentId>/` for a
+ * per-home run, so each home keeps its own snapshots.
+ */
+import { type VibesRuntime } from "@vibesdotdev/kernel";
+import { getPathRoots } from "@vibesdotdev/paths";
+import { backupFileSystemOf, type BackupPathOps } from "./io.ts";
+import type { BackupTargetDescriptor } from "../schemas/target.ts";
+import type { BackupAgentHome } from "./homes.ts";
+/** The runtime a backup path resolves on: its path roots, path mechanics and its invocation's agent. */
+export type BackupPathRuntime = Parameters<typeof getPathRoots>[0] & Parameters<typeof backupFileSystemOf>[0] & Pick<VibesRuntime, "context">;
+export interface BackupPathRoots {
+    userHome: string;
+    vibesHome: string;
+    /** The host path mechanics (the filesystem adapter's). */
+    path: BackupPathOps;
+    /** Resolved only when a path names `{agentId}`. */
+    agentId: () => Promise<string>;
+    /** The agent home a per-home run is bound to; `{agentHome}` stays literal without one. */
+    agentHome?: BackupAgentHome;
+}
+export declare function backupPathRoots(runtime: BackupPathRuntime): Promise<BackupPathRoots>;
+export declare function expandPath(input: string, roots: BackupPathRoots): Promise<string>;
+export declare function resolveDestinationDir(targetId: string, overrideDir: string | undefined, roots: BackupPathRoots): Promise<string>;
+/** A target's resolved source file and destination directory. */
+export declare function resolveTargetPaths(target: BackupTargetDescriptor, roots: BackupPathRoots): Promise<ResolvedTargetPaths>;
+/** Where one source file lands in a run: `<destDir>/<name>.<timestamp>`. */
+export declare function snapshotPathFor(path: Pick<BackupPathOps, "join" | "basename">, destDir: string, sourceName: string, timestamp: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/backup/core/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/backup/core/paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAEjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wGAAwG;AACxG,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,GAChE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,GACxC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AAEhC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,IAAI,EAAE,aAAa,CAAC;IACpB,mDAAmD;IACnD,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,0FAA0F;IAC1F,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAa1F;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAWvF;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,iEAAiE;AAGjE,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,mBAAmB,CAAC,CAY9B;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAAC,EAC9C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAGR"}

package/dist/backup/core/paths.js

@@ -0,0 +1,75 @@
+/**
+ * Path interpolation + destination resolution for backup targets.
+ *
+ * Every root comes from the runtime the caller was handed; nothing reads the
+ * process home or the environment, and no agent is guessed.
+ *
+ * Source and destination paths support:
+ *  - absolute paths
+ *  - `{vibesHome}/...` — the runtime's Vibes home (`paths/roots`)
+ *  - `~/...` and `{userHome}/...` — the runtime's user home (`paths/roots`)
+ *  - `{agentId}` — the agent the invocation acts as (`agent/identity`). A
+ *    target that names it on an invocation with no agent fails with the
+ *    context's typed `AUTH_REQUIRED` error instead of backing up someone
+ *    else's state.
+ *  - `{agentHome}` — the agent home a per-home target is running for
+ *    (`source.agentHomes`). It is bound only by that run; elsewhere (e.g. a
+ *    status listing) it stays literal, and resolving a target's paths without
+ *    it refuses `backup-agent-home-unbound`.
+ *
+ * Destinations default to `{vibesHome}/backups/{targetId}/`, and to
+ * `{vibesHome}/backups/{targetId}/<ownerType>/<ownerId>/<agentId>/` for a
+ * per-home run, so each home keeps its own snapshots.
+ */
+import { CapabilityError } from "@vibesdotdev/kernel";
+import { AGENT_IDENTITY_CONTEXT_ID } from "@vibesdotdev/kernel/schemas/agent-identity";
+import { getPathRoots } from "@vibesdotdev/paths";
+import { backupFileSystemOf } from "./io.js";
+export async function backupPathRoots(runtime) {
+    const roots = getPathRoots(runtime);
+    const path = await backupFileSystemOf(runtime);
+    let agent;
+    return {
+        userHome: roots.userHome,
+        vibesHome: roots.vibesHome,
+        path,
+        agentId: () => (agent ??= runtime
+            .context(AGENT_IDENTITY_CONTEXT_ID)
+            .then((identity) => identity.agentId)),
+    };
+}
+export async function expandPath(input, roots) {
+    let p = input;
+    if (p.startsWith("~/"))
+        p = roots.path.join(roots.userHome, p.slice(2));
+    p = p.replace(/\{vibesHome\}/g, roots.vibesHome).replace(/\{userHome\}/g, roots.userHome);
+    if (roots.agentHome) {
+        p = p.replace(/\{agentHome\}/g, roots.agentHome.dir);
+        // A per-home run acts for that home's agent, not the invocation's.
+        p = p.replace(/\{agentId\}/g, roots.agentHome.agentId);
+    }
+    if (p.includes("{agentId}"))
+        p = p.replace(/\{agentId\}/g, await roots.agentId());
+    return p;
+}
+export async function resolveDestinationDir(targetId, overrideDir, roots) {
+    const base = overrideDir ? await expandPath(overrideDir, roots) : roots.path.join(roots.vibesHome, "backups", targetId);
+    const home = roots.agentHome;
+    return home ? roots.path.join(base, home.ownerType, home.ownerId, home.agentId) : base;
+}
+/** A target's resolved source file and destination directory. */
+export async function resolveTargetPaths(target, roots) {
+    if (target.source.path.includes("{agentHome}") && !roots.agentHome) {
+        throw new CapabilityError(`Backup target '${target.id}' runs per agent home; its paths resolve only for one home.`, "INVALID_INPUT", { reason: "backup-agent-home-unbound", details: { targetId: target.id } });
+    }
+    return {
+        sourcePath: await expandPath(target.source.path, roots),
+        destDir: await resolveDestinationDir(target.id, target.destinationDir, roots),
+    };
+}
+/** Where one source file lands in a run: `<destDir>/<name>.<timestamp>`. */
+export function snapshotPathFor(path, destDir, sourceName, timestamp) {
+    const safeTs = timestamp.replace(/[:.]/g, "-");
+    return path.join(destDir, `${path.basename(sourceName)}.${safeTs}`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/backup/core/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/backup/core/paths.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,eAAe,EAAqB,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,yBAAyB,EAAsB,MAAM,4CAA4C,CAAC;AAC3G,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAsB,MAAM,SAAS,CAAC;AAqBjE,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAA0B;IAC9D,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,KAAkC,CAAC;IACvC,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,IAAI;QACJ,OAAO,EAAE,GAAG,EAAE,CACZ,CAAC,KAAK,KAAK,OAAO;aACf,OAAO,CAAgB,yBAAyB,CAAC;aACjD,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAa,EAAE,KAAsB;IACpE,IAAI,CAAC,GAAG,KAAK,CAAC;IACd,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1F,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACrD,mEAAmE;QACnE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAClF,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAAgB,EAChB,WAA+B,EAC/B,KAAsB;IAEtB,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,UAAU,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACxH,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC;IAC7B,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACzF,CAAC;AAED,iEAAiE;AAGjE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAA8B,EAC9B,KAAsB;IAEtB,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACnE,MAAM,IAAI,eAAe,CACvB,kBAAkB,MAAM,CAAC,EAAE,6DAA6D,EACxF,eAAe,EACf,EAAE,MAAM,EAAE,2BAA2B,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,CAC1E,CAAC;IACJ,CAAC;IACD,OAAO;QACL,UAAU,EAAE,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC;QACvD,OAAO,EAAE,MAAM,qBAAqB,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,EAAE,KAAK,CAAC;KAC9E,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAC7B,IAA8C,EAC9C,OAAe,EACf,UAAkB,EAClB,SAAiB;IAEjB,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/backup/core/readiness.d.ts

@@ -0,0 +1,9 @@
+import type { RecoveryReadinessReport } from '../schemas/core.ts';
+export type { RecoveryReadinessPredicate, RecoveryReadinessReport } from '../schemas/core.ts';
+import type { JsonValue } from "@vibesdotdev/kernel/schemas/json";
+export declare function evaluateRecoveryReadiness(planInput: JsonValue, attestationInput: JsonValue, options?: {
+    now?: Date;
+    planFile?: string;
+    attestationFile?: string;
+}): RecoveryReadinessReport;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/backup/core/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../../src/backup/core/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8B,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC9F,YAAY,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAGlE,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,EACpB,gBAAgB,EAAE,SAAS,EAC3B,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GACxE,uBAAuB,CA6LzB"}

package/dist/backup/core/readiness.js

@@ -0,0 +1,104 @@
+import { RecoveryPlanDescriptorSchema, RecoveryReadinessAttestationSchema } from "../schemas/disaster-recovery.js";
+import { verifyRecoveryDrillEvidence } from "./recovery.js";
+export function evaluateRecoveryReadiness(planInput, attestationInput, options = {}) {
+    const now = options.now ?? new Date();
+    const planFile = options.planFile ?? "<plan.json>";
+    const attestationFile = options.attestationFile ?? "<attestation.json>";
+    const rerun = `vibes infra recovery readiness --plan-file ${planFile} --attestation-file ${attestationFile} --output json`;
+    const parsedPlan = RecoveryPlanDescriptorSchema.safeParse(planInput);
+    if (!parsedPlan.success) {
+        return {
+            ok: false,
+            planId: "invalid",
+            generatedAt: now.toISOString(),
+            predicates: parsedPlan.error.issues.map((issue) => ({
+                id: "valid-plan",
+                pass: false,
+                summary: `${issue.path.join(".") || "<root>"}: ${issue.message}`,
+                evidenceRefs: [],
+                action: `Fix ${planFile}, then run: ${rerun}`,
+            })),
+        };
+    }
+    const plan = parsedPlan.data;
+    const parsedAttestation = RecoveryReadinessAttestationSchema.safeParse(attestationInput);
+    if (!parsedAttestation.success) {
+        const action = `Produce a sanitized provider attestation at ${attestationFile} without reading secret values, then run: ${rerun}`;
+        const predicates = [];
+        for (const plane of plan.authorityPlanes.filter((candidate) => candidate.authority === "authoritative")) {
+            for (const id of [
+                "snapshot-present", "provider-owned", "off-account", "immutable",
+                "cross-provider", "retention", "snapshot-rpo", "checksums",
+            ]) {
+                predicates.push({
+                    id,
+                    planeId: plane.id,
+                    pass: false,
+                    summary: `Provider could not attest '${id}' for ${plane.id}.`,
+                    evidenceRefs: [],
+                    action,
+                });
+            }
+        }
+        predicates.push({
+            id: "restore-drill",
+            pass: false,
+            summary: "Provider could not attest a successful isolated restore drill.",
+            evidenceRefs: parsedAttestation.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`),
+            action: `vibes infra recovery restore-drill --plan-file ${planFile} --evidence-file <drill-evidence.json> --output json`,
+        });
+        return { ok: false, planId: plan.id, generatedAt: now.toISOString(), predicates };
+    }
+    const attestation = parsedAttestation.data;
+    const predicates = [];
+    const add = (id, pass, summary, action, planeId, evidenceRefs = []) => {
+        const predicate = { id, pass, summary, action, evidenceRefs };
+        if (planeId)
+            predicate.planeId = planeId;
+        predicates.push(predicate);
+    };
+    add("plan-identity", attestation.planId === plan.id && attestation.planVersion === plan.version, `Attestation targets ${attestation.planId}@${attestation.planVersion}; plan is ${plan.id}@${plan.version}.`, rerun);
+    const snapshots = new Map(attestation.snapshots.map((snapshot) => [snapshot.planeId, snapshot]));
+    for (const plane of plan.authorityPlanes.filter((candidate) => candidate.authority === "authoritative")) {
+        add("implemented-coverage", plane.backup.coverage.status === "implemented" ||
+            plane.backup.coverage.status === "verified" ||
+            plane.backup.coverage.status === "drill-verified", `Tracked recovery coverage is ${plane.backup.coverage.status}.`, rerun, plane.id, plane.backup.coverage.evidenceRefs);
+        const snapshot = snapshots.get(plane.id);
+        if (!snapshot) {
+            add("snapshot-present", false, "Provider did not attest a successful snapshot.", rerun, plane.id);
+            continue;
+        }
+        const refs = [snapshot.lastSuccessfulSnapshot.evidenceRef];
+        add("single-epoch-watermark", snapshot.epoch === attestation.epoch &&
+            snapshot.consistencyWatermark === attestation.consistencyWatermark &&
+            snapshot.lastSuccessfulSnapshot.manifestSha256 === attestation.manifestSha256, `Plane epoch ${snapshot.epoch} at watermark ${snapshot.consistencyWatermark}.`, rerun, plane.id, [...refs, attestation.manifestKey]);
+        add("provider-owned", snapshot.producer.provider === snapshot.sourceProvider, `Snapshot was produced by ${snapshot.producer.provider} job ${snapshot.producer.executionRef}.`, rerun, plane.id, [...refs, snapshot.producer.executionRef]);
+        add("off-account", snapshot.sourceAccountRef !== snapshot.destinationAccountRef, `${snapshot.sourceAccountRef} -> ${snapshot.destinationAccountRef}`, rerun, plane.id, refs);
+        add("immutable", snapshot.immutability.locked && new Date(snapshot.immutability.until).getTime() > now.getTime(), `Immutable lock ends ${snapshot.immutability.until}.`, rerun, plane.id, [...refs, snapshot.immutability.evidenceRef]);
+        add("cross-provider", snapshot.sourceProvider === plane.sourceProvider &&
+            snapshot.destinationProvider === plane.backup.destinationProvider &&
+            snapshot.sourceProvider !== snapshot.destinationProvider, `${snapshot.sourceProvider} -> ${snapshot.destinationProvider}`, rerun, plane.id, refs);
+        add("retention", JSON.stringify(snapshot.retention) === JSON.stringify(plane.backup.retention), "Attested retention matches the recovery plan.", rerun, plane.id, [...refs, snapshot.retentionEvidenceRef]);
+        const ageMinutes = (now.getTime() - new Date(snapshot.lastSuccessfulSnapshot.createdAt).getTime()) / 60_000;
+        add("snapshot-rpo", ageMinutes >= 0 && ageMinutes <= plane.objectives.rpoMinutes, `Latest successful snapshot is ${Math.max(0, Math.round(ageMinutes))} minute(s) old; RPO is ${plane.objectives.rpoMinutes}.`, rerun, plane.id, refs);
+        add("checksums", snapshot.lastSuccessfulSnapshot.checksumsVerified, "Snapshot manifest and artifacts passed checksum verification.", rerun, plane.id, refs);
+    }
+    if (!attestation.latestDrill) {
+        add("restore-drill", false, "No isolated restore-drill evidence is attested.", `vibes infra recovery restore-drill --plan-file ${planFile} --evidence-file <drill-evidence.json> --output json`);
+    }
+    else {
+        const verification = verifyRecoveryDrillEvidence(plan, attestation.latestDrill);
+        const ageDays = (now.getTime() - new Date(attestation.latestDrill.finishedAt).getTime()) / 86_400_000;
+        const pass = verification.ok && ageDays >= 0 && ageDays <= plan.drillPolicy.intervalDays;
+        add("restore-drill", pass, pass
+            ? `Latest isolated restore drill passed ${Math.round(ageDays)} day(s) ago.`
+            : verification.failures.join("; ") || "Restore-drill evidence is stale.", `vibes infra recovery restore-drill --plan-file ${planFile} --evidence-file <drill-evidence.json> --output json`, undefined, [attestation.latestDrill.cleanup.evidenceRef]);
+    }
+    return {
+        ok: predicates.every((predicate) => predicate.pass),
+        planId: plan.id,
+        generatedAt: now.toISOString(),
+        predicates,
+    };
+}
+//# sourceMappingURL=readiness.js.map