@uns-kit/core 3.0.45 → 3.0.47

package/dist/runtime/retained-store-guide.md

@@ -1,7 +1,8 @@
 # Retained stores: opt-in same-host adoption
 
-Prepared in UNS Kit 3.0.45; npm publication and coordinated Controller/Runtime
-releases are separate steps. Existing applications do not change behavior.
+Retained-store adoption starts in UNS Kit 3.0.45. The 3.0.46 extension adds
+explicit copying between local mounts and verification of recovered stores.
+Managed activation requires coordinated Controller and Runtime releases. Existing applications do not change behavior.
 This is a filesystem capability, separate from the small JSON
 handover-state contract and MQTT output persistence. It does not change the
 default handover protocol, enable disk queues, or transfer data between hosts.
@@ -120,3 +121,44 @@ cannot be used as a complete queue restore. Restore retains store/owner/generati
 identity at the same logical root on another offline volume, and leaves an applying
 fence until complete. Known private partial staging files may be re-created only
 from the verified snapshot; differing published work is never overwritten.
+
+## Cross-mount transfer and recovery verification in 3.0.46
+
+Same-filesystem rename remains the default.
+For initial relocation to a separately mounted Runtime volume, the host may
+explicitly select `transfer: "copy-verified"`. Stop the source cleanly **before**
+reviewing this transport. Review pins content hashes, aggregate byte/file counts,
+resource identities, both installed artifacts, configuration and supervisor epoch.
+There is no automatic `EXDEV` fallback or caller-selected filesystem path.
+
+The host uses `prepareRetainedStoreMoveAsync`, `applyRetainedStoreMoveAsync` and
+`prepareRetainedStoreReturnAsync`. Bounded worker jobs perform opaque hashing and
+copying while the host event loop can serve health and recovery reads. Persist the
+complete plan before mutation and hold the existing maintenance/lifecycle fences
+through the durable outcome. Jobs have a 128MiB old-generation heap and a 300s
+bound; uncertainty always requires reconciliation of the same operation.
+
+Copy stages and fsyncs each declared resource on its receiving mount, verifies
+its exact contents and atomically publishes it. Source files remain unchanged and
+fenced; allow space for both copies. Known incomplete scratch can be resumed from
+the unchanged reviewed source. Unknown entries, links, changed source bytes and
+differing published files are preserved and refused. The existing limits remain
+32 stores, 100,000 entries, 64GiB aggregate files and 32GiB per file.
+
+Return copies the **current** stopped store back. If current work differs from
+the original, the original is first preserved as
+`.retained-original-<store UUID>-<resource ID>` beside its legacy path. The retired
+stable copy remains inert and is included by full backup; it cannot acquire a
+runtime lease. No cleanup, resource merge, conversion or cross-host transfer is
+implied. Runtime disk capacity and the application's destination acknowledgement
+semantics remain independent operational requirements.
+
+Offline restore now retains a verified local snapshot manifest. The data-only
+`verify-restored` / `verify-root` actions rehash exact declared payloads under an
+exclusive root lease before Runtime activation. A completed restore retry never
+replaces newer application data. Full RTT stage/activation/completion binds the
+verified root, signed backup digest and local manifest digest into its protected
+receipts. Missing, excluded, unfinished or altered storage cannot enable bound
+owners. After application work advances, do not activate an old snapshot: preserve
+current storage and use a fresh reviewed owner transition. Historic operation
+plans pin original physical files and are not rebased after a full restore.

package/dist/runtime/retained-store-job.d.mts

@@ -0,0 +1 @@
+export function retainedStoreJob(job: unknown, onProgress?: (id: string) => void): Promise<unknown>;

package/dist/runtime/retained-store-job.mjs

@@ -0,0 +1,28 @@
+import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";
+import { inspectRetainedCopy, applyRetainedCopy } from "./retained-store-copy.mjs";
+if (!isMainThread) {
+  const job = workerData;
+  if (job.action === "inspect") parentPort.postMessage({ done: true, result: inspectRetainedCopy(job.path, job.kind, job.limits) });
+  else if (job.action === "apply") {
+    applyRetainedCopy(job.plan, job.direction, job.limits, id => parentPort.postMessage({ progress: id }));
+    parentPort.postMessage({ done: true });
+  } else throw Error("Unknown retained storage job");
+}
+export function retainedStoreJob(job, onProgress) {
+  if (!isMainThread) throw Error("Nested retained storage job");
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(new URL(import.meta.url), { workerData: job, execArgv: [], env: { NODE_NO_WARNINGS: "1" }, resourceLimits: { maxOldGenerationSizeMb: 128 } });
+    let done = false;
+    const timer = setTimeout(() => finish(Error("Retained storage job timed out; reconcile the same operation")), 300000);
+    const finish = (error, result) => {
+      if (done) return; done = true; clearTimeout(timer);
+      void worker.terminate().finally(() => error ? reject(error) : resolve(result));
+    };
+    worker.on("message", message => {
+      if (message.progress) { try { onProgress?.(message.progress); } catch (error) { finish(error); } }
+      if (message.done) finish(undefined, message.result);
+    });
+    worker.once("error", error => finish(error));
+    worker.once("exit", () => { if (!done) finish(Error("Retained storage job exited without confirmation; reconcile the same operation")); });
+  });
+}

package/dist/runtime/retained-store-storage.d.mts

@@ -15,3 +15,10 @@ export function restoreRetained(
   afterPublish?: (id: string) => void,
 ): { state: string; stores: number };
 export function available(root: string): void;
+export function owned(path: string, directory?: boolean): import("node:fs").Stats;
+export function sha(path: string): string;
+export function sync(path: string): void;
+export function relative(path: string): boolean;
+export function checkLimit(limits: unknown): void;
+export function verifyRestoredRetained(source:string,root:string,backupDigest:string,limits:unknown):{state:string;stores:number;backupDigest:string;manifestDigest:string;root:string};
+export function verifyRetainedRecoveryRoot(root:string,backupDigest:string,manifestDigest:string,limits:unknown):{state:string;stores:number;backupDigest:string;manifestDigest:string;root:string};

package/dist/runtime/retained-store-storage.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
 export const RESTORE_FILE = "retained-store-restore.json";
+export const RESTORE_MANIFEST = "retained-store-restore-manifest.json";
 export const DECLARATION = "store-resources.json";
 export const OPERATION = "store-operation.json";
 const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -21,7 +22,7 @@ export function safePath(p) {
   if (!path.isAbsolute(p) || path.normalize(p) !== p) throw Error("Unsafe retained path");
   for (let a = p; a !== path.dirname(a); a = path.dirname(a)) if (entry(a)?.isSymbolicLink()) throw Error("Linked retained path");
 }
-function owned(p, directory = false) {
+export function owned(p, directory = false) {
   safePath(p);
   const s = entry(p);
   if (!s || s.uid !== process.getuid?.() || s.isSymbolicLink() || (directory ? !s.isDirectory() : !s.isFile() || s.nlink !== 1))
@@ -38,7 +39,7 @@ export function readJSON(p, limit = 131072) {
   if (s.size > limit) throw Error("Retained metadata limit");
   return JSON.parse(fs.readFileSync(p, "utf8"));
 }
-function sync(p) {
+export function sync(p) {
   const fd = fs.openSync(p, "r");
   try {
     fs.fsyncSync(fd);
@@ -147,7 +148,7 @@ export function runtimeLease(binding) {
     throw e;
   }
 }
-function sha(file) {
+export function sha(file) {
   const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
   const h = createHash("sha256"),
     buffer = Buffer.alloc(65536);
@@ -159,7 +160,7 @@ function sha(file) {
     fs.closeSync(fd);
   }
 }
-function relative(p) {
+export function relative(p) {
   return (
     typeof p === "string" &&
     p.length <= 4096 &&
@@ -212,7 +213,7 @@ function declaration(value, format) {
   }
   return value;
 }
-function checkLimit(limits) {
+export function checkLimit(limits) {
   if (
     limits.schemaVersion !== 1 ||
     limits.maximumStores !== 32 ||
@@ -258,7 +259,7 @@ export function captureRetained(root, destination, mode, limits) {
     }
     const names = fs.readdirSync(root).sort();
     for (const id of names) {
-      if (["retained-root-lease.sqlite", RESTORE_FILE].includes(id)) continue;
+      if (["retained-root-lease.sqlite", RESTORE_FILE,RESTORE_MANIFEST].includes(id)) continue;
       if (!uuid.test(id) || manifest.stores.length >= limits.maximumStores) throw Error("Unexpected retained root entry");
       const dir = path.join(root, id);
       privateRoot(dir);
@@ -267,30 +268,25 @@ export function captureRetained(root, destination, mode, limits) {
       if (entry(path.join(dir, OPERATION))) throw Error("Retained operation is incomplete");
       const b = binding(readJSON(path.join(dir, "store.json")), root, id);
       const d = declaration(readJSON(path.join(dir, DECLARATION)), b.format);
-      if (entry(path.join(dir, "store-returned.json"))) {
-        if (fs.readdirSync(dir).some((n) => !["store.json", DECLARATION, "store-lease.sqlite", "store-returned.json"].includes(n)))
-          throw Error("Undeclared returned-store entry");
+      const retired = !!entry(path.join(dir, "store-returned.json"));
+      if (retired) {
         const r = readJSON(path.join(dir, "store-returned.json"));
-        if (r.operationId !== b.operationId || r.generation !== b.generation || d.resources.some((x) => entry(path.join(dir, x.id))))
+        if (r.operationId !== b.operationId || r.generation !== b.generation)
           throw Error("Uncertain returned store");
-        fs.mkdirSync(path.join(destination, id), { mode: 0o700 });
-        manifest.entries.push({ path: id, type: "directory" });
-        for (const name of ["store.json", DECLARATION, "store-returned.json"]) copy(path.join(dir, name), id + "/" + name);
-        manifest.stores.push({ binding: b, storeId: id, generation: b.generation, owner: b.owner, format: b.format, resources: [], retired: true });
-        continue;
       }
-      const allowed = new Set(["store.json", DECLARATION, "store-lease.sqlite", ...d.resources.map((x) => x.id)]);
+      const allowed = new Set(["store.json", DECLARATION, "store-lease.sqlite", ...(retired?["store-returned.json"]:[]), ...d.resources.map((x) => x.id)]);
       if (fs.readdirSync(dir).some((n) => !allowed.has(n))) throw Error("Undeclared retained entry");
       fs.mkdirSync(path.join(destination, id), { mode: 0o700 });
       manifest.entries.push({ path: id, type: "directory" });
       copy(path.join(dir, "store.json"), id + "/store.json");
       copy(path.join(dir, DECLARATION), id + "/" + DECLARATION);
+      if(retired)copy(path.join(dir,"store-returned.json"),id+"/store-returned.json");
       const resources = [];
       for (const r of d.resources) {
         const p = path.join(dir, r.id),
           s = entry(p);
         if (!s) {
-          if (r.required) throw Error("Required retained resource missing");
+          if (r.required && !retired) throw Error("Required retained resource missing");
           continue;
         }
         if ((r.kind === "directory") !== s.isDirectory()) throw Error("Retained resource kind mismatch");
@@ -298,7 +294,7 @@ export function captureRetained(root, destination, mode, limits) {
         resources.push({ id: r.id, backup: r.backup ?? "payload", included });
         if (included) copy(p, id + "/" + r.id);
       }
-      manifest.stores.push({ binding: b, storeId: id, generation: b.generation, owner: b.owner, format: b.format, resources });
+      manifest.stores.push({ binding: b, storeId: id, generation: b.generation, owner: b.owner, format: b.format, resources, ...(retired?{retired:true}:{}) });
     }
     const raw = JSON.stringify(manifest);
     if (Buffer.byteLength(raw) > limits.maximumManifestBytes) throw Error("Retained manifest limit");
@@ -363,7 +359,7 @@ function verifySnapshot(source, limits) {
   if (stores.size !== m.stores.length || m.entries.some((e) => !stores.has(e.path.split("/")[0]))) throw Error("Undeclared snapshot store");
   for (const st of m.stores) {
     const b = binding(readJSON(path.join(source, st.storeId, "store.json")), m.sourceRoot, st.storeId);
-    declaration(readJSON(path.join(source, st.storeId, DECLARATION)), b.format);
+    const declared=declaration(readJSON(path.join(source, st.storeId, DECLARATION)), b.format);
     if (st.retired) {
       const r = readJSON(path.join(source, st.storeId, "store-returned.json"));
       if (
@@ -371,7 +367,7 @@ function verifySnapshot(source, limits) {
         r.generation !== b.generation ||
         m.entries.some(
           (e) =>
-            e.path.startsWith(st.storeId + "/") && !["store.json", DECLARATION, "store-returned.json"].includes(e.path.slice(st.storeId.length + 1)),
+            e.path.startsWith(st.storeId + "/") && !["store.json", DECLARATION, "store-returned.json",...declared.resources.map(r=>r.id)].includes(e.path.slice(st.storeId.length + 1).split("/")[0]),
         )
       )
         throw Error("Invalid retired-store receipt");
@@ -397,6 +393,7 @@ export function restoreRetained(source, root, backupDigest, limits, afterPublish
     if (new Set(ids).size !== ids.length || ids.some((id) => !uuid.test(id))) throw Error("Invalid snapshot store identities");
     if (marker?.state === "complete") {
       for (const id of ids) binding(readJSON(path.join(root, id, "store.json")), root, id);
+      persistRecoveryManifest(source,root,manifestDigest);
       return { state: "complete", stores: ids.length };
     }
     if (!marker) {
@@ -404,10 +401,11 @@ export function restoreRetained(source, root, backupDigest, limits, afterPublish
       marker = { protocol: 1, state: "applying", backupDigest, manifestDigest };
       atomicJSON(markerFile, marker);
     }
+    persistRecoveryManifest(source,root,manifestDigest);
     const stage = path.join(root, "retained-restore-stage");
     if (!entry(stage)) fs.mkdirSync(stage, { mode: 0o700 });
     privateRoot(stage);
-    const allowed = new Set(["retained-root-lease.sqlite", RESTORE_FILE, "retained-restore-stage", ...ids]);
+    const allowed = new Set(["retained-root-lease.sqlite", RESTORE_FILE,RESTORE_MANIFEST, "retained-restore-stage", ...ids]);
     if (fs.readdirSync(root).some((n) => !allowed.has(n))) throw Error("Unexpected restore target entry");
     for (const e of m.entries) {
       const id = e.path.split("/")[0],
@@ -486,8 +484,55 @@ export function retainedStorageMain() {
       ? captureRetained(root, out, modeOrDigest, limits)
       : action === "restore"
         ? restoreRetained(root, out, modeOrDigest, limits)
+        : action === "verify-restored"
+          ? verifyRestoredRetained(root,out,modeOrDigest,limits)
+          : action === "verify-root"
+            ? verifyRetainedRecoveryRoot(root,modeOrDigest,out,limits)
         : (() => {
             throw Error("Unknown retained operation");
           })();
   process.stdout.write(JSON.stringify(result));
 }
+
+/** Offline proof tied to one verified backup, used before an RTT tree can activate. */
+export function verifyRestoredRetained(source,root,backupDigest,limits){
+  checkLimit(limits);
+  const m=verifySnapshot(source,limits);
+  if(m.mode!=="include"||m.sourceRoot!==root||!hash.test(backupDigest))throw Error("Retained recovery scope differs");
+  return verifyRetainedRecoveryRoot(root,backupDigest,sha(path.join(source,"manifest.json")),limits);
+}
+function persistRecoveryManifest(source,root,digest){
+  const target=path.join(root,RESTORE_MANIFEST);
+  const temporary=target+".part";
+  if(entry(temporary)){owned(temporary);fs.unlinkSync(temporary);sync(root);}
+  if(entry(target)){if(sha(target)!==digest)throw Error("Retained recovery manifest differs");return;}
+  try{fs.copyFileSync(path.join(source,"manifest.json"),temporary,fs.constants.COPYFILE_EXCL);fs.chmodSync(temporary,0o600);sync(temporary);if(sha(temporary)!==digest)throw Error("Retained recovery manifest changed");fs.renameSync(temporary,target);sync(root);}finally{if(entry(temporary))fs.unlinkSync(temporary);}
+}
+export function verifyRetainedRecoveryRoot(root,backupDigest,digest,limits){
+  checkLimit(limits);
+  if(!hash.test(backupDigest)||!hash.test(digest))throw Error("Invalid retained recovery proof");
+  const release=rootLease(root,true,true);
+  try{
+    const marker=readJSON(path.join(root,RESTORE_FILE));
+    if(marker.state!=="complete"||marker.backupDigest!==backupDigest||marker.manifestDigest!==digest)throw Error("Matching completed retained recovery is required");
+    const file=path.join(root,RESTORE_MANIFEST);
+    if(sha(file)!==digest)throw Error("Retained recovery manifest differs");
+    const m=readJSON(file,limits.maximumManifestBytes);
+    if(m.schemaVersion!==1||m.kind!=="uns-retained-store-snapshot"||m.mode!=="include"||m.sourceRoot!==root||!Array.isArray(m.stores)||m.stores.length>limits.maximumStores||!Array.isArray(m.entries)||m.entries.length>limits.maximumEntries)throw Error("Invalid retained recovery manifest");
+    const ids=m.stores.map(s=>s.storeId);
+    if(new Set(ids).size!==ids.length||ids.some(id=>!uuid.test(id)))throw Error("Invalid recovered stores");
+    if(fs.readdirSync(root).some(n=>!["retained-root-lease.sqlite",RESTORE_FILE,RESTORE_MANIFEST,...ids].includes(n)))throw Error("Unexpected retained recovery root entry");
+    const seen=new Set();let total=0;
+    for(const e of m.entries){
+      if(!relative(e.path)||!ids.includes(e.path.split('/')[0])||seen.has(e.path)||!["file","directory"].includes(e.type))throw Error("Invalid retained recovery path");seen.add(e.path);
+      const p=path.join(root,e.path),s=owned(p,e.type==="directory");
+      if(e.type==="file"){total+=s.size;if(total>limits.maximumBytes||s.size>limits.maximumFileBytes||s.size!==e.size||sha(p)!==e.sha256)throw Error("Restored retained payload changed before activation");}
+    }
+    for(const id of ids){
+      const prefix=id+"/",dir=path.join(root,id),allowed=new Set(m.entries.filter(e=>e.path.startsWith(prefix)).map(e=>e.path.slice(prefix.length)));
+      if(entry(path.join(dir,"store-lease.sqlite"))){owned(path.join(dir,"store-lease.sqlite"));allowed.add("store-lease.sqlite");}
+      exactTree(dir,allowed);
+    }
+    return{state:"verified",stores:ids.length,backupDigest,manifestDigest:digest,root};
+  }finally{release();}
+}

package/dist/runtime/retained-store.d.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import { z } from "zod";
+import { type RetainedCopyFingerprint } from "./retained-store-copy.mjs";
 export declare const RETAINED_STORE_MANIFEST = "retained-store.manifest.json";
 export declare const RETAINED_STORE_BINDING = "retained-store-binding.json";
 export declare const RETAINED_STORE_GUARD = "retained-store-guard.json";
@@ -45,6 +46,7 @@ export type ResourceMove = {
     kind: "file" | "directory";
     device: number;
     inode: number;
+    content?: RetainedCopyFingerprint;
 };
 export type StoreMovePlan = {
     storeId: string;
@@ -54,6 +56,8 @@ export type StoreMovePlan = {
     directory: string;
     slots: RetainedStoreManifest["resources"];
     moves: ResourceMove[];
+    transfer?: "copy-verified";
+    originalMoves?: ResourceMove[];
 };
 export declare function retainedStoreDigest(value: unknown): string;
 export declare function retainedStoreEntry(file: string): fs.Stats | undefined;
@@ -62,10 +66,10 @@ export declare function readRetainedStoreJson(file: string): unknown;
 export declare function syncRetainedDirectory(directory: string): void;
 export declare function writeRetainedStoreJson(file: string, value: unknown): void;
 export declare function readRetainedStoreManifest(packageDirectory: string): RetainedStoreManifest;
-export declare function prepareRetainedStoreMove(source: string, root: string, storeId: string, manifest: RetainedStoreManifest): StoreMovePlan;
+export declare function prepareRetainedStoreMove(source: string, root: string, storeId: string, manifest: RetainedStoreManifest, transfer?: "copy-verified", deferContent?: boolean): StoreMovePlan;
 /** Caller durably records the complete plan and holds its resource reservation first.
  * Each rename is atomic; the multi-resource operation is deliberately resumable. */
-export declare function applyRetainedStoreMove(plan: StoreMovePlan, direction: "adopt" | "return", afterMove?: (id: string) => void): void;
+export declare function applyRetainedStoreMove(plan: StoreMovePlan, direction: "adopt" | "return", afterMove?: (id: string) => void, onFile?: (file: string) => void, validateOnly?: boolean): void;
 export declare function writeRetainedStoreBinding(instanceDirectory: string, binding: StoreBinding): void;
 export declare function loadRetainedStoreBinding(instanceDirectory: string, operationId?: string): StoreBinding | undefined;
 /** No application payload/schema inspection is performed by this helper. */
@@ -80,6 +84,7 @@ export declare const retainedStoreSelectionSchema: z.ZodObject<{
     sourceInstanceId: z.ZodString;
     targetVersion: z.ZodString;
     targetInstanceId: z.ZodString;
+    transfer: z.ZodOptional<z.ZodLiteral<"copy-verified">>;
 }, z.core.$strict>;
 export declare const retainedStoreRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"review">;
@@ -90,6 +95,7 @@ export declare const retainedStoreRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
         sourceInstanceId: z.ZodString;
         targetVersion: z.ZodString;
         targetInstanceId: z.ZodString;
+        transfer: z.ZodOptional<z.ZodLiteral<"copy-verified">>;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     action: z.ZodLiteral<"get">;
@@ -104,12 +110,15 @@ export declare const retainedStoreRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
 }, z.core.$strict>], "action">;
 export type RetainedStoreRequest = z.infer<typeof retainedStoreRequestSchema>;
 /** Capture mutable control files from the current stopped owner before persisting return intent. */
-export declare function prepareRetainedStoreReturn(plan: StoreMovePlan): StoreMovePlan;
+export declare function prepareRetainedStoreReturn(plan: StoreMovePlan, deferContent?: boolean): StoreMovePlan;
 export declare function retainedStoreRoot(defaultBase: string, configured?: string): string;
 export declare function openRetainedStoreLease(binding: StoreBinding): {
     close: () => void;
 };
 export declare function openRetainedStoreMaintenance(directory: string): () => void;
+export declare function prepareRetainedStoreMoveAsync(source: string, root: string, id: string, manifest: RetainedStoreManifest, transfer?: "copy-verified"): Promise<StoreMovePlan>;
+export declare function prepareRetainedStoreReturnAsync(plan: StoreMovePlan): Promise<StoreMovePlan>;
+export declare function applyRetainedStoreMoveAsync(plan: StoreMovePlan, direction: "adopt" | "return", afterMove?: (id: string) => void): Promise<void>;
 export declare const retainedStoreBackupSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     state: z.ZodEnum<{

package/dist/runtime/retained-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retained-store.d.ts","sourceRoot":"","sources":["../../src/runtime/retained-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"retained-store.d.ts","sourceRoot":"","sources":["../../src/runtime/retained-store.ts"],"names":[],"mappings":"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"}

package/dist/runtime/retained-store.js

@@ -3,6 +3,9 @@ import * as fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { available, maintenanceLease, runtimeLease } from "./retained-store-storage.mjs";
+import { inspectRetainedCopy, applyRetainedCopy } from "./retained-store-copy.mjs";
+import { retainedStoreJob } from "./retained-store-job.mjs";
+const copyLimits = () => JSON.parse(fs.readFileSync(new URL("./retained-store-storage-contract.json", import.meta.url), "utf8"));
 const segment = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/);
 const relative = z
     .string()
@@ -137,7 +140,7 @@ export function writeRetainedStoreJson(file, value) {
 export function readRetainedStoreManifest(packageDirectory) {
     return retainedStoreManifestSchema.parse(readRetainedStoreJson(path.join(packageDirectory, RETAINED_STORE_MANIFEST)));
 }
-export function prepareRetainedStoreMove(source, root, storeId, manifest) {
+export function prepareRetainedStoreMove(source, root, storeId, manifest, transfer, deferContent = false) {
     z.uuid().parse(storeId);
     retainedStoreManifestSchema.parse(manifest);
     assertRetainedStorePath(source);
@@ -151,8 +154,10 @@ export function prepareRetainedStoreMove(source, root, storeId, manifest) {
     const rootStat = existingRoot ?? fs.statSync(path.dirname(root)), sourceStat = fs.statSync(source);
     if (root === source || root.startsWith(source + path.sep) || source.startsWith(root + path.sep))
         throw Error("Nested retained store roots");
-    if (rootStat.dev !== sourceStat.dev)
-        throw Error("Retained store requires same filesystem; copy is not permitted");
+    if (transfer !== undefined && transfer !== "copy-verified")
+        throw Error("Unsupported retained transfer");
+    if (!transfer && rootStat.dev !== sourceStat.dev)
+        throw Error("Retained store requires same filesystem; review an explicit verified copy");
     const moves = [];
     for (const resource of manifest.resources) {
         const file = path.join(source, resource.path);
@@ -164,13 +169,16 @@ export function prepareRetainedStoreMove(source, root, storeId, manifest) {
             continue;
         }
         if (s.uid !== process.getuid?.() ||
-            s.dev !== rootStat.dev ||
+            (!transfer && s.dev !== rootStat.dev) ||
             s.isSymbolicLink() ||
             (resource.kind === "file" ? !s.isFile() || s.nlink !== 1 : !s.isDirectory()))
             throw Error("Unsafe retained resource");
-        moves.push({ id: resource.id, relative: resource.path, kind: resource.kind, device: s.dev, inode: s.ino });
+        moves.push({ id: resource.id, relative: resource.path, kind: resource.kind, device: s.dev, inode: s.ino,
+            ...(transfer && !deferContent ? { content: inspectRetainedCopy(file, resource.kind, copyLimits()) } : {}) });
     }
-    return { storeId, generation: randomUUID(), format: manifest.format, source, directory, slots: manifest.resources, moves };
+    if (transfer && (moves.reduce((n, m) => n + (m.content?.bytes ?? 0), 0) > copyLimits().maximumBytes || moves.reduce((n, m) => n + (m.content?.entries ?? 0), 0) > copyLimits().maximumEntries))
+        throw Error("Retained copy aggregate limit");
+    return { storeId, generation: randomUUID(), format: manifest.format, source, directory, slots: manifest.resources, moves, ...(transfer ? { transfer } : {}) };
 }
 function matches(file, move) {
     assertRetainedStorePath(file);
@@ -184,7 +192,8 @@ function matches(file, move) {
 }
 /** Caller durably records the complete plan and holds its resource reservation first.
  * Each rename is atomic; the multi-resource operation is deliberately resumable. */
-export function applyRetainedStoreMove(plan, direction, afterMove) {
+export function applyRetainedStoreMove(plan, direction, afterMove, onFile, validateOnly = false) {
+    const resourceMove = z.object({ id: segment, relative, kind: z.enum(["file", "directory"]), device: z.number().int().nonnegative(), inode: z.number().int().nonnegative(), content: z.object({ digest: z.string().regex(/^[a-f0-9]{64}$/), bytes: z.number().int().nonnegative().max(copyLimits().maximumBytes), entries: z.number().int().positive().max(copyLimits().maximumEntries) }).strict().optional() }).strict();
     z.object({
         storeId: z.uuid(),
         generation: z.uuid(),
@@ -202,17 +211,9 @@ export function applyRetainedStoreMove(plan, direction, afterMove) {
         })
             .strict())
             .max(16),
-        moves: z
-            .array(z
-            .object({
-            id: segment,
-            relative,
-            kind: z.enum(["file", "directory"]),
-            device: z.number().int().nonnegative(),
-            inode: z.number().int().nonnegative(),
-        })
-            .strict())
-            .max(16),
+        moves: z.array(resourceMove).max(16),
+        transfer: z.literal("copy-verified").optional(),
+        originalMoves: z.array(resourceMove).max(16).optional(),
     })
         .strict()
         .parse(plan);
@@ -234,6 +235,20 @@ export function applyRetainedStoreMove(plan, direction, afterMove) {
     const directoryStat = fs.lstatSync(plan.directory);
     if (!directoryStat.isDirectory() || directoryStat.uid !== process.getuid?.() || directoryStat.mode & 0o077)
         throw Error("Unsafe retained store directory");
+    if (plan.transfer) {
+        if (plan.moves.some(m => !m.content) || plan.originalMoves?.some(m => !m.content))
+            throw Error("Verified copy requires reviewed content fingerprints");
+        for (const entries of [plan.moves, plan.originalMoves ?? []])
+            if (entries.reduce((n, m) => n + (m.content?.bytes ?? 0), 0) > copyLimits().maximumBytes || entries.reduce((n, m) => n + (m.content?.entries ?? 0), 0) > copyLimits().maximumEntries)
+                throw Error("Retained copy aggregate limit");
+        if ((plan.originalMoves ?? []).some(m => !manifest.resources.some(r => r.id === m.id && r.path === m.relative && r.kind === m.kind)))
+            throw Error("Original copy differs from declared resources");
+        if (!validateOnly)
+            applyRetainedCopy(plan, direction, copyLimits(), afterMove, onFile);
+        return;
+    }
+    if (plan.originalMoves)
+        throw Error("Original copy receipt requires verified transfer");
     for (const move of plan.moves) {
         const legacy = path.join(plan.source, move.relative), stable = path.join(plan.directory, move.id);
         const [from, to] = direction === "adopt" ? [legacy, stable] : [stable, legacy];
@@ -314,6 +329,7 @@ export const retainedStoreSelectionSchema = z
     sourceInstanceId: segment,
     targetVersion: segment,
     targetInstanceId: segment,
+    transfer: z.literal("copy-verified").optional(),
 })
     .strict()
     .refine((x) => x.sourceVersion !== x.targetVersion || x.sourceInstanceId !== x.targetInstanceId, "Source and target must differ");
@@ -323,8 +339,25 @@ export const retainedStoreRequestSchema = z.discriminatedUnion("action", [
     z.object({ action: z.enum(["adopt", "return"]), id: z.uuid(), reviewedChecksum: z.string().regex(/^[a-f0-9]{64}$/) }).strict(),
 ]);
 /** Capture mutable control files from the current stopped owner before persisting return intent. */
-export function prepareRetainedStoreReturn(plan) {
+export function prepareRetainedStoreReturn(plan, deferContent = false) {
     const moves = [];
+    if (plan.transfer) {
+        for (const slot of plan.slots) {
+            const stable = path.join(plan.directory, slot.id), legacy = path.join(plan.source, slot.path), a = retainedStoreEntry(stable), b = retainedStoreEntry(legacy);
+            if (a) {
+                assertRetainedStorePath(stable);
+                moves.push({ id: slot.id, relative: slot.path, kind: slot.kind, device: a.dev, inode: a.ino, ...(!deferContent ? { content: inspectRetainedCopy(stable, slot.kind, copyLimits()) } : {}) });
+            }
+            else if (b) {
+                const original = plan.moves.find(m => m.id === slot.id);
+                if (!original || !matches(legacy, original) || (!deferContent && retainedStoreDigest(inspectRetainedCopy(legacy, slot.kind, copyLimits())) !== retainedStoreDigest(original.content)))
+                    throw Error("Original retained copy changed");
+            }
+            else if (slot.required)
+                throw Error("Current retained resource missing");
+        }
+        return { ...plan, moves, originalMoves: plan.moves };
+    }
     for (const slot of plan.slots) {
         const stable = path.join(plan.directory, slot.id), legacy = path.join(plan.source, slot.path);
         assertRetainedStorePath(stable);
@@ -359,6 +392,28 @@ export function openRetainedStoreLease(binding) {
 export function openRetainedStoreMaintenance(directory) {
     return maintenanceLease(directory);
 }
+export async function prepareRetainedStoreMoveAsync(source, root, id, manifest, transfer) {
+    const plan = prepareRetainedStoreMove(source, root, id, manifest, transfer, !!transfer);
+    if (transfer)
+        for (const move of plan.moves)
+            move.content = await retainedStoreJob({ action: "inspect", path: path.join(source, move.relative), kind: move.kind, limits: copyLimits() });
+    return plan;
+}
+export async function prepareRetainedStoreReturnAsync(plan) {
+    const back = prepareRetainedStoreReturn(plan, !!plan.transfer);
+    if (plan.transfer)
+        for (const move of back.moves)
+            move.content = await retainedStoreJob({ action: "inspect", path: path.join(plan.directory, move.id), kind: move.kind, limits: copyLimits() });
+    return back;
+}
+export async function applyRetainedStoreMoveAsync(plan, direction, afterMove) {
+    if (!plan.transfer) {
+        applyRetainedStoreMove(plan, direction, afterMove);
+        return;
+    }
+    applyRetainedStoreMove(plan, direction, undefined, undefined, true);
+    await retainedStoreJob({ action: "apply", plan, direction, limits: copyLimits() }, afterMove);
+}
 export const retainedStoreBackupSchema = z
     .object({
     schemaVersion: z.literal(1),