@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

package/dist/backup/docs/backup.disaster-recovery.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.disaster-recovery.docs.descriptor.js","sourceRoot":"","sources":["../../../src/backup/docs/backup.disaster-recovery.docs.descriptor.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0Bd,CAAC;AAEF,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,0BAA0B;IAC9B,KAAK,EAAE,6BAA6B;IACpC,OAAO,EACL,4FAA4F;IAC9F,IAAI,EAAE,EAAE,IAAI,EAAE,UAAmB,EAAE,UAAU,EAAE,KAAc,EAAE,MAAM,EAAE;IACvE,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,QAAQ,EAAE,mBAAmB,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC;IAC9D,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAU;IACpC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAU;IACxC,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/backup/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @vibesdotdev/storage/backup
+ *
+ * Snapshot infrastructure for irreplaceable agent data.
+ */
+export { default as backupPlugin } from "./backup.plugin.ts";
+export { backupKinds, backupDescriptors, backupLoaders, } from "./backup.plugin.ts";
+export { storageBackupConfigDescriptor, StorageBackupConfigSchema, STORAGE_BACKUP_CONFIG_MANIFEST_ID, } from "./config/storage.backup.config.descriptor.ts";
+export type { StorageBackupConfig } from "./config/storage.backup.config.descriptor.ts";
+export { BackupSourceKindSchema, BackupSourceSpecSchema, BackupRotationPolicySchema, BackupVerifyExpectationsSchema, BackupTargetDescriptorSchema, SnapshotStatusSchema, SnapshotFileSchema, SnapshotRecordSchema, SnapshotResultSchema, RecoveryCoverageStatusSchema, RecoveryCoverageSchema, RecoveryObjectiveSchema, RecoveryRetentionPolicySchema, RecoveryBackupModeSchema, RecoveryPlaneBackupSchema, RecoveryAuthorityPlaneSchema, RecoveryEncryptionPolicySchema, RecoveryRestoreAuthorizationSchema, RecoveryPlanDescriptorSchema, RecoveryDrillCheckSchema, RecoveryDrillPlaneResultSchema, RecoveryDrillEvidenceSchema, } from "./schemas/index.ts";
+export type { BackupSourceKind, BackupSourceSpec, BackupRotationPolicy, BackupVerifyExpectations, BackupTargetDescriptor, SnapshotStatus, SnapshotFile, SnapshotRecord, SnapshotResult, RecoveryCoverageStatus, RecoveryCoverage, RecoveryObjective, RecoveryRetentionPolicy, RecoveryBackupMode, RecoveryPlaneBackup, RecoveryAuthorityPlane, RecoveryEncryptionPolicy, RecoveryRestoreAuthorization, RecoveryPlanDescriptor, RecoveryDrillCheck, RecoveryDrillPlaneResult, RecoveryDrillEvidence, } from "./schemas/index.ts";
+export { expandPath, resolveDestinationDir, resolveTargetPaths, backupPathRoots, snapshotPathFor, backupIoOf, BACKUP_TARGET_EMPTY, BACKUP_SOURCE_SYMLINK, } from "./core/index.ts";
+export type { BackupIo } from "./core/index.ts";
+export type { BackupPathRoots, BackupPathRuntime, ResolvedTargetPaths } from "./core/index.ts";
+export { sha256OfFile } from "./core/index.ts";
+export type { RotationDecision, RunSnapshotOptions } from "./core/index.ts";
+export { planRotation, runSnapshot, listBackupTargets, verifyRecoveryDrillEvidence, evaluateRecoveryReadiness, } from "./core/index.ts";
+export type { RecoveryDrillVerification } from "./core/index.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backup/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,EACzB,iCAAiC,GAClC,MAAM,8CAA8C,CAAC;AACtD,YAAY,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AAGxF,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,8BAA8B,EAC9B,4BAA4B,EAC5B,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,uBAAuB,EACvB,6BAA6B,EAC7B,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,kCAAkC,EAClC,4BAA4B,EAC5B,wBAAwB,EACxB,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,4BAA4B,EAC5B,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,UAAU,EACV,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EACL,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/backup/index.js

@@ -0,0 +1,16 @@
+/**
+ * @vibesdotdev/storage/backup
+ *
+ * Snapshot infrastructure for irreplaceable agent data.
+ */
+// Plugin
+export { default as backupPlugin } from "./backup.plugin.js";
+export { backupKinds, backupDescriptors, backupLoaders, } from "./backup.plugin.js";
+export { storageBackupConfigDescriptor, StorageBackupConfigSchema, STORAGE_BACKUP_CONFIG_MANIFEST_ID, } from "./config/storage.backup.config.descriptor.js";
+// Schemas
+export { BackupSourceKindSchema, BackupSourceSpecSchema, BackupRotationPolicySchema, BackupVerifyExpectationsSchema, BackupTargetDescriptorSchema, SnapshotStatusSchema, SnapshotFileSchema, SnapshotRecordSchema, SnapshotResultSchema, RecoveryCoverageStatusSchema, RecoveryCoverageSchema, RecoveryObjectiveSchema, RecoveryRetentionPolicySchema, RecoveryBackupModeSchema, RecoveryPlaneBackupSchema, RecoveryAuthorityPlaneSchema, RecoveryEncryptionPolicySchema, RecoveryRestoreAuthorizationSchema, RecoveryPlanDescriptorSchema, RecoveryDrillCheckSchema, RecoveryDrillPlaneResultSchema, RecoveryDrillEvidenceSchema, } from "./schemas/index.js";
+// Core (for advanced consumers)
+export { expandPath, resolveDestinationDir, resolveTargetPaths, backupPathRoots, snapshotPathFor, backupIoOf, BACKUP_TARGET_EMPTY, BACKUP_SOURCE_SYMLINK, } from "./core/index.js";
+export { sha256OfFile } from "./core/index.js";
+export { planRotation, runSnapshot, listBackupTargets, verifyRecoveryDrillEvidence, evaluateRecoveryReadiness, } from "./core/index.js";
+//# sourceMappingURL=index.js.map

package/dist/backup/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backup/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,SAAS;AACT,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,EACzB,iCAAiC,GAClC,MAAM,8CAA8C,CAAC;AAGtD,UAAU;AACV,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,8BAA8B,EAC9B,4BAA4B,EAC5B,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,uBAAuB,EACvB,6BAA6B,EAC7B,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,kCAAkC,EAClC,4BAA4B,EAC5B,wBAAwB,EACxB,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC;AA0B5B,gCAAgC;AAChC,OAAO,EACL,UAAU,EACV,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EACL,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC"}

package/dist/backup/jobs/backup.snapshot.descriptor.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Backup Snapshot Job Descriptor
+ *
+ * Consumer-scoped and queued: it runs on the worker runtime's `backup-jobs`
+ * queue, durably, like every background job. `vibes backup now` dispatches it
+ * with runJob and waits for the result.
+ */
+export declare const backupSnapshotJobDescriptor: {
+    kind: "workers/job";
+    id: string;
+    name: string;
+    description: string;
+    queue: string;
+    dispatch: "background";
+    type: "progress";
+    retries: {
+        maxAttempts: number;
+        backoff: "exponential";
+        delay: number;
+    };
+    isolation: "inline";
+    hardware: readonly ["consumer"];
+    schemas: {
+        input: import("zod/v4").ZodObject<{
+            targetId: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+            skipHash: import("zod/v4").ZodDefault<import("zod/v4").ZodBoolean>;
+            dryRun: import("zod/v4").ZodDefault<import("zod/v4").ZodBoolean>;
+        }, import("zod/v4/core").$strip>;
+        output: import("zod/v4").ZodObject<{
+            success: import("zod/v4").ZodBoolean;
+            targetsAttempted: import("zod/v4").ZodNumber;
+            targetsSucceeded: import("zod/v4").ZodNumber;
+            targetsFailed: import("zod/v4").ZodNumber;
+            targetsEmpty: import("zod/v4").ZodDefault<import("zod/v4").ZodNumber>;
+            results: import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                targetId: import("zod/v4").ZodString;
+                snapshotId: import("zod/v4").ZodString;
+                status: import("zod/v4").ZodEnum<{
+                    success: "success";
+                    failed: "failed";
+                    pending: "pending";
+                    verified: "verified";
+                    pruned: "pruned";
+                    empty: "empty";
+                }>;
+                files: import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                    path: import("zod/v4").ZodString;
+                    bytes: import("zod/v4").ZodNumber;
+                    sha256: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+                    source: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+                }, import("zod/v4/core").$strip>>;
+                rowCount: import("zod/v4").ZodNullable<import("zod/v4").ZodNumber>;
+                durationMs: import("zod/v4").ZodNumber;
+                error: import("zod/v4").ZodNullable<import("zod/v4").ZodString>;
+                home: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+                notices: import("zod/v4").ZodDefault<import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                    preflight: import("zod/v4").ZodString;
+                    code: import("zod/v4").ZodString;
+                    reason: import("zod/v4").ZodString;
+                    message: import("zod/v4").ZodString;
+                }, import("zod/v4/core").$strip>>>;
+                failure: import("zod/v4").ZodOptional<import("zod/v4").ZodObject<{
+                    name: import("zod/v4").ZodString;
+                    code: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+                    reason: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+                }, import("zod/v4/core").$strip>>;
+            }, import("zod/v4/core").$strip>>;
+            rotation: import("zod/v4").ZodDefault<import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                targetId: import("zod/v4").ZodString;
+                home: import("zod/v4").ZodNullable<import("zod/v4").ZodString>;
+                destDir: import("zod/v4").ZodString;
+                applied: import("zod/v4").ZodBoolean;
+                kept: import("zod/v4").ZodNumber;
+                prunedSnapshots: import("zod/v4").ZodNumber;
+                pruneBytes: import("zod/v4").ZodNumber;
+                staleStaging: import("zod/v4").ZodNumber;
+                stagingBytes: import("zod/v4").ZodNumber;
+                skipped: import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                    snapshotId: import("zod/v4").ZodString;
+                    reason: import("zod/v4").ZodString;
+                }, import("zod/v4/core").$strip>>;
+                failures: import("zod/v4").ZodDefault<import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                    path: import("zod/v4").ZodString;
+                    reason: import("zod/v4").ZodString;
+                }, import("zod/v4/core").$strip>>>;
+                error: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+            }, import("zod/v4/core").$strip>>>;
+            error: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+        }, import("zod/v4/core").$strip>;
+    };
+    tags: string[];
+    enabled: true;
+};
+export default backupSnapshotJobDescriptor;
+//# sourceMappingURL=backup.snapshot.descriptor.d.ts.map

package/dist/backup/jobs/backup.snapshot.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.snapshot.descriptor.d.ts","sourceRoot":"","sources":["../../../src/backup/jobs/backup.snapshot.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyBtC,CAAC;AAEH,eAAe,2BAA2B,CAAC"}

package/dist/backup/jobs/backup.snapshot.descriptor.js

@@ -0,0 +1,33 @@
+/**
+ * Backup Snapshot Job Descriptor
+ *
+ * Consumer-scoped and queued: it runs on the worker runtime's `backup-jobs`
+ * queue, durably, like every background job. `vibes backup now` dispatches it
+ * with runJob and waits for the result.
+ */
+import { createRuntimeAsset } from "@vibesdotdev/kernel";
+import { SnapshotJobInputSchema, SnapshotJobOutputSchema, } from "./backup.snapshot.schema.js";
+export const backupSnapshotJobDescriptor = createRuntimeAsset({
+    kind: "workers/job",
+    id: "backup.snapshot",
+    name: "Backup Snapshot",
+    description: "Snapshot enabled backup/target descriptors and write provenance",
+    queue: "backup-jobs",
+    dispatch: "background",
+    type: "progress",
+    retries: {
+        maxAttempts: 2,
+        backoff: "exponential",
+        delay: 5_000,
+    },
+    isolation: "inline",
+    hardware: ["consumer"],
+    schemas: {
+        input: SnapshotJobInputSchema,
+        output: SnapshotJobOutputSchema,
+    },
+    tags: ["backup", "snapshot"],
+    enabled: true,
+});
+export default backupSnapshotJobDescriptor;
+//# sourceMappingURL=backup.snapshot.descriptor.js.map

package/dist/backup/jobs/backup.snapshot.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.snapshot.descriptor.js","sourceRoot":"","sources":["../../../src/backup/jobs/backup.snapshot.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,6BAA6B,CAAC;AAErC,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAAkB,CAAC;IAC5D,IAAI,EAAE,aAAa;IACnB,EAAE,EAAE,iBAAiB;IACrB,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,iEAAiE;IAEnE,KAAK,EAAE,aAAa;IACpB,QAAQ,EAAE,YAAqB;IAC/B,IAAI,EAAE,UAAmB;IACzB,OAAO,EAAE;QACP,WAAW,EAAE,CAAC;QACd,OAAO,EAAE,aAAsB;QAC/B,KAAK,EAAE,KAAK;KACb;IACD,SAAS,EAAE,QAAiB;IAC5B,QAAQ,EAAE,CAAC,UAAU,CAAU;IAE/B,OAAO,EAAE;QACP,KAAK,EAAE,sBAAsB;QAC7B,MAAM,EAAE,uBAAuB;KAChC;IAED,IAAI,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC5B,OAAO,EAAE,IAAI;CACd,CAAC,CAAC;AAEH,eAAe,2BAA2B,CAAC"}

package/dist/backup/jobs/backup.snapshot.impl.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Backup Snapshot Job Implementation
+ *
+ * Iterates enabled `backup/target` descriptors, runs each via the
+ * snapshot core, and persists provenance to `backup.snapshot`.
+ *
+ * Errors per-target are captured in their own provenance row — a single
+ * target failure does not abort the batch.
+ */
+import type { JobDescriptor, JobImplementation, JobExecutionContext } from "@vibesdotdev/kernel/kinds";
+import { type VibesRuntime } from "@vibesdotdev/kernel";
+import type { SnapshotJobInput, SnapshotJobOutput } from "./backup.snapshot.schema.ts";
+export declare class BackupSnapshotJob implements JobImplementation<SnapshotJobInput, SnapshotJobOutput> {
+    readonly id: string;
+    readonly descriptor: JobDescriptor;
+    readonly type: "progress";
+    readonly isolation: "inline";
+    private runtime;
+    constructor(descriptor: JobDescriptor, context: {
+        runtime: VibesRuntime;
+    });
+    handle(context: JobExecutionContext<SnapshotJobInput>): Promise<SnapshotJobOutput>;
+    /**
+     * Apply `target`'s declared rotation to one run's destination (planned only
+     * on a dry run). Its own failure is reported on its row and never stops the
+     * snapshot that follows.
+     */
+    private rotate;
+    /**
+     * Ask each of the target's `backup/preflight` ids, each within its deadline
+     * (the descriptor's `timeoutMs`, default `BACKUP_PREFLIGHT_DEFAULT_TIMEOUT_MS`).
+     * Every outcome other than a pass is a notice on this target's run, and the
+     * snapshot always runs: a typed refusal carries its code and reason; an id
+     * with no registered implementation is `backup-preflight-unavailable`; a
+     * resolution or untyped check failure is `backup-preflight-failed`; a
+     * preflight past its deadline is `TIMEOUT backup-preflight-timeout` (its
+     * signal is aborted). Never data loss over a policy read (Drew).
+     */
+    private preflight;
+    /**
+     * Ask one preflight within its deadline: `undefined` when it passed, `null`
+     * when no plugin registered it (or it is not a preflight), else what went
+     * wrong and in which phase, as a `CapabilityError` (an untyped throw is
+     * `INTERNAL untyped`, its cause kept).
+     */
+    private askPreflight;
+    /** The deadline `id`'s descriptor declares, or the default (a descriptor that cannot be read gets the default). */
+    private preflightTimeoutMs;
+    /**
+     * The runs `target` needs: one per agent home for a per-home target (or one
+     * failed run naming why no home could be listed or none was found), else a
+     * single run on this invocation.
+     */
+    private runsFor;
+    private runOnce;
+    private recordProvenance;
+}
+export default BackupSnapshotJob;
+//# sourceMappingURL=backup.snapshot.impl.d.ts.map

package/dist/backup/jobs/backup.snapshot.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.snapshot.impl.d.ts","sourceRoot":"","sources":["../../../src/backup/jobs/backup.snapshot.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAkE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxH,OAAO,KAAK,EAEV,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AAiDrC,qBAAa,iBAAkB,YAAW,iBAAiB,CACzD,gBAAgB,EAChB,iBAAiB,CAClB;IACC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IACpC,QAAQ,CAAC,SAAS,EAAG,QAAQ,CAAU;IAEvC,OAAO,CAAC,OAAO,CAAe;gBAG5B,UAAU,EAAE,aAAa,EACzB,OAAO,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE;IAO9B,MAAM,CACV,OAAO,EAAE,mBAAmB,CAAC,gBAAgB,CAAC,GAC7C,OAAO,CAAC,iBAAiB,CAAC;IA8E7B;;;;OAIG;YACW,MAAM;IAkDpB;;;;;;;;;OASG;YACW,SAAS;IAcvB;;;;;OAKG;YACW,YAAY;IAwB1B,mHAAmH;IACnH,OAAO,CAAC,kBAAkB;IAU1B;;;;OAIG;YACW,OAAO;YAsBP,OAAO;YAgDP,gBAAgB;CAmC/B;AAED,eAAe,iBAAiB,CAAC"}

package/dist/backup/jobs/backup.snapshot.impl.js

@@ -0,0 +1,393 @@
+/**
+ * Backup Snapshot Job Implementation
+ *
+ * Iterates enabled `backup/target` descriptors, runs each via the
+ * snapshot core, and persists provenance to `backup.snapshot`.
+ *
+ * Errors per-target are captured in their own provenance row — a single
+ * target failure does not abort the batch.
+ */
+import { CapabilityError, CaughtFailureSchema, settle, valueFreeFailure } from "@vibesdotdev/kernel";
+import { getLogger } from "@vibesdotdev/logging";
+import { BACKUP_PREFLIGHT_DEFAULT_TIMEOUT_MS, BACKUP_PREFLIGHT_KIND, BackupPreflightDescriptorSchema, BackupPreflightMembersSchema, } from "../kinds/backup-preflight.kind.js";
+import { listBackupTargets } from "../core/registry.js";
+import { runSnapshot } from "../core/snapshot.js";
+import { backupPathRoots, expandPath, resolveTargetPaths } from "../core/paths.js";
+import { agentHomeLabel, listBackupAgentHomes } from "../core/homes.js";
+import { backupIoOf } from "../core/io.js";
+import { BACKUP_SNAPSHOT_RECORD_ID, snapshotProvenanceStore } from "../core/restore.js";
+import { applyTargetRotation, planTargetRotation, targetRecords } from "../core/rotate.js";
+async function provenanceStore(runtime) {
+    if (!runtime.hasKind("storage/record"))
+        return null;
+    try {
+        return await snapshotProvenanceStore(runtime);
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        // Only "no provenance record registered" means no store; any other failure surfaces.
+        if (failure instanceof Error && CapabilityError.isAbsenceOf(failure, "storage/record", BACKUP_SNAPSHOT_RECORD_ID)) {
+            getLogger("backup:snapshot", runtime).debug("backup.snapshot provenance record not registered");
+            return null;
+        }
+        throw error;
+    }
+}
+export class BackupSnapshotJob {
+    id;
+    descriptor;
+    type = "progress";
+    isolation = "inline";
+    runtime;
+    constructor(descriptor, context) {
+        this.id = descriptor.id;
+        this.descriptor = descriptor;
+        this.runtime = context.runtime;
+    }
+    async handle(context) {
+        const { targetId, skipHash, dryRun } = context.data;
+        const targets = await listBackupTargets(this.runtime, { targetId });
+        if (targets.length === 0) {
+            return {
+                success: true,
+                targetsAttempted: 0,
+                targetsSucceeded: 0,
+                targetsFailed: 0,
+                targetsEmpty: 0,
+                results: [],
+                rotation: [],
+            };
+        }
+        const store = await provenanceStore(this.runtime);
+        const roots = await backupPathRoots(this.runtime);
+        const io = await backupIoOf(this.runtime);
+        const results = [];
+        // Rotation first, as its own step: a snapshot that later hangs or fails
+        // never leaves superseded snapshots or stale staging in place.
+        const rotation = [];
+        if (store) {
+            for (const target of targets) {
+                for (const run of await this.runsFor(target, roots, io)) {
+                    if (!run.refusal)
+                        rotation.push(await this.rotate(store, target, run, io, dryRun));
+                }
+            }
+        }
+        for (const target of targets) {
+            // A per-home target runs once for every agent home; any other target
+            // once, on this job's invocation. Each run gets its own result and
+            // provenance row, so one home failing never stops the others.
+            for (const run of await this.runsFor(target, roots, io)) {
+                const notices = await this.preflight(target);
+                const result = { ...(await this.runOnce(target, run, io, { skipHash, dryRun })), notices };
+                results.push(result);
+                const logger = getLogger("backup:snapshot", this.runtime);
+                const where = { targetId: target.id };
+                if (result.home)
+                    where.home = result.home;
+                if (result.status === "failed") {
+                    logger.warn("[backup:snapshot] target failed", { ...where, error: result.error, failure: result.failure });
+                }
+                if (result.status === "empty") {
+                    logger.warn("[backup:snapshot] target empty: none of its declared files exist", { ...where, reason: "backup-target-empty" });
+                }
+                for (const notice of notices) {
+                    logger.warn("[backup:snapshot] target preflight refused; the snapshot still ran", {
+                        targetId: target.id,
+                        preflight: notice.preflight,
+                        code: notice.code,
+                        reason: notice.reason,
+                    });
+                }
+                if (store && !dryRun)
+                    await this.recordProvenance(store, target, run, result);
+            }
+        }
+        const succeeded = results.filter((r) => r.status === "verified" || r.status === "success").length;
+        const failed = results.filter((r) => r.status === "failed").length;
+        const empty = results.filter((r) => r.status === "empty").length;
+        await context.events?.progress(100);
+        return {
+            success: failed === 0 && empty === 0,
+            targetsAttempted: results.length,
+            targetsSucceeded: succeeded,
+            targetsFailed: failed,
+            targetsEmpty: empty,
+            results,
+            rotation,
+        };
+    }
+    /**
+     * Apply `target`'s declared rotation to one run's destination (planned only
+     * on a dry run). Its own failure is reported on its row and never stops the
+     * snapshot that follows.
+     */
+    async rotate(store, target, run, io, dryRun) {
+        const home = run.home ? agentHomeLabel(run.home) : null;
+        const report = {
+            targetId: target.id,
+            home,
+            destDir: "",
+            applied: false,
+            kept: 0,
+            prunedSnapshots: 0,
+            pruneBytes: 0,
+            staleStaging: 0,
+            stagingBytes: 0,
+            skipped: [],
+            failures: [],
+        };
+        const rotated = await settle(async () => {
+            const { destDir } = await resolveTargetPaths(target, run.roots);
+            report.destDir = destDir;
+            const records = await targetRecords(store, target.id, home);
+            const plan = await planTargetRotation(io, { targetId: target.id, home, destDir, policy: target.rotation, records });
+            report.kept = plan.kept;
+            report.prunedSnapshots = plan.prune.length;
+            report.pruneBytes = plan.pruneBytes;
+            report.staleStaging = plan.staging.length;
+            report.stagingBytes = plan.stagingBytes;
+            report.skipped = plan.skipped;
+            if (dryRun)
+                return;
+            const outcome = await applyTargetRotation(io, store, plan);
+            report.applied = true;
+            report.prunedSnapshots = outcome.pruned.length;
+            report.failures = outcome.failures.map((entry) => ({ path: entry.path, reason: entry.failure.reason ?? entry.failure.code ?? entry.failure.name }));
+        });
+        if (!rotated.ok) {
+            // Reported on this run's row and in the log, value-free; the snapshot still runs.
+            const failure = valueFreeFailure(rotated.cause);
+            getLogger("backup:snapshot", this.runtime).warn("[backup:snapshot] rotation failed; the snapshot still runs", {
+                targetId: target.id,
+                failure,
+            });
+            report.error = failure.reason ?? failure.code ?? failure.name;
+        }
+        return report;
+    }
+    /**
+     * Ask each of the target's `backup/preflight` ids, each within its deadline
+     * (the descriptor's `timeoutMs`, default `BACKUP_PREFLIGHT_DEFAULT_TIMEOUT_MS`).
+     * Every outcome other than a pass is a notice on this target's run, and the
+     * snapshot always runs: a typed refusal carries its code and reason; an id
+     * with no registered implementation is `backup-preflight-unavailable`; a
+     * resolution or untyped check failure is `backup-preflight-failed`; a
+     * preflight past its deadline is `TIMEOUT backup-preflight-timeout` (its
+     * signal is aborted). Never data loss over a policy read (Drew).
+     */
+    async preflight(target) {
+        const notices = [];
+        for (const id of target.preflight ?? []) {
+            const outcome = await this.askPreflight(target, id);
+            if (outcome === undefined)
+                continue;
+            if (outcome === null) {
+                notices.push(preflightUnavailable(id));
+                continue;
+            }
+            notices.push(preflightNotice(id, outcome));
+        }
+        return notices;
+    }
+    /**
+     * Ask one preflight within its deadline: `undefined` when it passed, `null`
+     * when no plugin registered it (or it is not a preflight), else what went
+     * wrong and in which phase, as a `CapabilityError` (an untyped throw is
+     * `INTERNAL untyped`, its cause kept).
+     */
+    async askPreflight(target, id) {
+        const timeoutMs = this.preflightTimeoutMs(id);
+        const controller = new AbortController();
+        let check;
+        try {
+            check = await withinDeadline(this.runtime.query(BACKUP_PREFLIGHT_KIND).withId(id).resolve(), timeoutMs, controller);
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            if (failure instanceof Error && CapabilityError.isAbsenceOf(failure, BACKUP_PREFLIGHT_KIND, id))
+                return null;
+            return { phase: "resolve", error: CapabilityError.from(failure) };
+        }
+        if (!BackupPreflightMembersSchema.safeParse(check).success)
+            return null;
+        try {
+            await withinDeadline(check.check({ targetId: target.id, signal: controller.signal }), timeoutMs, controller);
+            return undefined;
+        }
+        catch (error) {
+            return { phase: "check", error: CapabilityError.from(CaughtFailureSchema.parse(error)) };
+        }
+    }
+    /** The deadline `id`'s descriptor declares, or the default (a descriptor that cannot be read gets the default). */
+    preflightTimeoutMs(id) {
+        const declared = this.runtime
+            .query(BACKUP_PREFLIGHT_KIND)
+            .withId(id)
+            .descriptors()
+            .map((descriptor) => BackupPreflightDescriptorSchema.shape.timeoutMs.safeParse(descriptor.timeoutMs))
+            .find((parsed) => parsed.success && parsed.data !== undefined);
+        return declared?.success && declared.data !== undefined ? declared.data : BACKUP_PREFLIGHT_DEFAULT_TIMEOUT_MS;
+    }
+    /**
+     * The runs `target` needs: one per agent home for a per-home target (or one
+     * failed run naming why no home could be listed or none was found), else a
+     * single run on this invocation.
+     */
+    async runsFor(target, roots, io) {
+        const perHome = target.source.agentHomes;
+        if (!perHome)
+            return [{ roots }];
+        try {
+            const root = await expandPath(perHome.root, roots);
+            const homes = await listBackupAgentHomes(io, root, perHome.marker);
+            if (homes.length === 0) {
+                return [{
+                        roots,
+                        refusal: new CapabilityError(`No agent home under ${root} holds ${perHome.marker}.`, "NOT_FOUND", { reason: "backup-agent-homes-none", details: { targetId: target.id, root, marker: perHome.marker } }),
+                    }];
+            }
+            return homes.map((home) => ({ roots: { ...roots, agentHome: home }, home }));
+        }
+        catch (error) {
+            return [{ roots, refusal: CapabilityError.from(CaughtFailureSchema.parse(error)) }];
+        }
+    }
+    async runOnce(target, run, io, options) {
+        const snapshotId = crypto.randomUUID();
+        const home = run.home ? agentHomeLabel(run.home) : undefined;
+        /** A run that failed before or around the snapshot: its own message when typed (fixed text), facts kept. */
+        const failedWith = (error) => {
+            const failed = {
+                targetId: target.id,
+                snapshotId,
+                status: "failed",
+                files: [],
+                rowCount: null,
+                durationMs: 0,
+                error: error.reason === "untyped" ? "The target could not be snapshotted." : error.message,
+                failure: valueFreeFailure(error),
+            };
+            if (home)
+                failed.home = home;
+            return failed;
+        };
+        if (run.refusal)
+            return failedWith(CapabilityError.from(run.refusal));
+        if (options.dryRun) {
+            const pending = { targetId: target.id, snapshotId, status: "pending", files: [], rowCount: null, durationMs: 0, error: null };
+            if (home)
+                pending.home = home;
+            return pending;
+        }
+        // Paths resolve on this job's runtime roots, bound to the run's home when
+        // it has one. A target this run cannot resolve (e.g. `{agentId}` with no
+        // agent) fails on its own row; the batch continues.
+        try {
+            const paths = await resolveTargetPaths(target, run.roots);
+            const result = await runSnapshot(target, {
+                snapshotId,
+                timestamp: new Date().toISOString(),
+                skipHash: options.skipHash,
+                paths,
+                io,
+            });
+            return home ? { ...result, home } : result;
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            return { ...failedWith(CapabilityError.from(failure)), failure: valueFreeFailure(failure) };
+        }
+    }
+    async recordProvenance(store, target, run, result) {
+        const finishedAt = new Date().toISOString();
+        const startedAt = new Date(Date.parse(finishedAt) - result.durationMs).toISOString();
+        const row = {
+            id: result.snapshotId,
+            targetId: target.id,
+            status: result.status,
+            startedAt,
+            finishedAt,
+            durationMs: result.durationMs,
+            sourcePath: target.source.path,
+            files: result.files,
+            rowCount: result.rowCount,
+            tablesSeen: [],
+            rotationTag: null,
+            error: result.error,
+            notes: result.notices.length > 0 ? result.notices.map((notice) => notice.reason).join(", ") : null,
+            home: run.home ? agentHomeLabel(run.home) : null,
+            createdAt: startedAt,
+        };
+        const logger = getLogger("backup:snapshot", this.runtime);
+        try {
+            await store.create(row);
+        }
+        catch (error) {
+            logger.warn("[backup:snapshot] provenance write failed; this snapshot cannot be restored by id", {
+                snapshotId: result.snapshotId,
+                error: valueFreeFailure(CaughtFailureSchema.parse(error)),
+            });
+        }
+    }
+}
+export default BackupSnapshotJob;
+/** The reason a preflight that outlived its deadline carries. */
+const PREFLIGHT_TIMEOUT_REASON = "backup-preflight-timeout";
+/**
+ * `work`, or a `TIMEOUT backup-preflight-timeout` refusal once `timeoutMs`
+ * passes (aborting `controller`, so a check that honours its signal stops).
+ * The timer is cleared either way.
+ */
+async function withinDeadline(work, timeoutMs, controller) {
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new CapabilityError("The target's preflight check did not answer within its deadline; the snapshot still ran.", "TIMEOUT", {
+                reason: PREFLIGHT_TIMEOUT_REASON,
+                retryable: true,
+                details: { timeoutMs },
+            }));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([work, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The notice for a preflight that did not pass. A typed refusal from `check`
+ * carries its code, reason and the owner's fixed message; a deadline is
+ * `TIMEOUT backup-preflight-timeout`; anything else (a resolution failure, an
+ * untyped throw) is `backup-preflight-failed` with the job's own message,
+ * never the failure's text.
+ */
+function preflightNotice(id, outcome) {
+    const { phase, error } = outcome;
+    if (error.reason === PREFLIGHT_TIMEOUT_REASON) {
+        return { preflight: id, code: error.code, reason: PREFLIGHT_TIMEOUT_REASON, message: error.message };
+    }
+    if (phase === "check" && error.reason !== "untyped") {
+        return { preflight: id, code: error.code, reason: error.reason ?? "backup-preflight-refused", message: error.message };
+    }
+    return {
+        preflight: id,
+        code: error.reason === "untyped" ? "INTERNAL" : error.code,
+        reason: "backup-preflight-failed",
+        message: phase === "resolve"
+            ? "The target's preflight check could not be resolved; the snapshot still ran."
+            : "The target's preflight check failed without a typed refusal; the snapshot still ran.",
+    };
+}
+function preflightUnavailable(id) {
+    return {
+        preflight: id,
+        code: "UNAVAILABLE",
+        reason: "backup-preflight-unavailable",
+        message: "The target names a preflight check that no plugin registered.",
+    };
+}
+//# sourceMappingURL=backup.snapshot.impl.js.map