@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.138

package/dist/services/memory-repair-document-delta.js

@@ -0,0 +1,451 @@
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { assertMemoryRepairWritePaths } from "./memory-review-correction-plan.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { reviewEnvironmentAllowed } from "./review-copy.js";
+const observationToken = Symbol("memory-repair-document-observation");
+const transitionToken = Symbol("memory-repair-document-transition");
+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;
+    });
+}
+function refuse(reason) {
+    throw new AppError("memory_repair_document_delta_invalid", "Physical repair documents differ from their bounded baseline", 2, { reason, effect: "no_effect" });
+}
+const alias = (logical) => logical.normalize("NFC").toLowerCase();
+function inventory(root) {
+    if (!path.isAbsolute(root) || fs.realpathSync(root) !== path.resolve(root) || !fs.lstatSync(root).isDirectory())
+        refuse("noncanonical_workspace");
+    const entries = [], aliases = new Set();
+    const visit = (logical, depth) => {
+        if (depth > 64 || entries.length >= 20_000 || logical.length > 4096)
+            refuse("unbounded_document_inventory");
+        const file = path.join(root, logical), stat = fs.lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile() || stat.isFile() && stat.nlink !== 1)
+            refuse("linked_or_special_document");
+        if (aliases.has(alias(logical)))
+            refuse("aliased_document_inventory");
+        aliases.add(alias(logical));
+        entries.push({ path: logical, kind: stat.isDirectory() ? "directory" : "file", mode: stat.mode & 0o7777, sha256: null });
+        if (stat.isDirectory())
+            for (const name of fs.readdirSync(file).sort()) {
+                if (!name || name.includes("\\") || name.includes("\0") || name === "." || name === "..")
+                    refuse("unsafe_document_name");
+                visit(`${logical}/${name}`, depth + 1);
+            }
+    };
+    visit(".memory-bank", 0);
+    return entries;
+}
+function capture(root) {
+    try {
+        const initial = inventory(root);
+        const files = initial.filter(entry => entry.kind === "file");
+        const evidenceAllowed = (logical) => logical.split("/").every(part => reviewEnvironmentAllowed(alias(part))
+            && ![".git", "node_modules", ".dd-flow"].includes(alias(part)));
+        let size = 0;
+        for (const entry of files) {
+            const bytes = fs.lstatSync(path.join(root, entry.path)).size;
+            if (bytes > 16 * 1024 * 1024 || (size += bytes) > 64 * 1024 * 1024)
+                refuse("documents_unavailable_or_changed");
+        }
+        // Preservation observes private files only as opaque hashes. Their bytes
+        // never enter an evidence owner or the sanitized writer copy.
+        const protectedHashes = () => new Map(files.filter(entry => !evidenceAllowed(entry.path)).map(entry => {
+            let parent = root;
+            for (const part of entry.path.split("/").slice(0, -1)) {
+                parent = path.join(parent, part);
+                if (!fs.lstatSync(parent).isDirectory())
+                    refuse("linked_or_special_document");
+            }
+            return [memorySourceKey("workspace", entry.path), createHash("sha256")
+                    .update(readBoundedReleaseFile(path.join(root, entry.path), 16 * 1024 * 1024)).digest("hex")];
+        }));
+        const protectedBefore = protectedHashes();
+        const observed = ObservedMemorySources.capture({ workspace: root }, files.filter(entry => evidenceAllowed(entry.path))
+            .map(entry => ({ root: "workspace", path: entry.path })));
+        if (hybridDigest(inventory(root)) !== hybridDigest(initial))
+            refuse("inventory_changed_during_capture");
+        observed.revalidate();
+        if (hybridDigest([...protectedHashes()]) !== hybridDigest([...protectedBefore]))
+            refuse("inventory_changed_during_capture");
+        if (hybridDigest(inventory(root)) !== hybridDigest(initial))
+            refuse("inventory_changed_during_capture");
+        const hashes = new Map([...observed.hashes(), ...protectedBefore]), entries = initial.map(entry => ({ ...entry,
+            sha256: entry.kind === "file" ? hashes.get(memorySourceKey("workspace", entry.path)) : null }));
+        return { entries, observed, sha256: hybridDigest(entries) };
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "memory_repair_document_delta_invalid")
+            throw error;
+        return refuse("documents_unavailable_or_changed");
+    }
+}
+/** Physical MB-only observation, not provider/Session authority or permission to
+ * write the shared workspace. A registered owner must bind this start baseline,
+ * inspect the rest of its private workspace and journal bounded publication.
+ * It cannot use this helper alone to accept a Work or close a review finding.
+ */
+export class MemoryRepairDocumentBaseline {
+    sha256;
+    #entries;
+    #paths;
+    constructor(entries, paths) {
+        this.#entries = structuredClone(entries);
+        this.#paths = [...paths];
+        this.sha256 = hybridDigest({ entries, write_paths: paths });
+        Object.freeze(this);
+    }
+    static capture(workspace, writePaths) {
+        assertMemoryRepairWritePaths(writePaths);
+        const snapshot = capture(workspace), byPath = new Map(snapshot.entries.map(entry => [entry.path, entry]));
+        for (const logical of writePaths) {
+            if (byPath.get(logical)?.kind === "directory")
+                refuse("write_path_is_directory");
+            if (snapshot.entries.some(entry => alias(entry.path) === alias(logical) && entry.path !== logical))
+                refuse("aliased_write_path");
+            const parts = logical.split("/");
+            for (let index = 1; index < parts.length; index++) {
+                const parent = parts.slice(0, index).join("/");
+                if (byPath.get(parent)?.kind === "file" || snapshot.entries.some(entry => alias(entry.path) === alias(parent) && entry.path !== parent))
+                    refuse("invalid_write_parent");
+            }
+        }
+        return new MemoryRepairDocumentBaseline(snapshot.entries, writePaths);
+    }
+    entries() { return structuredClone(this.#entries); }
+    /** Adapt an independently accepted document view to the next registered
+     * Work's approved paths without re-capturing mutable workspace bytes.
+     * The caller still owns graph/current-view authority; this grants none.
+     */
+    withWritePaths(writePaths) {
+        assertMemoryRepairWritePaths(writePaths);
+        const value = { schema_id: "dd-flow/memory-repair-document-baseline@1", entries: this.entries(), write_paths: [...writePaths] };
+        return MemoryRepairDocumentBaseline.restore(Buffer.from(JSON.stringify(value)), hybridDigest({ entries: value.entries, write_paths: value.write_paths }));
+    }
+    /** Metadata composition only, never admission or filesystem publication.
+     * A caller must independently prove both retained views belong to a settled
+     * repair. Disjoint concurrent deltas preserve the current inventory; file
+     * conflicts never rebase. Identical new parent directories may be shared.
+     */
+    composeSettledDelta(before, after) {
+        if (!(before instanceof MemoryRepairDocumentBaseline) || !(after instanceof MemoryRepairDocumentBaseline)
+            || hybridDigest(before.#paths) !== hybridDigest(after.#paths))
+            refuse("invalid_settled_document_views");
+        const prior = new Map(before.#entries.map(entry => [entry.path, entry]));
+        const final = new Map(after.#entries.map(entry => [entry.path, entry]));
+        const current = new Map(this.#entries.map(entry => [entry.path, structuredClone(entry)]));
+        let changedFiles = 0;
+        for (const logical of new Set([...prior.keys(), ...final.keys()])) {
+            const old = prior.get(logical) ?? null, next = final.get(logical) ?? null;
+            if (hybridDigest(old) === hybridDigest(next))
+                continue;
+            const present = current.get(logical) ?? null;
+            if (next?.kind === "directory") {
+                if (old !== null || ![0o700, 0o755].includes(next.mode)
+                    || !after.#entries.some(entry => entry.kind === "file" && before.#paths.includes(entry.path) && entry.path.startsWith(`${logical}/`)))
+                    refuse("invalid_settled_directory_delta");
+                if (present !== null && hybridDigest(present) !== hybridDigest(next))
+                    refuse("settled_document_conflict");
+            }
+            else {
+                if (!before.#paths.includes(logical) || old?.kind === "directory" || next && next.kind !== "file"
+                    || next && (old ? next.mode !== old.mode : ![0o600, 0o644].includes(next.mode))
+                    || old && next && old.sha256 === next.sha256)
+                    refuse("invalid_settled_file_delta");
+                if (hybridDigest(present) !== hybridDigest(old))
+                    refuse("settled_document_conflict");
+                changedFiles++;
+            }
+            if (next)
+                current.set(logical, structuredClone(next));
+            else
+                current.delete(logical);
+        }
+        if (!changedFiles)
+            refuse("empty_settled_document_delta");
+        const entries = ordered(current.values()), value = { schema_id: "dd-flow/memory-repair-document-baseline@1", entries, write_paths: [...this.#paths] };
+        return MemoryRepairDocumentBaseline.restore(Buffer.from(JSON.stringify(value)), hybridDigest({ entries, write_paths: value.write_paths }));
+    }
+    /** Project only the independently selected regular files into a sanitized
+     * writer view. The protected source snapshot stays intact. This is metadata
+     * derivation, not file copying or authority to choose more source inputs.
+     */
+    exported(selected) {
+        if (!Array.isArray(selected) || selected.length > 20_000 || selected.some(logical => typeof logical !== "string"))
+            refuse("invalid_export_selection");
+        const byPath = new Map(this.#entries.map(entry => [entry.path, entry])), retained = new Set([".memory-bank"]);
+        const allowed = (logical) => logical.split("/").every(part => reviewEnvironmentAllowed(alias(part))
+            && ![".git", "node_modules", ".dd-flow"].includes(alias(part)));
+        const parents = (logical) => {
+            const parts = logical.split("/");
+            for (let index = 1; index < parts.length; index++) {
+                const parent = parts.slice(0, index).join("/");
+                if (byPath.get(parent)?.kind === "directory")
+                    retained.add(parent);
+            }
+        };
+        for (const logical of selected) {
+            if (!logical.startsWith(".memory-bank/") || logical.length > 4096 || logical.includes("\\") || logical.includes("\0")
+                || logical.split("/").some(part => !part || part === "." || part === ".."))
+                refuse("invalid_export_selection");
+            if (!allowed(logical))
+                continue;
+            if (byPath.get(logical)?.kind !== "file")
+                refuse("selected_export_file_missing");
+            if (retained.has(logical))
+                refuse("repeated_export_selection");
+            retained.add(logical);
+            parents(logical);
+        }
+        for (const logical of this.#paths) {
+            if (byPath.has(logical) && !retained.has(logical))
+                refuse("write_target_not_exported");
+            parents(logical);
+        }
+        const exported = new MemoryRepairDocumentBaseline(this.#entries.filter(entry => retained.has(entry.path)), this.#paths);
+        // Apply the same bounded, strict representation used by SQL restoration.
+        return MemoryRepairDocumentBaseline.restore(exported.bytes(), exported.sha256);
+    }
+    bytes() {
+        const bytes = Buffer.from(JSON.stringify({ schema_id: "dd-flow/memory-repair-document-baseline@1", entries: this.#entries, write_paths: this.#paths }));
+        if (bytes.length > 8 * 1024 * 1024)
+            refuse("unbounded_baseline_receipt");
+        return bytes;
+    }
+    /** Decode an independently retained receipt, not an agent result. The caller
+     * still has to prove SQL/start ownership of expectedSha256 before use.
+     */
+    static restore(bytes, expectedSha256) {
+        try {
+            if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 8 * 1024 * 1024
+                || typeof expectedSha256 !== "string" || !/^[a-f0-9]{64}$/.test(expectedSha256))
+                refuse("invalid_baseline_receipt");
+            const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+            if (!value || Object.keys(value).sort().join(",") !== "entries,schema_id,write_paths"
+                || value.schema_id !== "dd-flow/memory-repair-document-baseline@1" || !Array.isArray(value.entries)
+                || !value.entries.length || value.entries.length > 20_000)
+                refuse("invalid_baseline_receipt");
+            assertMemoryRepairWritePaths(value.write_paths);
+            const byPath = new Map(), aliases = new Set();
+            for (const entry of value.entries) {
+                if (!entry || Object.keys(entry).sort().join(",") !== "kind,mode,path,sha256"
+                    || typeof entry.path !== "string" || entry.path.length > 4096 || entry.path.split("/").length > 65
+                    || entry.path !== ".memory-bank" && !entry.path.startsWith(".memory-bank/")
+                    || entry.path.includes("\\") || entry.path.includes("\0") || entry.path.split("/").some(part => !part || part === "." || part === "..")
+                    || !["file", "directory"].includes(entry.kind) || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777
+                    || entry.kind === "directory" && entry.sha256 !== null
+                    || entry.kind === "file" && (typeof entry.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha256))
+                    || aliases.has(alias(entry.path)))
+                    refuse("invalid_baseline_receipt");
+                if (entry.path === ".memory-bank" ? byPath.size !== 0 || entry.kind !== "directory"
+                    : byPath.get(path.posix.dirname(entry.path))?.kind !== "directory")
+                    refuse("invalid_baseline_receipt");
+                aliases.add(alias(entry.path));
+                byPath.set(entry.path, entry);
+            }
+            for (const logical of value.write_paths) {
+                if (byPath.get(logical)?.kind === "directory" || value.entries.some((entry) => alias(entry.path) === alias(logical) && entry.path !== logical))
+                    refuse("invalid_baseline_receipt");
+                const parts = logical.split("/");
+                for (let index = 1; index < parts.length; index++) {
+                    const parent = parts.slice(0, index).join("/");
+                    if (byPath.get(parent)?.kind === "file" || value.entries.some((entry) => alias(entry.path) === alias(parent) && entry.path !== parent))
+                        refuse("invalid_baseline_receipt");
+                }
+            }
+            const prepared = new MemoryRepairDocumentBaseline(value.entries, value.write_paths);
+            if (prepared.sha256 !== expectedSha256 || !prepared.bytes().equals(Buffer.from(bytes)))
+                refuse("baseline_receipt_changed");
+            return prepared;
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_repair_document_delta_invalid")
+                throw error;
+            return refuse("invalid_baseline_receipt");
+        }
+    }
+    revalidate(workspace) {
+        if (hybridDigest(capture(workspace).entries) !== hybridDigest(this.#entries))
+            refuse("documents_changed_after_baseline");
+    }
+    /** Derive the protected shared-workspace transition from an authenticated
+     * private-copy observation. Excluded/private/canonical source entries are
+     * retained, never inferred from the sanitized execution copy. This is not
+     * permission to publish or settle a Work.
+     */
+    publicationTransition(exported, delta, startProtected = this) {
+        if (!ObservedMemoryRepairDelta.isObserved(delta))
+            refuse("physical_observation_required");
+        if (delta.baselineSha256 !== exported.sha256 || startProtected.exported(exported.entries().filter(entry => entry.kind === "file").map(entry => entry.path)).sha256 !== exported.sha256)
+            refuse("foreign_publication_baseline");
+        const before = new Map(this.#entries.map(entry => [entry.path, entry]));
+        const start = new Map(startProtected.entries().map(entry => [entry.path, entry]));
+        const visible = new Map(exported.entries().map(entry => [entry.path, entry]));
+        const observed = new Map(delta.afterEntries().map(entry => [entry.path, entry]));
+        const actions = [], added = new Set();
+        for (const change of delta.changes()) {
+            if (!this.#paths.includes(change.path) || (before.get(change.path)?.sha256 ?? null) !== change.before_sha256
+                || hybridDigest(before.get(change.path) ?? null) !== hybridDigest(start.get(change.path) ?? null))
+                refuse("foreign_publication_delta");
+            const next = observed.get(change.path) ?? null;
+            if ((next?.sha256 ?? null) !== change.after_sha256 || next && next.kind !== "file")
+                refuse("foreign_publication_delta");
+            if (next) {
+                const parts = change.path.split("/");
+                for (let length = 1; length < parts.length; length++) {
+                    const parent = parts.slice(0, length).join("/");
+                    const currentParent = before.get(parent), originalParent = start.get(parent);
+                    if (currentParent && (currentParent.kind !== "directory"
+                        || hybridDigest(currentParent) !== hybridDigest(originalParent ?? observed.get(parent) ?? null)))
+                        refuse("foreign_publication_parent");
+                    if (!before.has(parent) && !added.has(parent)) {
+                        const entry = observed.get(parent);
+                        if (visible.has(parent) || entry?.kind !== "directory")
+                            refuse("foreign_publication_parent");
+                        actions.push({ path: parent, before: null, after: entry });
+                        added.add(parent);
+                    }
+                }
+            }
+            actions.push({ path: change.path, before: before.get(change.path) ?? null, after: next });
+        }
+        const transition = new MemoryRepairDocumentTransition(transitionToken, this, delta, actions, startProtected.sha256);
+        // Apply the strict retained representation before a publication owner can
+        // register this expected view or perform any shared filesystem mutation.
+        transition.after();
+        return transition;
+    }
+    observeResult(workspace, result) {
+        const snapshot = capture(workspace), before = new Map(this.#entries.map(entry => [entry.path, entry]));
+        const after = new Map(snapshot.entries.map(entry => [entry.path, entry]));
+        const changed = [...new Set([...before.keys(), ...after.keys()])].sort().filter(logical => hybridDigest(before.get(logical) ?? null) !== hybridDigest(after.get(logical) ?? null));
+        const changes = [];
+        for (const logical of changed) {
+            const old = before.get(logical), current = after.get(logical);
+            if (old?.kind === "directory" || current?.kind === "directory") {
+                // Creating declared documents can create their parent directories; no
+                // unrelated empty directory, removed directory or chmod is a delta.
+                if (old || current?.kind !== "directory" || ![0o700, 0o755].includes(current.mode)
+                    || !result.changes.some(change => change.after_sha256 !== null && change.path.startsWith(`${logical}/`)))
+                    refuse("unregistered_directory_delta");
+                continue;
+            }
+            if (!this.#paths.includes(logical))
+                refuse("undeclared_document_delta");
+            if (old && current && old.mode !== current.mode || !old && current && ![0o600, 0o644].includes(current.mode))
+                refuse("document_mode_delta");
+            if (old?.sha256 === current?.sha256)
+                refuse("noncontent_document_delta");
+            changes.push({ path: logical, before_sha256: old?.sha256 ?? null, after_sha256: current?.sha256 ?? null });
+        }
+        const proposed = [...result.changes].sort((a, b) => a.path.localeCompare(b.path, "en"));
+        changes.sort((a, b) => a.path.localeCompare(b.path, "en"));
+        if (hybridDigest(changes) !== hybridDigest(proposed))
+            refuse("claimed_delta_differs_from_bytes");
+        if (result.outcome === "blocked" && changed.length || result.outcome === "accepted" && !changes.length)
+            refuse("outcome_differs_from_physical_delta");
+        return new ObservedMemoryRepairDelta(observationToken, this.sha256, workspace, snapshot.sha256, changes, snapshot.observed, snapshot.entries);
+    }
+}
+export class ObservedMemoryRepairDelta {
+    static isObserved(value) {
+        return typeof value === "object" && value !== null && #observed in value;
+    }
+    sha256;
+    baselineSha256;
+    #workspace;
+    #snapshotSha256;
+    #changes;
+    #observed;
+    #after;
+    constructor(token, baselineSha256, workspace, snapshotSha256, changes, observed, after) {
+        if (token !== observationToken)
+            refuse("physical_observation_required");
+        this.baselineSha256 = baselineSha256;
+        this.#workspace = workspace;
+        this.#snapshotSha256 = snapshotSha256;
+        this.#changes = structuredClone(changes);
+        this.#observed = observed;
+        this.#after = structuredClone(after);
+        this.sha256 = hybridDigest({ baseline_sha256: baselineSha256, snapshot_sha256: snapshotSha256, changes });
+        Object.freeze(this);
+    }
+    changes() { return structuredClone(this.#changes); }
+    afterEntries() { return structuredClone(this.#after); }
+    bytes(logical) {
+        if (!this.#changes.some(change => change.path === logical && change.after_sha256 !== null))
+            refuse("unselected_delta_bytes");
+        return this.#observed.bytes({ root: "workspace", path: logical });
+    }
+    revalidate() { if (capture(this.#workspace).sha256 !== this.#snapshotSha256)
+        refuse("documents_changed_after_delta"); }
+}
+/** Exact publication prefix model. A SQL/Session-owned publisher must admit
+ * the transition independently before applying these actions. This component
+ * only derives and observes views; it never mutates the shared workspace.
+ */
+export class MemoryRepairDocumentTransition {
+    sha256;
+    #before;
+    #delta;
+    #actions;
+    constructor(token, before, delta, actions, startProtectedSha256) {
+        if (token !== transitionToken)
+            refuse("publication_transition_required");
+        this.#before = before;
+        this.#delta = delta;
+        this.#actions = structuredClone(actions);
+        this.sha256 = hybridDigest({ before_sha256: before.sha256, start_protected_sha256: startProtectedSha256, delta_sha256: delta.sha256, actions });
+        Object.freeze(this);
+    }
+    actions() { return structuredClone(this.#actions); }
+    state(completed) {
+        if (!Number.isSafeInteger(completed) || completed < 0 || completed > this.#actions.length)
+            refuse("invalid_publication_cursor");
+        const entries = new Map(this.#before.entries().map(entry => [entry.path, entry]));
+        for (const action of this.#actions.slice(0, completed)) {
+            if (action.after)
+                entries.set(action.path, action.after);
+            else
+                entries.delete(action.path);
+        }
+        const retained = JSON.parse(this.#before.bytes().toString("utf8"));
+        const value = { ...retained, entries: ordered(entries.values()) };
+        const expected = hybridDigest({ entries: value.entries, write_paths: value.write_paths });
+        return MemoryRepairDocumentBaseline.restore(Buffer.from(JSON.stringify(value)), expected);
+    }
+    after() { return this.state(this.#actions.length); }
+    classify(workspace) {
+        const actual = capture(workspace), entries = new Map(actual.entries.map(entry => [entry.path, entry]));
+        let completed = 0, pending = false;
+        for (const action of this.#actions) {
+            const current = entries.get(action.path) ?? null;
+            if (hybridDigest(current) === hybridDigest(action.after)) {
+                if (pending)
+                    refuse("publication_not_known_prefix");
+                completed++;
+            }
+            else if (hybridDigest(current) === hybridDigest(action.before))
+                pending = true;
+            else
+                refuse("publication_not_known_prefix");
+        }
+        if (hybridDigest(actual.entries) !== hybridDigest(this.state(completed).entries()))
+            refuse("publication_not_known_prefix");
+        return { completed, total: this.#actions.length, status: completed === this.#actions.length ? "after" : completed === 0 ? "before" : "partial" };
+    }
+    bytes(logical) { return this.#delta.bytes(logical); }
+    revalidateDelta() { this.#delta.revalidate(); }
+}