@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/dist/services/memory-repair-physical-binding.js

@@ -0,0 +1,194 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { hookSessionIdentity } from "./hooks.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { parseLifecycleCommand, commandPosition } from "./lifecycle-command.js";
+import { resolveWorkReference } from "../storage/work-references.js";
+import { currentLifecycleAdmission } from "./lifecycle-invocations.js";
+import { recoveryGuard } from "./run-recovery-guard.js";
+const event = "memory.repair_native_binding";
+function refuse(reason) {
+    throw new AppError("memory_repair_native_binding_invalid", "Native repair requires its actual direct-child Hook and independently owned copy", 1, { reason, effect: "no_effect" });
+}
+/** Preserve raw Hook CWD. A scoped literal shell route becomes physical
+ * execution proof only after the CLI independently admitted process.cwd. */
+export function memoryRepairExecutionIdentity(context, input) {
+    const reader = { ...context };
+    delete reader.observeLifecycleHook;
+    const identity = hookSessionIdentity(reader, input.projectId, input.eventKey);
+    if (identity.cwd === input.root)
+        return { identity, invocationId: null };
+    const rows = context.db.all("SELECT id,status,command,scope_json,identity_json FROM lifecycle_invocations WHERE event_key=? AND status IN ('executing','settled') LIMIT 2", [input.eventKey]);
+    if (rows.length !== 1)
+        refuse("repair_execution_cwd_unproven");
+    const row = rows[0];
+    try {
+        if ([row.command, row.scope_json, row.identity_json].some(value => typeof value !== "string" || Buffer.byteLength(value) > 1024 * 1024))
+            refuse("repair_execution_cwd_unproven");
+        const scope = JSON.parse(row.scope_json), native = JSON.parse(row.identity_json), parsed = parseLifecycleCommand(row.command);
+        const project = context.db.get("SELECT root FROM projects WHERE id=?", [input.projectId]);
+        const parent = context.db.get("SELECT provider_session_id FROM sessions WHERE project_id=? AND session_id=? AND run_id=?", [input.projectId, identity.parentSessionId, input.runId]);
+        if (parsed.kind === "none" || parsed.supported === false || parsed.invocation.operation !== "work_start"
+            || scope.runId !== input.runId || scope.projectRoot !== project?.root || !Array.isArray(native) || native.length !== 6
+            || native[0] !== identity.daemonId || scope.daemonId !== identity.daemonId || native[1] !== scope.rootSessionId
+            || !parent || native[3] !== parent.provider_session_id || typeof native[4] !== "string" || !native[4]
+            || native[2] !== identity.providerSessionId || native[5]?.executionCwd !== input.root)
+            refuse("repair_execution_cwd_unproven");
+        const target = resolveWorkReference(context, commandPosition(parsed.invocation, 0), { projectId: input.projectId });
+        if (target.work_id !== input.workId)
+            refuse("repair_execution_cwd_unproven");
+        const retained = context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id JOIN hook_events he ON he.project_id=w.project_id AND he.event_key=ws.hook_event_id WHERE w.project_id=? AND w.run_id=? AND w.work_id=? AND ws.hook_event_id=? AND ws.session_id=? AND he.status='claimed' AND EXISTS (SELECT 1 FROM audit_events a WHERE a.project_id=w.project_id AND a.event_type IN ('memory.repair_work_start','memory.native_review_binding') AND json_extract(a.payload_json,'$.run_id')=w.run_id AND json_extract(a.payload_json,'$.work_id')=w.work_id AND json_extract(a.payload_json,'$.work_session_id')=ws.id AND (a.event_type='memory.repair_work_start' OR json_extract(a.payload_json,'$.invocation_id')=?))", [input.projectId, input.runId, input.workId, input.eventKey, identity.sessionId, row.id]);
+        if (!currentLifecycleAdmission(context, row.id) && !retained)
+            refuse("repair_execution_cwd_not_admitted");
+        return { identity: { ...identity, cwd: input.root }, invocationId: row.id };
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "memory_repair_native_binding_invalid")
+            throw error;
+        return refuse("repair_execution_cwd_unproven");
+    }
+}
+export { memoryRepairAssignedHookCwd } from "./hook-memory-routing.js";
+/** Native children have no external launch row. Read the immutable physical
+ * Hook and copy journal instead; preparation cannot manufacture a Session. */
+export function readMemoryRepairPhysicalBinding(context, workId, route, operationId) {
+    const external = context.db.get("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='work_launches'")
+        ? context.db.get("SELECT operation_id,status,profile_json,profile_hash,provider_session_id FROM work_launches WHERE work_id=?", [workId]) : undefined;
+    if (route.delegation.mode === "external")
+        return external;
+    if (external)
+        refuse("native_work_has_external_launch");
+    const work = context.db.get("SELECT project_id,run_id,parent_work_id FROM works WHERE work_id=?", [workId]);
+    if (!work?.parent_work_id)
+        refuse("owned_native_work_required");
+    const run = context.db.get("SELECT run_root,run_dir FROM runs WHERE project_id=? AND id=?", [work.project_id, work.run_id]);
+    if (!run)
+        refuse("owned_native_run_required");
+    const retained = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 2", [work.project_id, event, work.run_id, workId]);
+    let prior;
+    if (retained.length) {
+        try {
+            if (retained.length !== 1 || Buffer.byteLength(retained[0].payload_json) > 1024 * 1024)
+                refuse("ambiguous_native_binding");
+            prior = JSON.parse(retained[0].payload_json);
+            if (!prior || prior.schema_id !== "dd-flow/memory-repair-native-binding@1" || prior.project_id !== work.project_id
+                || prior.run_id !== work.run_id || prior.work_id !== workId || typeof prior.work_session_id !== "string"
+                || !prior.work_session_id || Object.keys(prior).sort().join(",") !== "binding,hook_event_key,parent_provider_session_id,parent_session_id,project_id,run_id,schema_id,work_id,work_session_id")
+                refuse("foreign_native_binding");
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            refuse("invalid_native_binding");
+        }
+    }
+    const key = prior?.hook_event_key ?? (operationId?.startsWith("native-hook:") ? operationId.slice(12) : context.env.DD_FLOW_MEMORY_REPAIR_HOOK_EVENT);
+    if (!key || key.length > 1024)
+        refuse("native_start_hook_required");
+    const reader = { ...context };
+    delete reader.observeLifecycleHook;
+    let identity;
+    try {
+        identity = hookSessionIdentity(reader, work.project_id, key);
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "hook_event_not_found")
+            refuse("native_start_hook_required");
+        throw error;
+    }
+    const hook = context.db.get("SELECT status,created_at FROM hook_events WHERE project_id=? AND event_key=? AND id=? AND event_name='PreToolUse'", [work.project_id, key, identity.hookEventId]);
+    const parents = context.db.all("SELECT DISTINCT s.session_id,s.harness,s.status,s.current_stage,s.run_id,s.worker_id,s.provider_session_id FROM work_sessions ws JOIN sessions s ON s.project_id=? AND s.session_id=ws.session_id WHERE ws.work_id=? AND s.session_id=? LIMIT 2", [work.project_id, work.parent_work_id, identity.parentSessionId]);
+    if (!hook || !["observed", "claimed"].includes(hook.status) || parents.length !== 1)
+        refuse("native_parent_or_hook_required");
+    const parent = parents[0];
+    if (parent.run_id !== work.run_id || !prior && parent.worker_id !== work.parent_work_id || parent.harness !== runtimeHarness(route.coordinator)
+        || identity.parentSessionId !== parent.session_id || identity.sessionId === parent.session_id
+        || identity.harness !== runtimeHarness(route.worker) || identity.model !== route.worker.model
+        || identity.provider && identity.provider !== route.worker.provider)
+        refuse("native_route_or_parent_mismatch");
+    if (context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id WHERE w.project_id=? AND w.run_id=? AND w.work_id<>? AND s.harness=? AND s.provider_session_id=? LIMIT 1", [work.project_id, work.run_id, workId, identity.harness, identity.providerSessionId]))
+        refuse("native_repair_session_not_fresh");
+    let freshnessAt = context.now();
+    const currentId = context.env.DD_FLOW_CURRENT_INVOCATION;
+    const admission = currentId ? currentLifecycleAdmission(context, currentId) : null;
+    if (admission) {
+        const project = context.db.get("SELECT root FROM projects WHERE id=?", [work.project_id]);
+        const attempt = context.db.get("SELECT event_key,scope_json,command FROM lifecycle_invocations WHERE id=?", [currentId]);
+        if (attempt?.event_key === key) {
+            const scope = JSON.parse(attempt.scope_json), parsed = parseLifecycleCommand(attempt.command);
+            if (scope.runId !== work.run_id || scope.projectRoot !== project?.root
+                || scope.generation !== (recoveryGuard(context, work.project_id, work.run_id)?.generation ?? 0))
+                refuse("native_invocation_scope_changed");
+            if (parsed.kind !== "none" && parsed.supported !== false
+                && parsed.invocation.operation === "work_start"
+                && resolveWorkReference(context, commandPosition(parsed.invocation, 0), { projectId: work.project_id }).work_id === workId)
+                freshnessAt = admission.admittedAt;
+        }
+    }
+    if (!prior && (parent.status !== "active" || parent.current_stage !== "review" || Date.parse(hook.created_at) < Date.parse(freshnessAt) - 60_000
+        || Date.parse(hook.created_at) > Date.parse(freshnessAt) || Date.parse(freshnessAt) > Date.parse(context.now())
+        || !Number.isFinite(Date.parse(hook.created_at))))
+        refuse("native_hook_or_parent_not_current");
+    if (prior && (hook.status !== "claimed" || !context.db.get("SELECT 1 FROM work_sessions ws JOIN sessions s ON s.project_id=? AND s.session_id=ws.session_id WHERE ws.id=? AND ws.work_id=? AND ws.hook_event_id=? AND ws.session_id=? AND s.run_id=? AND s.worker_id=? AND s.provider_session_id=? AND s.provider_parent_session_id=?", [work.project_id, prior.work_session_id, workId, key, identity.sessionId, work.run_id, workId, identity.providerSessionId, parent.session_id])))
+        refuse("native_registered_start_changed");
+    const copies = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.repair_writer_copy_ready' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 2", [work.project_id, work.run_id, workId]);
+    if (copies.length !== 1 || Buffer.byteLength(copies[0].payload_json) > 12 * 1024 * 1024)
+        refuse("owned_ready_copy_required");
+    let copy;
+    let intent;
+    try {
+        const value = JSON.parse(copies[0].payload_json), workspace_manifest_sha256 = value.workspace_manifest_sha256;
+        delete value.workspace_manifest_sha256;
+        delete value.workspace_manifest_base64;
+        copy = { ...value, workspace_manifest_sha256 };
+        intent = value;
+        if (value.schema_id !== "dd-flow/memory-repair-writer-copy-intent@1" || value.project_id !== work.project_id
+            || value.run_id !== work.run_id || value.work_id !== workId || !Number.isSafeInteger(value.generation) || value.generation < 0
+            || !path.isAbsolute(value.run_root) || value.run_root !== (run.run_root ?? run.run_dir)
+            || value.copy_relative !== `works/${workId}/writer-workspaces/generation-${value.generation}`
+            || !/^[a-f0-9]{64}$/.test(workspace_manifest_sha256) || !/^[a-f0-9]{64}$/.test(value.baseline_registration_sha256))
+            refuse("foreign_ready_copy");
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("invalid_ready_copy");
+    }
+    const physical = memoryRepairExecutionIdentity(context, { projectId: work.project_id, runId: work.run_id,
+        workId, eventKey: key, root: path.join(copy.run_root, copy.copy_relative) });
+    const frozen = { coordinator: route.coordinator, worker: route.worker, delegation: { mode: "native", max_parallel: null } };
+    const binding = { operation_id: `native-hook:${key}`, status: "start_requested",
+        profile_json: JSON.stringify({ ...frozen, memory_repair_copy: { root: copy.copy_relative,
+                copy_intent_sha256: hybridDigest(intent), workspace_manifest_sha256: copy.workspace_manifest_sha256,
+                baseline_registration_sha256: copy.baseline_registration_sha256 },
+            ...(physical.invocationId ? { native_execution_cwd: { invocation_id: physical.invocationId, root: physical.identity.cwd } } : {}) }),
+        profile_hash: createHash("sha256").update(JSON.stringify(frozen)).digest("hex"), provider_session_id: identity.providerSessionId };
+    if (prior && (prior.parent_session_id !== parent.session_id || prior.parent_provider_session_id !== parent.provider_session_id
+        || hybridDigest(prior.binding) !== hybridDigest(binding)))
+        refuse("native_binding_changed");
+    return binding;
+}
+/** Commit only inside the same writer that claimed the Hook and inserted
+ * the physical WorkSession; rollback removes both authorities together. */
+export function recordMemoryRepairNativeBinding(context, workId, route, binding, workSessionId) {
+    if (route.delegation.mode !== "native")
+        return;
+    if (context.db.isOwnedWriteTransaction?.() !== true)
+        refuse("owned_claim_writer_required");
+    const actual = readMemoryRepairPhysicalBinding(context, workId, route, binding.operation_id);
+    const key = binding.operation_id.slice(12);
+    const row = context.db.get("SELECT w.project_id,w.run_id,he.parent_session_id,p.provider_session_id AS parent_provider_session_id FROM works w JOIN work_sessions ws ON ws.work_id=w.work_id JOIN hook_events he ON he.project_id=w.project_id AND he.event_key=ws.hook_event_id AND he.session_id=ws.session_id JOIN sessions p ON p.project_id=w.project_id AND p.session_id=he.parent_session_id WHERE w.work_id=? AND ws.id=? AND ws.status='running' AND he.status='claimed' AND he.event_key=? AND he.provider_session_id=?", [workId, workSessionId, key, binding.provider_session_id]);
+    if (!row || hybridDigest(actual) !== hybridDigest(binding))
+        refuse("native_claim_identity_changed");
+    const payload = { schema_id: "dd-flow/memory-repair-native-binding@1", project_id: row.project_id, run_id: row.run_id,
+        work_id: workId, work_session_id: workSessionId, parent_session_id: row.parent_session_id,
+        parent_provider_session_id: row.parent_provider_session_id, hook_event_key: key, binding };
+    const prior = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=?", [row.project_id, event, row.run_id, workId]);
+    if (prior && hybridDigest(JSON.parse(prior.payload_json)) !== hybridDigest(payload))
+        refuse("native_binding_changed");
+    if (!prior)
+        appendAudit(context, { projectId: row.project_id, eventType: event, payload });
+}

package/dist/services/memory-repair-publication-files.js

@@ -0,0 +1,152 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+function refuse(reason) {
+    throw new AppError("memory_repair_staging_invalid", "Publication staging file is not the owned exact output prefix", 1, { reason, effect: "no_effect" });
+}
+const noFollow = (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+function regular(stat, limit) {
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > limit)
+        refuse("linked_special_or_oversized_staging_file");
+}
+function same(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mode === right.mode
+        && left.nlink === right.nlink && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+/** Read-only verification after independently retained readiness. Unlike staging
+ * recovery, a ready file is never repaired if it becomes missing or partial.
+ */
+export function verifyRetainedMemoryRepairFile(file, value, mode) {
+    if (!(value instanceof Uint8Array) || value.byteLength > 16 * 1024 * 1024)
+        refuse("invalid_ready_bytes");
+    const before = fs.lstatSync(file);
+    regular(before, value.byteLength);
+    if (before.size !== value.byteLength || (before.mode & 0o7777) !== mode)
+        refuse("ready_staging_file_changed");
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+    try {
+        if (!same(before, fs.fstatSync(fd)))
+            refuse("staging_identity_changed");
+        const bytes = Buffer.alloc(value.byteLength);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (!count)
+                refuse("ready_staging_file_changed");
+            offset += count;
+        }
+        if (!bytes.equals(Buffer.from(value)) || !same(before, fs.fstatSync(fd)) || !same(before, fs.lstatSync(file)))
+            refuse("ready_staging_file_changed");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Low-level staging effects only. The publication owner must independently
+ * journal this exact directory/slot before calling. This function grants no
+ * SQL/Session authority and never changes an MB destination. Unknown existing
+ * bytes are preserved; an owned exact partial file is completed by append.
+ */
+export function stageRetainedMemoryRepairFile(directory, slot, value, mode) {
+    if (!path.isAbsolute(directory) || fs.realpathSync(directory) !== path.resolve(directory)
+        || !fs.lstatSync(directory).isDirectory() || (fs.lstatSync(directory).mode & 0o7777) !== 0o700
+        || !/^action-[0-9]{1,6}\.tmp$/.test(slot) || !(value instanceof Uint8Array) || value.byteLength > 16 * 1024 * 1024
+        || !Number.isInteger(mode) || mode < 0 || mode > 0o7777)
+        refuse("invalid_staging_binding");
+    const directoryIdentity = fs.lstatSync(directory);
+    const bytes = Buffer.from(value), file = path.join(directory, slot);
+    let fd, changed = false, initialSize = 0, replayed = false;
+    try {
+        const prior = fs.lstatSync(file, { throwIfNoEntry: false });
+        if (prior) {
+            replayed = true;
+            regular(prior, bytes.length);
+            if ((prior.mode & 0o7777) !== 0o600 && (prior.size !== bytes.length || (prior.mode & 0o7777) !== mode))
+                refuse("staging_mode_changed");
+            fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+            if (!same(prior, fs.fstatSync(fd)))
+                refuse("staging_identity_changed");
+        }
+        else {
+            fd = fs.openSync(file, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
+            changed = true;
+        }
+        const before = fs.fstatSync(fd);
+        regular(before, bytes.length);
+        initialSize = before.size;
+        const retained = Buffer.alloc(initialSize);
+        let read = 0;
+        while (read < retained.length) {
+            const count = fs.readSync(fd, retained, read, retained.length - read, read);
+            if (!count)
+                refuse("staging_changed_during_read");
+            read += count;
+        }
+        if (!same(before, fs.fstatSync(fd)) || !retained.equals(bytes.subarray(0, initialSize)))
+            refuse("unknown_staging_bytes");
+        if (initialSize < bytes.length && replayed) {
+            fs.closeSync(fd);
+            fd = undefined;
+            fd = fs.openSync(file, fs.constants.O_RDWR | noFollow);
+            if (!same(before, fs.fstatSync(fd)))
+                refuse("staging_identity_changed");
+        }
+        let written = initialSize;
+        while (written < bytes.length) {
+            changed = true;
+            const count = fs.writeSync(fd, bytes, written, bytes.length - written, written);
+            if (!count)
+                throw new Error("No progress writing retained staging bytes");
+            written += count;
+        }
+        if ((fs.fstatSync(fd).mode & 0o7777) !== mode) {
+            changed = true;
+            fs.fchmodSync(fd, mode);
+        }
+        fs.fsyncSync(fd);
+        const after = fs.fstatSync(fd);
+        regular(after, bytes.length);
+        if ((after.mode & 0o7777) !== mode)
+            refuse("staging_final_mode_changed");
+        if (after.size !== bytes.length)
+            refuse("staging_identity_changed");
+        const verified = Buffer.alloc(bytes.length);
+        let checked = 0;
+        while (checked < verified.length) {
+            const count = fs.readSync(fd, verified, checked, verified.length - checked, checked);
+            if (!count)
+                refuse("staging_changed_during_read");
+            checked += count;
+        }
+        if (!verified.equals(bytes) || !same(after, fs.fstatSync(fd)))
+            refuse("staging_output_changed");
+        const named = fs.lstatSync(file);
+        if (after.size !== bytes.length || !same(after, named))
+            refuse("staging_identity_changed");
+        fs.closeSync(fd);
+        fd = undefined;
+        const parent = fs.openSync(directory, fs.constants.O_RDONLY | noFollow);
+        try {
+            const current = fs.fstatSync(parent), namedDirectory = fs.lstatSync(directory);
+            if (!current.isDirectory() || current.dev !== directoryIdentity.dev || current.ino !== directoryIdentity.ino
+                || current.dev !== namedDirectory.dev || current.ino !== namedDirectory.ino || (current.mode & 0o7777) !== 0o700)
+                refuse("staging_directory_changed");
+            fs.fsyncSync(parent);
+        }
+        finally {
+            fs.closeSync(parent);
+        }
+        return { path: file, sha256: createHash("sha256").update(bytes).digest("hex"), status: "ready", replayed,
+            bytes_appended: bytes.length - initialSize };
+    }
+    catch (error) {
+        if (!changed && error instanceof AppError)
+            throw error;
+        throw new AppError("memory_repair_staging_pending", "Owned staging output remains pending; preserve it for exact-prefix reconciliation", 1, { effect: "publication_pending", path: file, cause: error instanceof Error ? error.message : String(error) });
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}

package/dist/services/memory-repair-publication-intent.js

@@ -0,0 +1,27 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { RetainedMemoryRepairPublicationPlan } from "./memory-repair-publication-plan.js";
+/** Metadata decoding only: no start, source, Session or publication authority.
+ * v1 is never promoted to v2 by optional caller fields. */
+export function retainedMemoryRepairPublicationPlans(receipt) {
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+        throw new AppError("memory_repair_publication_invalid", "Retained publication intent must be an object", 1, { reason: "invalid_retained_intent_shape", effect: "no_effect" });
+    }
+    const fields = ["schema_id", "project_id", "run_id", "work_id", "generation", "work_session_id", "source_root", "private_root", "output_sha256",
+        "start_receipt_sha256", "result_sha256", "result_base64", "delta_sha256", "transition_sha256", "before_sha256", "before_base64", "after_sha256", "after_base64", "actions"];
+    const current = receipt.schema_id === "dd-flow/memory-repair-publication-intent@2";
+    if (current)
+        fields.push("source_view_sha256", "source_receipt_sha256", "private_plan_sha256", "private_plan");
+    if ((!current && receipt.schema_id !== "dd-flow/memory-repair-publication-intent@1")
+        || Object.keys(receipt).sort().join(",") !== fields.sort().join(",")
+        || current && (!receipt.private_plan || typeof receipt.private_plan !== "object" || Array.isArray(receipt.private_plan)
+            || [receipt.source_view_sha256, receipt.source_receipt_sha256, receipt.private_plan_sha256].some(value => typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)))
+        || Buffer.byteLength(JSON.stringify(receipt)) > 160 * 1024 * 1024) {
+        throw new AppError("memory_repair_publication_invalid", "Retained publication intent has a foreign version or shape", 1, { reason: "invalid_retained_intent_shape", effect: "no_effect" });
+    }
+    const retained = { before_sha256: receipt.before_sha256, before_base64: receipt.before_base64,
+        after_sha256: receipt.after_sha256, after_base64: receipt.after_base64, actions: receipt.actions };
+    const plan = RetainedMemoryRepairPublicationPlan.restore(Buffer.from(JSON.stringify(retained)), hybridDigest(retained));
+    const privatePlan = current ? RetainedMemoryRepairPublicationPlan.restore(Buffer.from(JSON.stringify(receipt.private_plan)), receipt.private_plan_sha256) : plan;
+    return { current, plan, privatePlan };
+}

package/dist/services/memory-repair-publication-plan.js

@@ -0,0 +1,162 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { MemoryRepairDocumentBaseline } from "./memory-repair-document-delta.js";
+const token = Symbol("retained-memory-repair-publication-plan");
+function refuse(reason) {
+    throw new AppError("memory_repair_publication_plan_invalid", "Retained publication metadata or bytes are inconsistent", 1, { reason, effect: "no_effect" });
+}
+function decode(value, limit) {
+    if (typeof value !== "string" || value.length > Math.ceil(limit / 3) * 4)
+        refuse("unbounded_or_invalid_bytes");
+    const bytes = Buffer.from(value, "base64");
+    if (bytes.length > limit || bytes.toString("base64") !== value)
+        refuse("noncanonical_retained_bytes");
+    return bytes;
+}
+function ordered(entries) {
+    return [...entries].sort((a, b) => {
+        const left = a.path.split("/"), right = b.path.split("/");
+        for (let index = 0; index < Math.min(left.length, right.length); index++) {
+            if (left[index] !== right[index])
+                return left[index] < right[index] ? -1 : 1;
+        }
+        return left.length - right.length;
+    });
+}
+/** Strict retained metadata decoder, not SQL/Session authority or permission
+ * to apply files. The publication owner must independently select its receipt.
+ * Restoration never captures today's partly published workspace as baseline.
+ */
+export class RetainedMemoryRepairPublicationPlan {
+    sha256;
+    #receipt;
+    #before;
+    #writePaths;
+    constructor(key, receipt, before) {
+        if (key !== token)
+            refuse("retained_plan_token_required");
+        this.#receipt = structuredClone(receipt);
+        this.#before = before;
+        this.#writePaths = JSON.parse(before.bytes().toString("utf8")).write_paths;
+        this.sha256 = hybridDigest(receipt);
+        Object.freeze(this);
+    }
+    static restore(bytes, expectedSha256) {
+        try {
+            if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 160 * 1024 * 1024
+                || typeof expectedSha256 !== "string" || !/^[a-f0-9]{64}$/.test(expectedSha256))
+                refuse("invalid_retained_plan");
+            const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+            if (!value || Object.keys(value).sort().join(",") !== "actions,after_base64,after_sha256,before_base64,before_sha256"
+                || !Array.isArray(value.actions) || value.actions.length > 20_000 || hybridDigest(value) !== expectedSha256
+                || !Buffer.from(JSON.stringify(value)).equals(Buffer.from(bytes)))
+                refuse("invalid_retained_plan");
+            const before = MemoryRepairDocumentBaseline.restore(decode(value.before_base64, 8 * 1024 * 1024), value.before_sha256);
+            const after = MemoryRepairDocumentBaseline.restore(decode(value.after_base64, 8 * 1024 * 1024), value.after_sha256);
+            const writes = JSON.parse(before.bytes().toString("utf8")).write_paths;
+            if (hybridDigest(writes) !== hybridDigest(JSON.parse(after.bytes().toString("utf8")).write_paths))
+                refuse("write_paths_changed");
+            if (hybridDigest([...before.canonicalWritePaths()]) !== hybridDigest([...after.canonicalWritePaths()]))
+                refuse("canonical_permissions_changed");
+            const current = new Map(before.entries().map(entry => [entry.path, entry]));
+            const final = new Map(after.entries().map(entry => [entry.path, entry]));
+            const directories = new Set();
+            for (const entry of final.values())
+                if (entry.kind === "file") {
+                    const parts = entry.path.split("/");
+                    for (let length = 1; length < parts.length; length++)
+                        directories.add(parts.slice(0, length).join("/"));
+                }
+            const seen = new Set();
+            let total = 0;
+            for (const action of value.actions) {
+                if (!action || Object.keys(action).sort().join(",") !== "after,before,bytes_base64,path" || typeof action.path !== "string"
+                    || seen.has(action.path) || hybridDigest(action.before) !== hybridDigest(current.get(action.path) ?? null)
+                    || hybridDigest(action.after) !== hybridDigest(final.get(action.path) ?? null)
+                    || hybridDigest(action.before) === hybridDigest(action.after))
+                    refuse("invalid_retained_action");
+                seen.add(action.path);
+                if (action.after?.kind === "directory") {
+                    if (action.before || ![0o700, 0o755].includes(action.after.mode) || action.bytes_base64 !== null
+                        || !directories.has(action.path))
+                        refuse("unassigned_directory_action");
+                }
+                else {
+                    if (!writes.includes(action.path) || action.before?.kind === "directory"
+                        || action.after && action.after.kind !== "file")
+                        refuse("unassigned_file_action");
+                    if (action.after) {
+                        if (action.before ? action.before.mode !== action.after.mode : ![0o600, 0o644].includes(action.after.mode))
+                            refuse("file_mode_action");
+                        const content = decode(action.bytes_base64, 16 * 1024 * 1024);
+                        total += content.length;
+                        if (total > 64 * 1024 * 1024 || createHash("sha256").update(content).digest("hex") !== action.after.sha256
+                            || action.before?.sha256 === action.after.sha256)
+                            refuse("retained_output_bytes_changed");
+                    }
+                    else if (!action.before || action.bytes_base64 !== null)
+                        refuse("invalid_delete_action");
+                }
+                if (action.after) {
+                    const parent = action.path.slice(0, action.path.lastIndexOf("/"));
+                    if (current.get(parent)?.kind !== "directory")
+                        refuse("parent_action_out_of_order");
+                    current.set(action.path, action.after);
+                }
+                else
+                    current.delete(action.path);
+            }
+            if (hybridDigest(ordered(current.values())) !== hybridDigest(after.entries()))
+                refuse("unexplained_after_view");
+            return new RetainedMemoryRepairPublicationPlan(token, value, before);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_repair_publication_plan_invalid")
+                throw error;
+            return refuse("invalid_retained_plan");
+        }
+    }
+    actions() { return structuredClone(this.#receipt.actions); }
+    bytes() { return Buffer.from(JSON.stringify(this.#receipt)); }
+    output(logical) {
+        const action = this.#receipt.actions.find(item => item.path === logical && item.after?.kind === "file");
+        if (!action)
+            refuse("unselected_output");
+        return decode(action.bytes_base64, 16 * 1024 * 1024);
+    }
+    state(completed) {
+        if (!Number.isSafeInteger(completed) || completed < 0 || completed > this.#receipt.actions.length)
+            refuse("invalid_cursor");
+        const entries = new Map(this.#before.entries().map(entry => [entry.path, entry]));
+        for (const action of this.#receipt.actions.slice(0, completed)) {
+            if (action.after)
+                entries.set(action.path, action.after);
+            else
+                entries.delete(action.path);
+        }
+        const value = { ...JSON.parse(this.#before.bytes().toString("utf8")), entries: ordered(entries.values()) };
+        return MemoryRepairDocumentBaseline.restore(Buffer.from(JSON.stringify(value)), hybridDigest({ ...value, schema_id: undefined }));
+    }
+    classify(workspace) {
+        const actual = MemoryRepairDocumentBaseline.capture(workspace, this.#writePaths, this.#before.canonicalWritePaths());
+        const entries = new Map(actual.entries().map(entry => [entry.path, entry]));
+        let completed = 0, pending = false;
+        for (const action of this.#receipt.actions) {
+            const current = entries.get(action.path) ?? null;
+            if (hybridDigest(current) === hybridDigest(action.after)) {
+                if (pending)
+                    refuse("unknown_publication_prefix");
+                completed++;
+            }
+            else if (hybridDigest(current) === hybridDigest(action.before))
+                pending = true;
+            else
+                refuse("unknown_publication_prefix");
+        }
+        if (actual.sha256 !== this.state(completed).sha256)
+            refuse("unknown_publication_prefix");
+        return { completed, total: this.#receipt.actions.length,
+            status: completed === this.#receipt.actions.length ? "after" : completed === 0 ? "before" : "partial" };
+    }
+}