@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.140

package/dist/services/memory-finish-integration.js

@@ -0,0 +1,280 @@
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { PreparedMemoryFinishReview } from "./memory-finish-handler.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { readMemoryInitGitPolicy } from "./memory-init-git-policy.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { observeReviewedMemoryGitIntegration, reviewedMemoryGitFiles } from "./memory-git-integration.js";
+import { createHash } from "node:crypto";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { spawnSync } from "node:child_process";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { readMemoryInitProjectBootstrap } from "./memory-init-project-bootstrap.js";
+import { readPublishedMemoryReferenceInventory } from "./memory-layer-publication.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { appendAudit } from "./audit.js";
+import fs from "node:fs";
+import path from "node:path";
+const token = Symbol("memory-finish-integration");
+function refuse(reason) {
+    throw new AppError("memory_finish_integration_invalid", "Finish lacks policy-bound reviewed Git integration", 2, { reason, effect: "no_effect" });
+}
+function retained(context, scope, bundle) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const frozen = bundle.execution.snapshot().scope;
+    const request = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const readiness = readMemoryInitBootstrapReadiness(context, request), policy = readMemoryInitGitPolicy(context, request);
+    if (!readiness || !policy || readiness.projectId !== scope.projectId
+        || readiness.authority.binding.execution_sha256 !== bundle.execution.sha256
+        || readiness.authority.binding.git_policy_sha256 !== hybridDigest(policy)
+        || policy.target_sha256 !== hybridDigest(readiness.authority.binding.target))
+        refuse("policy_bootstrap_binding_changed");
+    const selection = { projectRoot: request.projectRoot, workspaceRoot: request.workspaceRoot,
+        integrationBranch: policy.integration_branch, gitExecutable: readiness.authority.binding.target.tools.git };
+    const gitSha256 = readiness.authority.binding.target.tool_probes?.git.executable_sha256;
+    if (typeof gitSha256 !== "string" || !/^[a-f0-9]{64}$/.test(gitSha256))
+        refuse("pinned_git_executable_required");
+    return { readiness, policy, selection, gitSha256 };
+}
+function assertGitExecutable(selection, sha256) {
+    if (createHash("sha256").update(readBoundedReleaseFile(selection.gitExecutable, 64 * 1024 * 1024)).digest("hex") !== sha256)
+        refuse("pinned_git_executable_changed");
+}
+/** Physical Git operation only; callers must independently select accepted files
+ * and retain each mutation's intent. No ambient Git redirection or whole-tree add. */
+export function integrateReviewedMemoryFiles(selection, environment, references, runId, mutation, policy) {
+    const env = Object.fromEntries(Object.entries(environment).filter(([key]) => !key.startsWith("GIT_")));
+    const git = (directory, args, write = false, absent = false) => {
+        const result = spawnSync(selection.gitExecutable, ["-c", "core.fsmonitor=false", "-C", directory, ...args], { env, encoding: "utf8", timeout: 30000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        if (absent && !result.error && !result.signal && result.status !== 0)
+            return "";
+        if (result.error || result.signal || result.status !== 0)
+            throw new AppError("memory_finish_integration_invalid", write ? "Git integration did not return success; inspect the original operation before retrying" : "Git integration preparation failed", 2, { reason: "git_operation_failed", effect: write ? "unknown" : "no_effect", operation: args[0], stderr: result.stderr,
+                next_action: write ? "reconcile_original_integration" : "resolve_git_configuration_or_workspace" });
+        return result.stdout.trim();
+    };
+    const paths = references.map(ref => ref.path);
+    if (!paths.length || paths.length > 4096 || !paths.includes(".memory-bank/index.md") || new Set(paths).size !== paths.length
+        || references.some(ref => ref.root !== "workspace" || !(ref.path.startsWith(".memory-bank/") || ref.path === ".mb-lint.json")
+            || ref.path.split("/").some(part => !part || part === "." || part === "..") || /[\\\0]/.test(ref.path)
+            || !/^[a-f0-9]{64}$/.test(ref.sha256)))
+        refuse("invalid_owned_inventory");
+    const source = fs.realpathSync(selection.workspaceRoot), target = fs.realpathSync(selection.projectRoot);
+    const branch = git(source, ["symbolic-ref", "--short", "HEAD"]);
+    if (target === source ? branch !== selection.integrationBranch
+        : git(target, ["symbolic-ref", "--short", "HEAD"]) !== selection.integrationBranch)
+        refuse("integration_branch_changed");
+    const common = (directory) => fs.realpathSync(path.resolve(directory, git(directory, ["rev-parse", "--git-common-dir"])));
+    if (common(source) !== common(target))
+        refuse("foreign_repository");
+    if (policy && (common(source) !== policy.repository || branch !== policy.workspace_branch))
+        refuse("policy_repository_or_branch_changed");
+    const observed = ObservedMemorySources.capture({ workspace: source }, references.map(({ root, path }) => ({ root, path })));
+    const hashes = observed.hashes();
+    for (const ref of references)
+        if (hashes.get(memorySourceKey(ref.root, ref.path)) !== ref.sha256)
+            refuse("reviewed_workspace_bytes_changed");
+    try {
+        return observeReviewedMemoryGitIntegration(selection, environment, references);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "memory_git_integration_invalid")
+            throw error;
+    }
+    const visibility = git(source, ["ls-files", "-v", "--", ...paths]);
+    if (visibility.split("\n").filter(Boolean).some(line => !line.startsWith("H ")))
+        refuse("owned_index_visibility_override");
+    if (git(source, ["diff", "--name-only", "--diff-filter=U"]))
+        refuse("unmerged_workspace");
+    const sourceHead = git(source, ["rev-parse", "--verify", "HEAD"], false, true);
+    if (source !== target) {
+        const targetHead = git(target, ["rev-parse", "HEAD"]), base = git(source, ["merge-base", targetHead, sourceHead]);
+        const changes = git(source, ["diff", "--name-only", "-z", base, sourceHead]).split("\0").filter(Boolean);
+        if (changes.some(logical => !paths.includes(logical)))
+            refuse("feature_contains_unowned_changes");
+        if (git(target, ["diff", "--cached", "--name-only"]) || git(target, ["diff", "--name-only", "--diff-filter=U"]))
+            refuse("integration_target_index_not_clean");
+    }
+    const needsCommit = references.some(ref => {
+        const bytes = spawnSync(selection.gitExecutable, ["-C", source, "cat-file", "blob", `HEAD:${ref.path}`], { env, timeout: 10000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        return bytes.status !== 0 || createHash("sha256").update(bytes.stdout).digest("hex") !== ref.sha256;
+    });
+    if (needsCommit) {
+        git(source, ["var", "GIT_AUTHOR_IDENT"]);
+        git(source, ["var", "GIT_COMMITTER_IDENT"]);
+        mutation("commit", sourceHead, () => {
+            observed.revalidate();
+            if (git(source, ["rev-parse", "--verify", "HEAD"], false, true) !== sourceHead
+                || git(source, ["symbolic-ref", "--short", "HEAD"]) !== branch)
+                refuse("source_git_baseline_changed");
+            git(source, ["add", "-f", "--", ...paths], true);
+            git(source, ["commit", "--only", "-m", `chore(${runId.toLowerCase()}): integrate reviewed Memory Bank`, "--", ...paths], true);
+        });
+    }
+    observed.revalidate();
+    if (source !== target) {
+        const head = git(source, ["rev-parse", "HEAD"]), targetHead = git(target, ["rev-parse", "HEAD"]);
+        if (head !== targetHead) {
+            mutation("merge", targetHead, () => {
+                if (git(target, ["rev-parse", "HEAD"]) !== targetHead
+                    || git(target, ["symbolic-ref", "--short", "HEAD"]) !== selection.integrationBranch
+                    || git(target, ["diff", "--cached", "--name-only"]))
+                    refuse("target_git_baseline_changed");
+                git(target, ["merge", "--no-edit", "--no-autostash", head], true);
+            });
+        }
+    }
+    return observeReviewedMemoryGitIntegration(selection, environment, references);
+}
+/** The admitted Memory finish operation. A retained intent never licenses a
+ * second dispatch: replay first observes completed Git effects, or reports unknown. */
+export function integrateMemoryFinish(context, input) {
+    if (!(input.bundle instanceof RetainedExecutionBundle) || input.bundle.descriptor.descriptor.id !== "mb-init")
+        refuse("registered_memory_bundle_required");
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const stageScope = { ...input.scope, stage: "finish" };
+    readDescriptorStageInput(context, stageScope, input.bundle);
+    const review = PreparedMemoryFinishReview.prepare(context, input);
+    const selected = context.db.readSnapshot(() => retained(context, input.scope, input.bundle));
+    const request = { requestId: selected.policy.scope.requestId, projectRoot: selected.selection.projectRoot,
+        workspaceRoot: selected.selection.workspaceRoot };
+    const bootstrap = readMemoryInitProjectBootstrap(context, request);
+    if (!bootstrap)
+        refuse("accepted_bootstrap_required");
+    const published = readPublishedMemoryReferenceInventory(context.ddFlowHome, { ...request, targetSha256: bootstrap.receipt.target_sha256,
+        layerSha256: bootstrap.receipt.layer_sha256, installationSha256: selected.readiness.authority.binding.installation_manifest_sha256,
+        packSha256: selected.readiness.authority.binding.pack_sha256 }, selected.readiness.authority.binding.target, bootstrap.receipt.layer_publication_sha256, bootstrap.receipt.draft_identity_sha256);
+    const files = new Map(reviewedMemoryGitFiles(review.reviewedSources(context)).map(ref => [ref.path, ref]));
+    for (const [logical, sha256] of published.artifacts) {
+        const ref = { root: "workspace", path: logical, sha256 };
+        if (files.has(ref.path)) {
+            if (published.canon.has(logical.slice(".memory-bank/".length)) && files.get(ref.path).sha256 !== ref.sha256)
+                refuse("selected_canon_changed");
+        }
+        else
+            files.set(ref.path, ref);
+    }
+    const references = [...files.values()].sort((a, b) => a.path.localeCompare(b.path, "en"));
+    const identity = hybridDigest({ scope: input.scope, bundle: input.bundle.sha256, policy: selected.policy,
+        review: review.bytes().toString("base64"), references });
+    const events = context.db.all(`SELECT payload_json FROM audit_events WHERE project_id=?
+    AND event_type='memory.finish_integration_intent' AND json_extract(payload_json,'$.run_id')=?`, [input.scope.projectId, input.scope.runId]);
+    const intents = events.map(row => JSON.parse(row.payload_json));
+    if (intents.length > 2 || intents.some(value => value.identity !== identity))
+        refuse("integration_intent_changed");
+    assertGitExecutable(selected.selection, selected.gitSha256);
+    if (intents.length) {
+        try {
+            observeReviewedMemoryGitIntegration(selected.selection, context.env, references);
+            const accepted = PreparedMemoryFinishIntegration.prepare(context, input);
+            return { integrated: true, replayed: true, integration: accepted.value() };
+        }
+        catch (error) {
+            const commit = intents.length === 1 && intents[0].phase === "commit" ? intents[0] : null;
+            const result = spawnSync(selected.selection.gitExecutable, ["-C", selected.selection.workspaceRoot, "log", "-1", "--format=%P%n%s"], { env: Object.fromEntries(Object.entries(context.env).filter(([key]) => !key.startsWith("GIT_"))), encoding: "utf8", timeout: 10000 });
+            // Only a physically completed original scoped commit can continue to the
+            // not-yet-issued merge. Never rerun a commit or unresolved merge intent.
+            if (!commit || result.status !== 0 || result.stdout.trim() !== `${commit.baseline}\nchore(${input.scope.runId.toLowerCase()}): integrate reviewed Memory Bank`.trim()
+                || selected.selection.workspaceRoot === selected.selection.projectRoot)
+                throw new AppError("memory_finish_integration_pending", "Original integration has not been physically proven; do not redispatch Git mutations", 1, { effect: "unknown", next_action: "reconcile_original_integration", cause: error instanceof AppError ? error.details.reason : "observation_failed" });
+        }
+    }
+    let dispatched = false;
+    try {
+        const integration = integrateReviewedMemoryFiles(selected.selection, context.env, references, input.scope.runId, (phase, baseline, action) => {
+            if (intents.some(value => value.phase === phase))
+                throw new AppError("memory_finish_integration_pending", "Original Git mutation remains unresolved", 1, { effect: "unknown", next_action: "reconcile_original_integration" });
+            review.revalidate(context);
+            assertGitExecutable(selected.selection, selected.gitSha256);
+            context.db.writeTransaction(() => {
+                readDescriptorStageInput(context, stageScope, input.bundle);
+                review.assertCustody(context);
+                if (hybridDigest(retained(context, input.scope, input.bundle)) !== hybridDigest(selected))
+                    refuse("integration_custody_changed");
+                const current = context.db.all(`SELECT payload_json FROM audit_events WHERE project_id=?
+        AND event_type='memory.finish_integration_intent' AND json_extract(payload_json,'$.run_id')=?`, [input.scope.projectId, input.scope.runId])
+                    .map(row => JSON.parse(row.payload_json));
+                if (current.some(value => value.identity !== identity || value.phase === phase) || current.length > 1)
+                    throw new AppError("memory_finish_integration_pending", "The original Git mutation already has an owner; observe its effect without redispatch", 1, { effect: "unknown", next_action: "reconcile_original_integration" });
+                appendAudit(context, { projectId: input.scope.projectId, eventType: "memory.finish_integration_intent",
+                    payload: { run_id: input.scope.runId, identity, phase, baseline } });
+            }, "memoryFinish.integrate");
+            dispatched = true;
+            action();
+        }, selected.policy);
+        return { integrated: true, replayed: false, integration };
+    }
+    catch (error) {
+        if (!dispatched)
+            throw error;
+        throw new AppError("memory_finish_integration_pending", "The retained original Git operation requires physical reconciliation; do not redispatch", 1, { effect: "unknown", next_action: "reconcile_original_integration", cause: error instanceof AppError ? error.details.reason : "git_operation_failed" });
+    }
+}
+/** Fresh terminal integration proof: independent accepted review + explicit
+ * retained policy/bootstrap + exact committed reviewed MB bytes. Read-only:
+ * no Git integration is performed and no normal-flow readiness, Stage/RUN
+ * completion, permission or historical replay authority is granted here. */
+export class PreparedMemoryFinishIntegration {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #review in value;
+    }
+    #scope;
+    #bundle;
+    #review;
+    #retainedSha256;
+    #selection;
+    #observation;
+    #gitSha256;
+    constructor(key, scope, bundle, review, selected, observation) {
+        if (key !== token)
+            refuse("finish_integration_token_required");
+        this.#scope = { ...scope };
+        this.#bundle = bundle;
+        this.#review = review;
+        this.#retainedSha256 = hybridDigest(selected);
+        this.#selection = structuredClone(selected.selection);
+        this.#observation = structuredClone(observation);
+        this.#gitSha256 = selected.gitSha256;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bundle instanceof RetainedExecutionBundle) || input.bundle.descriptor.descriptor.id !== "mb-init")
+            refuse("registered_memory_bundle_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        const review = PreparedMemoryFinishReview.prepare(context, input);
+        const selected = context.db.readSnapshot(() => retained(context, input.scope, input.bundle));
+        const references = reviewedMemoryGitFiles(review.reviewedSources(context));
+        assertGitExecutable(selected.selection, selected.gitSha256);
+        const observation = observeReviewedMemoryGitIntegration(selected.selection, context.env, references);
+        assertGitExecutable(selected.selection, selected.gitSha256);
+        if (observation.repository !== selected.policy.repository || observation.workspace_branch !== selected.policy.workspace_branch)
+            refuse("policy_repository_or_branch_changed");
+        const prepared = new PreparedMemoryFinishIntegration(token, input.scope, input.bundle, review, selected, observation);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    value() { return structuredClone(this.#observation); }
+    /** SQL-only writer fence; physical observation must precede the writer. */
+    assertCustody(context) {
+        this.#review.assertCustody(context);
+        if (hybridDigest(retained(context, this.#scope, this.#bundle)) !== this.#retainedSha256)
+            refuse("finish_integration_custody_changed");
+    }
+    revalidate(context) {
+        const review = this.#review;
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_revalidation_outside_writer_required");
+        review.revalidate(context);
+        this.assertCustody(context);
+        const references = reviewedMemoryGitFiles(this.#review.reviewedSources(context));
+        assertGitExecutable(this.#selection, this.#gitSha256);
+        if (hybridDigest(observeReviewedMemoryGitIntegration(this.#selection, context.env, references)) !== hybridDigest(this.#observation))
+            refuse("finish_integration_observation_changed");
+        assertGitExecutable(this.#selection, this.#gitSha256);
+        this.assertCustody(context);
+    }
+}

package/dist/services/memory-finish-readiness.js

@@ -0,0 +1,122 @@
+var _a;
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { PreparedMemoryFinishIntegration } from "./memory-finish-integration.js";
+import { PreparedMemoryFinishReview } from "./memory-finish-handler.js";
+import { observeMemoryNormalFlowEntry } from "./memory-normal-flow-entry.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { readMemoryInitProjectBootstrap } from "./memory-init-project-bootstrap.js";
+import { readRetainedMemoryLayer } from "./memory-layer-publication.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const token = Symbol("memory-finish-readiness");
+function refuse(reason) {
+    throw new AppError("memory_finish_readiness_invalid", "Finish lacks reviewed ordinary-flow readiness", 2, { reason, effect: "no_effect" });
+}
+function accepted(context, scope, bundle) {
+    const frozen = bundle.execution.snapshot().scope;
+    const request = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const bootstrap = readMemoryInitBootstrapReadiness(context, request), registration = readMemoryInitProjectBootstrap(context, request);
+    if (!bootstrap || !registration || bootstrap.projectId !== scope.projectId
+        || bootstrap.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_bootstrap_required");
+    return { request, bootstrap, registration };
+}
+function tools(selected) {
+    const target = selected.bootstrap.authority.binding.target;
+    for (const name of ["git", "wt", "mb-lint"]) {
+        const expected = target.tool_probes?.[name].executable_sha256;
+        if (!expected || createHash("sha256").update(readBoundedReleaseFile(target.tools[name], 64 * 1024 * 1024)).digest("hex") !== expected)
+            refuse("selected_tool_changed");
+    }
+}
+/** Fresh readiness requires accepted final review, integrated reviewed bytes,
+ * unchanged selected canonical pack/tools and real ordinary SPECIFY preparation
+ * from the integration checkout. It does not execute the future task or seal a
+ * Stage/RUN; historical replay must use independently committed evidence. */
+export class PreparedMemoryFinishReadiness {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #integration in value;
+    }
+    #scope;
+    #bundle;
+    #integration;
+    #review;
+    #acceptedSha256;
+    #value;
+    constructor(key, scope, bundle, integration, review, acceptedSha256, value) {
+        if (key !== token)
+            refuse("readiness_token_required");
+        this.#scope = { ...scope };
+        this.#bundle = bundle;
+        this.#integration = integration;
+        this.#review = review;
+        this.#acceptedSha256 = acceptedSha256;
+        this.#value = structuredClone(value);
+        Object.freeze(this);
+    }
+    static observe(context, scope, bundle, review, integration) {
+        const selected = context.db.readSnapshot(() => accepted(context, scope, bundle));
+        tools(selected);
+        const layer = readRetainedMemoryLayer(context.ddFlowHome, { ...selected.request,
+            targetSha256: selected.registration.receipt.target_sha256, layerSha256: selected.registration.receipt.layer_sha256,
+            installationSha256: selected.bootstrap.authority.binding.installation_manifest_sha256 });
+        if (layer.packSha256 !== selected.bootstrap.authority.binding.pack_sha256)
+            refuse("selected_pack_changed");
+        const files = layer.files();
+        for (const root of new Set([selected.request.projectRoot, selected.request.workspaceRoot])) {
+            const observed = ObservedMemorySources.capture({ project: root }, [...files.keys()].map(logical => ({ root: "project", path: `.memory-bank/${logical}` })));
+            const hashes = observed.hashes();
+            for (const [logical, bytes] of files)
+                if (hashes.get(memorySourceKey("project", `.memory-bank/${logical}`)) !== createHash("sha256").update(bytes).digest("hex"))
+                    refuse("installed_pack_bytes_changed");
+            observed.revalidate();
+        }
+        const entry = observeMemoryNormalFlowEntry(context, selected.request.projectRoot);
+        const reviewed = new Map(review.reviewedSources(context).filter(ref => ref.root === "workspace").map(ref => [ref.path, ref.sha256]));
+        for (const source of entry.sources) {
+            const canonical = files.get(source.path.slice(".memory-bank/".length));
+            if (canonical ? createHash("sha256").update(canonical).digest("hex") !== source.sha256 : reviewed.get(source.path) !== source.sha256)
+                refuse("entry_source_not_reviewed_or_selected_canon");
+        }
+        tools(selected);
+        integration.revalidate(context);
+        review.assertCustody(context);
+        return { schema_id: "dd-flow/memory-finish-readiness-observation@1", scope: { ...scope },
+            bundle_sha256: bundle.sha256, execution_sha256: bundle.execution.sha256,
+            bootstrap_authority_sha256: hybridDigest(selected.bootstrap.authority), pack_sha256: layer.packSha256,
+            integration: integration.value(), entry, readiness: "entry_prepared", model_access: "unknown" };
+    }
+    static prepare(context, input) {
+        if (!(input.bundle instanceof RetainedExecutionBundle) || input.bundle.descriptor.descriptor.id !== "mb-init")
+            refuse("registered_memory_bundle_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        const integration = PreparedMemoryFinishIntegration.prepare(context, input), review = PreparedMemoryFinishReview.prepare(context, input);
+        const selected = context.db.readSnapshot(() => accepted(context, input.scope, input.bundle));
+        const value = this.observe(context, input.scope, input.bundle, review, integration);
+        const prepared = new _a(token, input.scope, input.bundle, integration, review, hybridDigest(selected), value);
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    value() { return structuredClone(this.#value); }
+    assertCustody(context) {
+        this.#integration.assertCustody(context);
+        this.#review.assertCustody(context);
+        if (hybridDigest(accepted(context, this.#scope, this.#bundle)) !== this.#acceptedSha256)
+            refuse("readiness_custody_changed");
+    }
+    revalidate(context) {
+        const integration = this.#integration;
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_revalidation_outside_writer_required");
+        this.assertCustody(context);
+        if (hybridDigest(_a.observe(context, this.#scope, this.#bundle, this.#review, integration)) !== hybridDigest(this.#value))
+            refuse("ordinary_readiness_changed");
+        this.assertCustody(context);
+    }
+}
+_a = PreparedMemoryFinishReadiness;

package/dist/services/memory-git-integration.js

@@ -0,0 +1,151 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+/** One reviewed inventory for fresh Git observation and historical terminal custody. */
+export function reviewedMemoryGitFiles(refs) {
+    return refs.filter(ref => ref.root === "workspace" && (ref.path.startsWith(".memory-bank/") || ref.path === ".mb-lint.json"))
+        .map(ref => ({ root: "workspace", path: ref.path, sha256: ref.sha256 }))
+        .sort((a, b) => a.path.localeCompare(b.path, "en"));
+}
+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";
+function refuse(reason) {
+    throw new AppError("memory_git_integration_invalid", "Memory finish lacks observed Git integration", 2, { reason, effect: "no_effect" });
+}
+function root(value) {
+    if (typeof value !== "string" || !path.isAbsolute(value))
+        refuse("absolute_root_required");
+    try {
+        const resolved = fs.realpathSync(value);
+        if (!fs.statSync(resolved).isDirectory())
+            refuse("repository_root_required");
+        return resolved;
+    }
+    catch {
+        return refuse("repository_root_unavailable");
+    }
+}
+/** Read-only physical observation, NOT policy selection, accepted MB content,
+ * full owned-file coverage or SQL/Stage authority. The finish owner must bind
+ * this selection to retained project policy and independently reviewed bytes.
+ * No checkout, commit, merge, push, tool repair or configuration mutation. */
+export function observeMemoryGitIntegration(input, env) {
+    if (!input || typeof input.integrationBranch !== "string" || !input.integrationBranch
+        || input.integrationBranch.length > 1024 || [...input.integrationBranch].some(character => character.charCodeAt(0) <= 32 || character.charCodeAt(0) === 127)
+        || input.integrationBranch.startsWith("-") || typeof input.gitExecutable !== "string"
+        || !path.isAbsolute(input.gitExecutable))
+        refuse("explicit_git_selection_required");
+    const projectRoot = root(input.projectRoot), workspaceRoot = root(input.workspaceRoot);
+    const cleanEnv = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("GIT_")));
+    const git = (directory, args, expectedStatus = 0) => {
+        const result = spawnSync(input.gitExecutable, ["-c", "core.fsmonitor=false", "-c", "core.untrackedCache=false",
+            "-C", directory, ...args], { env: { ...cleanEnv, GIT_OPTIONAL_LOCKS: "0" }, encoding: "utf8",
+            timeout: 10000, maxBuffer: 2 * 1024 * 1024, windowsHide: true, shell: false });
+        if (result.error || result.signal || result.status !== expectedStatus)
+            refuse("git_observation_failed");
+        return result.stdout;
+    };
+    const integrationRef = `refs/heads/${input.integrationBranch}`;
+    git(projectRoot, ["check-ref-format", integrationRef]);
+    for (const directory of [projectRoot, workspaceRoot]) {
+        if (git(directory, ["rev-parse", "--is-bare-repository"]).trim() !== "false"
+            || root(git(directory, ["rev-parse", "--show-toplevel"]).trim()) !== directory)
+            refuse("not_repository_root");
+    }
+    const common = (directory) => root(path.resolve(directory, git(directory, ["rev-parse", "--git-common-dir"]).trim()));
+    const repository = common(projectRoot);
+    if (common(workspaceRoot) !== repository)
+        refuse("foreign_workspace_repository");
+    const workspaceBranch = git(workspaceRoot, ["symbolic-ref", "--short", "HEAD"]).trim();
+    const head = git(workspaceRoot, ["rev-parse", "--verify", "HEAD^{commit}"]).trim();
+    const integrationHead = git(projectRoot, ["rev-parse", "--verify", `${integrationRef}^{commit}`]).trim();
+    if (![head, integrationHead].every(value => /^[a-f0-9]{40,64}$/.test(value)))
+        refuse("invalid_commit_identity");
+    // status intentionally trusts index visibility flags. Do not accept that
+    // trust for MB readiness or mutate the user's index to clear those flags.
+    const visibility = git(workspaceRoot, ["ls-files", "-v", "-z", "--", ".memory-bank"]);
+    if (visibility.split("\0").filter(Boolean).some(entry => !entry.startsWith("H ")))
+        refuse("memory_index_visibility_override");
+    const status = git(workspaceRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ".memory-bank"]);
+    if (status)
+        refuse("memory_bank_not_committed");
+    const index = git(workspaceRoot, ["ls-files", "--stage", "-z", "--", ".memory-bank/index.md"]);
+    if (!/^100644 [a-f0-9]{40,64} 0\t\.memory-bank\/index\.md\0$/.test(index))
+        refuse("tracked_memory_bank_index_required");
+    // Failure is a typed refusal; neither an unmerged feature nor an unborn
+    // branch can become an accepted integration by supplying its own hash.
+    git(projectRoot, ["merge-base", "--is-ancestor", head, integrationHead]);
+    const workspaceMemoryTree = git(workspaceRoot, ["rev-parse", "--verify", `${head}:.memory-bank`]).trim();
+    const integrationMemoryTree = git(projectRoot, ["rev-parse", "--verify", `${integrationHead}:.memory-bank`]).trim();
+    if (!/^[a-f0-9]{40,64}$/.test(workspaceMemoryTree) || workspaceMemoryTree !== integrationMemoryTree)
+        refuse("integrated_memory_tree_changed");
+    return { schema_id: "dd-flow/memory-git-integration-observation@1", project_root: projectRoot,
+        workspace_root: workspaceRoot, repository, workspace_branch: workspaceBranch, integration_ref: integrationRef, workspace_head: head,
+        integration_head: integrationHead, memory_tree: workspaceMemoryTree,
+        tracked_index_entry_sha256: hybridDigest(index), memory_index_visibility_sha256: hybridDigest(visibility),
+        memory_status_sha256: hybridDigest(status) };
+}
+/** Exact reviewed MB/owned root lint bytes in the physical workspace and integrated Git
+ * tree. References must be selected by the accepted review owner; this helper
+ * validates physical correspondence only and grants no semantic authority. */
+export function observeReviewedMemoryGitIntegration(input, env, references) {
+    if (!Array.isArray(references) || !references.length || references.length > 4096
+        || references.some(ref => !ref || ref.root !== "workspace" || typeof ref.path !== "string"
+            || !(ref.path.startsWith(".memory-bank/") || ref.path === ".mb-lint.json") || ref.path.length > 4096 || ref.path.includes("\\") || ref.path.includes("\0")
+            || ref.path.split("/").some((segment) => !segment || segment === "." || segment === "..")
+            || typeof ref.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(ref.sha256)
+            || Object.keys(ref).sort().join() !== "path,root,sha256")
+        || new Set(references.map(ref => ref.path)).size !== references.length
+        || !references.some(ref => ref.path === ".memory-bank/index.md"))
+        refuse("invalid_reviewed_memory_inventory");
+    const selected = structuredClone([...references]).sort((a, b) => a.path.localeCompare(b.path, "en"));
+    const integration = observeMemoryGitIntegration(input, env);
+    const observed = ObservedMemorySources.capture({ workspace: integration.workspace_root }, selected.map(({ root, path }) => ({ root, path })));
+    const hashes = observed.hashes();
+    const cleanEnv = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("GIT_")));
+    const git = (args, directory = integration.workspace_root) => {
+        const result = spawnSync(input.gitExecutable, ["-c", "core.fsmonitor=false", "-c", "core.untrackedCache=false",
+            "-C", directory, ...args], { env: { ...cleanEnv, GIT_OPTIONAL_LOCKS: "0" },
+            timeout: 10000, maxBuffer: 16 * 1024 * 1024, windowsHide: true, shell: false });
+        if (result.error || result.signal || result.status !== 0)
+            refuse("reviewed_git_blob_unavailable");
+        return result.stdout;
+    };
+    let total = 0;
+    for (const ref of selected) {
+        if (hashes.get(memorySourceKey("workspace", ref.path)) !== ref.sha256)
+            refuse("reviewed_workspace_bytes_changed");
+        const entry = git(["ls-tree", "-z", integration.workspace_head, "--", ref.path]).toString("utf8");
+        const separator = entry.indexOf("\t");
+        if (separator < 0 || !/^100644 blob [a-f0-9]{40,64}$/.test(entry.slice(0, separator))
+            || entry.slice(separator + 1) !== `${ref.path}\0`)
+            refuse("reviewed_regular_git_blob_required");
+        const content = git(["cat-file", "blob", `${integration.workspace_head}:${ref.path}`]);
+        total += content.length;
+        if (total > 64 * 1024 * 1024)
+            refuse("reviewed_git_bytes_exceed_bound");
+        if (createHash("sha256").update(content).digest("hex") !== ref.sha256)
+            refuse("reviewed_git_bytes_changed");
+        if (ref.path === ".mb-lint.json") {
+            for (const root of new Set([integration.workspace_root, integration.project_root])) {
+                const visibility = git(["ls-files", "-v", "-z", "--", ref.path], root).toString("utf8");
+                if (visibility !== `H ${ref.path}\0`)
+                    refuse("lint_configuration_index_visibility_override");
+                const source = ObservedMemorySources.capture({ workspace: root }, [{ root: "workspace", path: ref.path }]);
+                if (source.hashes().get(memorySourceKey("workspace", ref.path)) !== ref.sha256)
+                    refuse("integrated_lint_configuration_changed");
+                source.revalidate();
+            }
+            const integrated = git(["cat-file", "blob", `${integration.integration_head}:${ref.path}`], integration.project_root);
+            if (createHash("sha256").update(integrated).digest("hex") !== ref.sha256)
+                refuse("integrated_lint_configuration_changed");
+        }
+    }
+    observed.revalidate();
+    if (hybridDigest(observeMemoryGitIntegration(input, env)) !== hybridDigest(integration))
+        refuse("integration_changed_during_observation");
+    return { ...integration, reviewed_files_sha256: hybridDigest(selected) };
+}