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

package/dist/services/memory-upgrade-inventory.js

@@ -0,0 +1,442 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { PreparedMemoryLayer, isCanonicalOnlyMemoryPath } from "./memory-layer.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
+import { validateSchema } from "./schema-validation.js";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { localEnvironmentAllowed } from "./workspace-files.js";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+function projectPaths(workspace, gitExecutable, env, trackedOnly = false) {
+    const gitEnv = Object.fromEntries(Object.entries({ ...process.env, ...env }).filter(([key]) => !key.startsWith("GIT_")));
+    const result = spawnSync(gitExecutable, ["-c", "core.fsmonitor=false", "-c", "core.untrackedCache=false",
+        "-C", workspace, "ls-files", "-z", "--cached", ...(trackedOnly ? [] : ["--others", "--exclude-standard"])], { env: { ...gitEnv, GIT_OPTIONAL_LOCKS: "0" }, encoding: "utf8", timeout: 5000, maxBuffer: 1024 * 1024 });
+    if (result.error || result.signal || result.status !== 0)
+        refuse("git_observation_failed");
+    const paths = [...new Set(result.stdout.split("\0").filter(Boolean))].sort();
+    if (paths.length > 20_000)
+        refuse("source_inventory_exceeds_bound");
+    return paths;
+}
+function projectEvidencePath(logical) {
+    return typeof logical === "string" && logical.length <= 4096 && !path.posix.isAbsolute(logical) && !path.win32.isAbsolute(logical)
+        && !logical.includes("\\") && !logical.includes("\0") && logical.split("/").every(part => part && part !== "." && part !== ".."
+        && ![".git", "node_modules", ".dd-flow", ".memory-bank", ".tasks", ".dd-eval", ".codex", ".claude", ".zcode"].includes(part.toLowerCase()) && localEnvironmentAllowed(part));
+}
+/** Old public project inputs for preservation claims, never untracked scratch,
+ * provider state or link referents. The existing selection size bound applies. */
+export function captureUpgradeProjectFiles(workspace, gitExecutable, env) {
+    const files = [];
+    let total = 0;
+    for (const logical of projectPaths(workspace, gitExecutable, env, true)) {
+        if (!projectEvidencePath(logical))
+            continue;
+        let parent = workspace, safe = true;
+        for (const part of logical.split("/").slice(0, -1)) {
+            parent = path.join(parent, part);
+            if (!fs.lstatSync(parent, { throwIfNoEntry: false })?.isDirectory()) {
+                safe = false;
+                break;
+            }
+        }
+        if (!safe)
+            continue;
+        const file = path.join(workspace, logical), stat = fs.lstatSync(file, { throwIfNoEntry: false });
+        if (!stat?.isFile())
+            continue;
+        if (stat.size > 16 * 1024 * 1024 || (total += stat.size) > 64 * 1024 * 1024)
+            refuse("source_inventory_exceeds_bound");
+        const observed = observeContent(file);
+        if (observed.reference.kind !== "file")
+            refuse("source_changed_during_inventory", file);
+        files.push({ path: logical, base64: observed.content.toString("base64"), sha256: observed.reference.sha256, mode: observed.reference.mode });
+    }
+    return files;
+}
+/** Decode frozen bytes only; today's files cannot fill missing old evidence. */
+export function readUpgradeProjectFiles(value) {
+    if (!Array.isArray(value) || value.length > 20_000)
+        refuse("invalid_project_evidence");
+    const seen = new Set();
+    let total = 0;
+    for (const file of value) {
+        if (!file || Object.keys(file).sort().join() !== "base64,mode,path,sha256" || !projectEvidencePath(file.path)
+            || seen.has(file.path) || typeof file.base64 !== "string" || file.base64.length > 24 * 1024 * 1024
+            || !Number.isInteger(file.mode) || file.mode < 0 || file.mode > 0o777)
+            refuse("invalid_project_evidence");
+        const bytes = Buffer.from(file.base64, "base64");
+        if (bytes.toString("base64") !== file.base64 || bytes.length > 16 * 1024 * 1024 || (total += bytes.length) > 64 * 1024 * 1024
+            || hash(bytes) !== file.sha256)
+            refuse("invalid_project_evidence");
+        seen.add(file.path);
+    }
+    return structuredClone(value);
+}
+/** Literal link identity only: neither outside nor inside referents are read. */
+export function captureUpgradeProjectLinks(workspace, gitExecutable, env) {
+    const paths = projectPaths(workspace, gitExecutable, env), links = [];
+    let total = 0;
+    for (const logical of paths) {
+        const parts = logical.split("/");
+        if (path.isAbsolute(logical) || parts.some(part => !part || part === "." || part === ".."))
+            refuse("unsafe_source_path");
+        if (parts.some(part => [".git", "node_modules", ".dd-flow"].includes(part) || !localEnvironmentAllowed(part)))
+            continue;
+        let directory = workspace, safe = true;
+        for (const part of parts.slice(0, -1)) {
+            directory = path.join(directory, part);
+            if (!fs.lstatSync(directory, { throwIfNoEntry: false })?.isDirectory()) {
+                safe = false;
+                break;
+            }
+        }
+        if (!safe)
+            continue;
+        const file = path.join(workspace, logical), stat = fs.lstatSync(file, { throwIfNoEntry: false });
+        if (!stat?.isSymbolicLink())
+            continue;
+        const observed = observeContent(file);
+        if ((total += observed.content.length) > 1024 * 1024)
+            refuse("link_metadata_exceeds_bound");
+        links.push({ path: logical, target_base64: observed.content.toString("base64"), sha256: observed.reference.sha256, mode: observed.reference.mode });
+    }
+    return links;
+}
+function refuse(reason, file) {
+    throw new AppError("upgrade_inventory_invalid", "Upgrade inventory cannot safely authorize content changes", 1, { reason, ...(file ? { file } : {}), effect: "no_effect" });
+}
+function observe(file) {
+    return observeContent(file).reference;
+}
+function observeContent(file) {
+    const before = fs.lstatSync(file);
+    if (!before.isFile() && !before.isSymbolicLink())
+        refuse("unsupported_source_kind", file);
+    const content = before.isSymbolicLink() ? fs.readlinkSync(file, { encoding: "buffer" })
+        : before.size === 0 ? Buffer.alloc(0) : readBoundedReleaseFile(file, 64 * 1024 * 1024);
+    const after = fs.lstatSync(file);
+    if (before.dev !== after.dev || before.ino !== after.ino || before.mtimeMs !== after.mtimeMs
+        || before.size !== after.size || before.mode !== after.mode)
+        refuse("source_changed_during_inventory", file);
+    const reference = { path: file, sha256: hash(content), kind: before.isSymbolicLink() ? "link" : "file", mode: before.mode & 0o777 };
+    return { reference, content };
+}
+/** Old @2 producers repeated canon_root under canon_repo_root. Observe that
+ * exact redundant hint only; it never selects a live canonical checkout. */
+function validateUpgradeManifest(manifest, file) {
+    const data = { ...manifest };
+    if (Object.hasOwn(data, "canon_repo_root")) {
+        if (data.schema_id !== "dd-flow/project-flow-pack-manifest@2" || typeof data.canon_repo_root !== "string"
+            || data.canon_repo_root !== data.canon_root)
+            refuse("legacy_manifest_root_conflict", file);
+        delete data.canon_repo_root;
+    }
+    validateSchema({ schemaName: "project-flow-pack-manifest", file, data, schemaDir: fileURLToPath(new URL("../schemas/", import.meta.url)) });
+}
+/** Read-only ownership/delta map. Version mismatch alone grants no overwrite.
+ * Project manifest hashes are hints, not independent canonical authority.
+ * Without a prepared old release, canonical-looking files need semantic Work.
+ */
+export function prepareMemoryUpgradeInventory(workspaceRoot, layer, baselineLayer) {
+    if (!(layer instanceof PreparedMemoryLayer))
+        refuse("unprepared_target_layer");
+    if (baselineLayer !== undefined && !(baselineLayer instanceof PreparedMemoryLayer))
+        refuse("unprepared_baseline_layer");
+    if (!path.isAbsolute(workspaceRoot) || fs.realpathSync(workspaceRoot) !== workspaceRoot)
+        refuse("noncanonical_workspace");
+    const root = path.join(workspaceRoot, ".memory-bank");
+    if (!fs.lstatSync(root).isDirectory())
+        refuse("linked_or_missing_memory_bank");
+    if (!fs.lstatSync(path.join(root, "dd-flow")).isDirectory())
+        refuse("linked_or_missing_project_pack");
+    if (!fs.lstatSync(path.join(root, "dd-flow/manifest.json")).isFile())
+        refuse("linked_or_missing_manifest");
+    const prepared = prepareJsonFile(path.join(root, "dd-flow/manifest.json"), "Current project flow-pack manifest");
+    validateUpgradeManifest(prepared.value, prepared.file);
+    const manifest = prepared.value, current = new Map(), directories = new Set();
+    const baselineFiles = baselineLayer?.files();
+    if (baselineFiles) {
+        const content = baselineFiles.get("dd-flow/manifest.json");
+        if (!content)
+            refuse("baseline_manifest_missing");
+        let old;
+        try {
+            old = JSON.parse(content.toString("utf8"));
+        }
+        catch {
+            return refuse("baseline_manifest_invalid");
+        }
+        validateUpgradeManifest(old, "retained-baseline/dd-flow/manifest.json");
+        if (old.source_commit !== manifest.source_commit || old.canon_version_at_source_commit !== manifest.canon_version_at_source_commit)
+            refuse("baseline_provenance_mismatch");
+    }
+    let bytes = 0;
+    const collect = (directory, prefix = "") => {
+        for (const name of fs.readdirSync(directory).sort()) {
+            const relative = prefix + name, file = path.join(directory, name), stat = fs.lstatSync(file);
+            if (stat.isDirectory()) {
+                if (relative.split("/").length > 64)
+                    refuse("unbounded_directory_depth");
+                directories.add(relative);
+                collect(file, `${relative}/`);
+            }
+            else {
+                if (current.size >= 20_000 || (bytes += stat.size) > 64 * 1024 * 1024)
+                    refuse("unbounded_current_inventory");
+                current.set(relative, observe(file));
+            }
+        }
+    };
+    collect(root);
+    const target = layer.files(), installed = new Set(manifest.included_files.map(file => `dd-flow/${file}`));
+    const paths = [...new Set([...current.keys(), ...target.keys(), ...installed])].sort();
+    const entries = paths.map(logical => {
+        const source = current.get(logical) ?? null, content = target.get(logical);
+        const expected = logical.startsWith("dd-flow/") ? manifest.file_hashes?.[logical.slice(8)] : undefined;
+        const baselineBytes = baselineFiles?.get(logical);
+        const baseline = baselineBytes && (logical.startsWith("mbb/") || installed.has(logical) || isCanonicalOnlyMemoryPath(logical))
+            && (expected === undefined || expected === hash(baselineBytes)) ? hash(baselineBytes) : null;
+        const destination = content ? { path: logical, sha256: hash(content) } : null;
+        const canonical = source?.kind === "file" && baseline !== null && source.sha256 === baseline;
+        const generated = logical === "dd-flow/manifest.json" || logical.startsWith("dd-flow/.generated/")
+            && manifest.generated_allow_patterns?.includes(".generated/**");
+        let ownership = "project", action = "retain";
+        if (generated) {
+            ownership = "generated";
+            if (source && destination && source.sha256 !== destination.sha256)
+                action = "update";
+        }
+        else if (canonical) {
+            ownership = "canonical";
+            action = !destination ? "archive" : destination.sha256 === source.sha256 ? "retain" : "update";
+        }
+        else if (installed.has(logical) || logical.startsWith("dd-flow/") || logical.startsWith("mbb/")) {
+            ownership = "local-customized";
+            if (destination && (!source || source.kind !== "file" || destination.sha256 !== source.sha256) || installed.has(logical) && !source)
+                action = "semantic-work";
+        }
+        if (!source && destination && !installed.has(logical)) {
+            ownership = "canonical";
+            action = "add";
+        }
+        const ancestors = logical.split("/").slice(0, -1).map((_part, index, parts) => parts.slice(0, index + 1).join("/"));
+        if (destination && (directories.has(logical) || ancestors.some(parent => current.has(parent)))) {
+            ownership = "local-customized";
+            action = "semantic-work";
+        }
+        return { path: logical, ownership, action, current: source, target: destination, baseline_sha256: baseline };
+    });
+    const inventory = { schema_id: "dd-flow/mb-upgrade-inventory@1", workspace_root: workspaceRoot,
+        current_manifest: { path: prepared.file, sha256: hash(prepared.text) }, target_layer_sha256: layer.sha256,
+        baseline_layer_sha256: baselineLayer?.sha256 ?? null,
+        entries, local_divergences: entries.filter(entry => entry.ownership === "local-customized").map(entry => entry.path) };
+    return { inventory, sha256: hybridDigest(inventory) };
+}
+/** Older selections called the CLI-owned manifest "retain" even when its
+ * target bytes differed. Admit that exact historical representation only;
+ * all source/target hashes, modes, ownership and other actions still match.
+ * Never rewrite the retained inventory or its issued evidence projection. */
+export function matchesRetainedMemoryUpgradeInventory(current, retained) {
+    if (current.sha256 === retained.sha256)
+        return true;
+    const legacy = retained.inventory.entries.find(entry => entry.path === "dd-flow/manifest.json"
+        && entry.ownership === "generated" && entry.action === "retain");
+    if (!legacy)
+        return false;
+    const inventory = { ...current.inventory, entries: current.inventory.entries.map(entry => entry.path === legacy.path && entry.ownership === "generated" && entry.action === "update"
+            ? { ...entry, action: "retain" } : entry) };
+    return hybridDigest(inventory) === retained.sha256;
+}
+/** Full accepted upgrade plan, unlike the reusable partial permission helper.
+ * Refuse omissions while diff-analysis is still correctable, before its plan
+ * becomes immutable or Work/publication effects begin.
+ */
+export function validateUpgradePathMap(inventory, changes) {
+    const paths = upgradeAuthoringPaths(inventory, changes);
+    for (const entry of inventory.entries) {
+        const required = entry.ownership === "canonical" && entry.action !== "retain"
+            || entry.ownership === "generated" && entry.target && entry.current?.sha256 !== entry.target.sha256
+            || entry.ownership === "local-customized" && entry.action === "semantic-work";
+        if (!required)
+            continue;
+        const logical = `.memory-bank/${entry.path}`;
+        const covered = changes.some(change => {
+            if (change.ownership !== entry.ownership)
+                return false;
+            if (entry.ownership === "generated")
+                return change.action === "update" && change.from === logical && change.to === logical;
+            if (entry.ownership === "local-customized")
+                return change.from === logical || !entry.current && change.to === logical;
+            if (entry.action === "archive")
+                return change.from === logical && ["archive", "move"].includes(change.action);
+            if (entry.action === "add")
+                return change.to === logical && ["add", "move"].includes(change.action);
+            return change.from === logical && change.to === logical && ["update", "semantic-work"].includes(change.action);
+        });
+        if (!covered)
+            refuse("incomplete_upgrade_path_map", entry.path);
+    }
+    return paths;
+}
+/** Finite authoring paths from an independently accepted diff. Retention and
+ * archival are not semantic write permissions; removal/publication has its own
+ * mechanical owner. A project snapshot cannot grant canonical ownership.
+ */
+export function upgradeAuthoringPaths(inventory, changes) {
+    const entries = new Map(inventory.entries.map(entry => [entry.path, entry]));
+    const result = new Map();
+    const aliases = new Map();
+    const physical = (value) => value.normalize("NFC").toLowerCase();
+    const currentPhysicalPaths = new Map();
+    for (const entry of inventory.entries)
+        if (entry.current) {
+            const key = physical(entry.path), paths = currentPhysicalPaths.get(key) ?? [];
+            paths.push(entry.path);
+            currentPhysicalPaths.set(key, paths);
+        }
+    // A diff describes one transition from the retained tree, not sequential
+    // edits. Mechanical publication and semantic Work cannot share a path.
+    const claim = (paths) => {
+        for (const value of new Set(paths)) {
+            const key = physical(value);
+            for (const [prior, logical] of aliases) {
+                if (prior === key && logical !== value)
+                    refuse("aliased_upgrade_destinations");
+                if (prior === key || prior.startsWith(`${key}/`) || key.startsWith(`${prior}/`))
+                    refuse("conflicting_upgrade_effects");
+            }
+            aliases.set(key, value);
+        }
+    };
+    const logical = (value) => {
+        if (!value.startsWith(".memory-bank/") || value.includes("\\") || value.includes("\0")
+            || value.split("/").some(part => !part || part === "." || part === ".."))
+            refuse("invalid_upgrade_authoring_path");
+        return value.slice(".memory-bank/".length);
+    };
+    for (const change of changes) {
+        const from = change.from === null ? null : logical(change.from), to = change.to === null ? null : logical(change.to);
+        const source = from === null ? undefined : entries.get(from), destination = to === null ? undefined : entries.get(to);
+        if (from !== null && !source?.current)
+            refuse("missing_upgrade_source");
+        const owner = source ?? destination;
+        if (owner ? owner.ownership !== change.ownership : change.ownership !== "project")
+            refuse("changed_upgrade_ownership");
+        if (change.action === "retain" && from !== null && to !== null && from !== to || change.action === "add" && from !== null
+            || change.action === "update" && (from === null || from !== to) || change.action === "move" && (from === null || to === null || from === to))
+            refuse("invalid_upgrade_path_action");
+        if (change.action === "retain") {
+            if (from === null && (to === null || !destination || destination.current !== null || destination.ownership !== "local-customized"))
+                refuse("invalid_upgrade_path_action");
+            continue;
+        }
+        if (change.action === "archive") {
+            if (source?.ownership !== "canonical" || !source.baseline_sha256)
+                refuse("unverified_canonical_archive");
+            if (to !== null)
+                refuse("invalid_upgrade_path_action");
+            claim([from]);
+            continue;
+        }
+        if (owner?.ownership === "generated" && change.action !== "update")
+            refuse("invalid_generated_upgrade_action");
+        if (to === null || change.action === "add" && destination?.current || from !== to && destination?.current)
+            refuse("conflicting_upgrade_destination");
+        if (owner?.ownership === "local-customized" && change.action !== "semantic-work" && change.action !== "move")
+            refuse("customized_upgrade_requires_semantic_work");
+        if (owner?.ownership === "canonical" && change.action === "move"
+            && (source?.action !== "archive" || destination?.ownership !== "canonical" || destination.action !== "add"))
+            refuse("invalid_canonical_move");
+        if (destination?.current?.kind === "link" || source?.current?.kind === "link"
+            || currentPhysicalPaths.get(physical(to))?.some(value => value !== to)
+            || inventory.entries.some(entry => entry.current && (entry.path.startsWith(`${to}/`) || to.startsWith(`${entry.path}/`))))
+            refuse("unsafe_upgrade_destination_kind");
+        claim(from === null ? [to] : [from, to]);
+        if (owner?.ownership === "generated" || owner?.ownership === "canonical" && change.action !== "semantic-work")
+            continue;
+        const paths = result.get(change.unit_id) ?? [];
+        if (!paths.includes(change.to))
+            paths.push(change.to);
+        result.set(change.unit_id, paths);
+    }
+    return result;
+}
+function preservationFile(inventory, logical) {
+    const parts = logical.split("/");
+    if (parts.some(part => !part || part === "." || part === "..") || path.isAbsolute(logical) || logical.includes("\\") || logical.includes("\0"))
+        refuse("invalid_preservation_path");
+    const root = path.join(inventory.workspace_root, ".memory-bank");
+    if (fs.realpathSync(root) !== root)
+        refuse("linked_preservation_root");
+    for (let index = 1; index < parts.length; index++)
+        if (!fs.lstatSync(path.join(root, ...parts.slice(0, index))).isDirectory())
+            refuse("linked_preservation_parent");
+    return path.join(root, logical);
+}
+/** Capture before any content effect. Local facts and customized canonical
+ * files are retained alike; a symlink contributes its link bytes, not its target.
+ * The enclosing immutable selection/SQL receipt owns custody, not these hashes.
+ */
+export function captureUpgradePreservationBaseline(selected) {
+    if (hybridDigest(selected.inventory) !== selected.sha256)
+        refuse("changed_baseline_inventory");
+    const files = selected.inventory.entries.filter(entry => entry.current).map(entry => {
+        const file = preservationFile(selected.inventory, entry.path), observed = observeContent(file);
+        if (hybridDigest(observed.reference) !== hybridDigest(entry.current))
+            refuse("baseline_source_changed", file);
+        return { path: entry.path, base64: observed.content.toString("base64") };
+    });
+    const baseline = { schema_id: "dd-flow/mb-upgrade-preservation-baseline@1", inventory_sha256: selected.sha256, files };
+    readUpgradePreservationBaseline(baseline, selected);
+    return baseline;
+}
+/** Pure historical decoding, including under an SQL writer/read snapshot.
+ * No filesystem access, restoration, overwrite permission or semantic PASS.
+ */
+export function readUpgradePreservationBaseline(baseline, selected) {
+    if (!baseline || Object.keys(baseline).sort().join() !== "files,inventory_sha256,schema_id"
+        || baseline.schema_id !== "dd-flow/mb-upgrade-preservation-baseline@1" || baseline.inventory_sha256 !== selected.sha256
+        || hybridDigest(selected.inventory) !== selected.sha256 || !Array.isArray(baseline.files) || baseline.files.length > 20_000)
+        refuse("invalid_preservation_baseline");
+    const expected = selected.inventory.entries.filter(entry => entry.current);
+    if (baseline.files.length !== expected.length)
+        refuse("incomplete_preservation_baseline");
+    const files = new Map();
+    let size = 0;
+    for (const [index, entry] of baseline.files.entries()) {
+        const original = expected[index], reference = original.current;
+        if (!entry || Object.keys(entry).sort().join() !== "base64,path" || entry.path !== original.path || files.has(entry.path)
+            || typeof entry.base64 !== "string" || entry.base64.length > 90 * 1024 * 1024)
+            refuse("invalid_preservation_baseline_file");
+        const content = Buffer.from(entry.base64, "base64");
+        if ((size += content.length) > 64 * 1024 * 1024 || content.toString("base64") !== entry.base64 || hash(content) !== reference.sha256
+            || !["file", "link"].includes(reference.kind) || !Number.isInteger(reference.mode) || reference.mode < 0 || reference.mode > 0o777)
+            refuse("preservation_baseline_bytes_changed");
+        files.set(entry.path, { bytes: content, kind: reference.kind, mode: reference.mode, sha256: reference.sha256 });
+    }
+    return files;
+}
+/** Exact-byte and mode preservation for files outside canonical replacement.
+ * Semantic edits are intentionally not excused here: their acceptance needs
+ * separately named facts/invariants and independent review, not a path bypass.
+ */
+export function verifyUpgradePreservation(inventory) {
+    const violations = [];
+    for (const entry of inventory.entries) {
+        if (!entry.current || !["project", "local-customized"].includes(entry.ownership))
+            continue;
+        try {
+            const actual = observe(preservationFile(inventory, entry.path));
+            if (actual.sha256 !== entry.current.sha256 || actual.kind !== entry.current.kind || actual.mode !== entry.current.mode)
+                violations.push({ path: entry.path, reason: "preserved_source_changed" });
+        }
+        catch {
+            violations.push({ path: entry.path, reason: "preserved_source_unavailable" });
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}

package/dist/services/memory-upgrade-publication-custody.js

@@ -0,0 +1,73 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedMemoryUpgradePublication } from "./memory-upgrade-publication.js";
+export const upgradePublicationIntentEvent = "memory.upgrade_publication_intent";
+export const upgradePublicationCompleteEvent = "memory.upgrade_publication_complete";
+export const upgradePublicationKey = (binding) => `memory_upgrade_publication:${hybridDigest(binding.scope)}`;
+export function upgradePublicationReceipt(binding, plan, complete = false) {
+    return { schema_id: complete ? "dd-flow/memory-upgrade-publication-complete@1" : "dd-flow/memory-upgrade-publication-intent@1",
+        run_id: binding.scope.run_id, scope_sha256: hybridDigest(binding.scope), binding_sha256: hybridDigest(binding), plan_sha256: plan.sha256,
+        ...(complete ? { outputs: plan.outputs() } : {}) };
+}
+function refuse(reason) {
+    throw new AppError("memory_upgrade_publication_custody_invalid", "Publication lacks its exact SQL intent or completion", 1, { reason, effect: "no_effect" });
+}
+/** SQL-only read. The caller selects binding from RUN/bootstrap/registration
+ * and settled Work, not agent JSON. Historical readability grants no effects
+ * or current filesystem proof; the physical publisher and Stage check those.
+ */
+export function readMemoryUpgradePublication(context, binding) {
+    return context.db.readSnapshot(() => {
+        const row = context.db.get("SELECT value_json FROM runtime_config WHERE key=?", [upgradePublicationKey(binding)]);
+        const events = (event) => context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.scope_sha256')=? LIMIT 2", [binding.scope.project_id, event, hybridDigest(binding.scope)]);
+        const intents = events(upgradePublicationIntentEvent), completions = events(upgradePublicationCompleteEvent);
+        if (!row && !intents.length && !completions.length)
+            return null;
+        if (!row || intents.length !== 1 || completions.length > 1 || row.value_json.length > 180 * 1024 * 1024
+            || intents[0].payload_json.length > 32768 || completions.some(row => row.payload_json.length > 16 * 1024 * 1024))
+            refuse("intent_custody_missing_or_unbounded");
+        try {
+            const value = JSON.parse(row.value_json);
+            if (!value || Object.keys(value).sort().join() !== "binding,plan_json,plan_sha256" || hybridDigest(value.binding) !== hybridDigest(binding)
+                || typeof value.plan_json !== "string")
+                refuse("publication_binding_changed");
+            const plan = PreparedMemoryUpgradePublication.restore(Buffer.from(value.plan_json), value.plan_sha256);
+            if (hybridDigest(JSON.parse(intents[0].payload_json)) !== hybridDigest(upgradePublicationReceipt(binding, plan)))
+                refuse("intent_changed");
+            if (completions.length && hybridDigest(JSON.parse(completions[0].payload_json)) !== hybridDigest(upgradePublicationReceipt(binding, plan, true)))
+                refuse("completion_changed");
+            return { plan, completed: completions.length === 1 };
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            return refuse("invalid_publication_record");
+        }
+    });
+}
+/** Read a completed publication after Stage acceptance. The original Work
+ * digest stays in its independently audited publication intent; later FINISH
+ * must not reconstruct original Work from repaired current documents. All
+ * remaining identity fields are selected again by the RUN/bootstrap owner.
+ * This read grants no publication effects or current-content acceptance. */
+export function readCompletedMemoryUpgradePublication(context, expected) {
+    return context.db.readSnapshot(() => {
+        const row = context.db.get("SELECT value_json FROM runtime_config WHERE key=?", [upgradePublicationKey(expected)]);
+        if (!row || Buffer.byteLength(row.value_json) > 180 * 1024 * 1024)
+            refuse("completed_publication_required");
+        let binding;
+        try {
+            binding = JSON.parse(row.value_json).binding;
+        }
+        catch {
+            return refuse("invalid_publication_record");
+        }
+        if (!binding || typeof binding.work_custody_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(binding.work_custody_sha256)
+            || hybridDigest(binding) !== hybridDigest({ ...expected, work_custody_sha256: binding.work_custody_sha256 }))
+            refuse("publication_binding_changed");
+        const retained = readMemoryUpgradePublication(context, binding);
+        if (!retained?.completed)
+            refuse("completed_publication_required");
+        return { binding: structuredClone(binding), plan: retained.plan };
+    });
+}