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

package/dist/services/memory-init-controller-start.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { validateMemoryInitStartupScope, readMemoryInitStartupInput } from "./memory-init-startup-custody.js";
+import { startMemoryInitRun } from "./memory-init-start.js";
+import { startMemoryUpgradeRun } from "./memory-upgrade-start.js";
+import { requireProjectByRoot } from "./projects.js";
+import { readRunStartRequest } from "./run-start-custody.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { requireRun } from "./run-controller-state.js";
+import { prepareRunControllerLaunch } from "./run-controller.js";
+import { prepareMemoryInitContextsFromStartup, publishMemoryInitContexts, prepareMemoryUpgradeContextsFromStartup, publishMemoryUpgradeContexts } from "./memory-init-contexts.js";
+import { parseRuntimeBudget } from "./runtime-budget.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { startDiagnosticRun } from "./diagnostic-start.js";
+import { prepareDiagnosticContextsFromRequest, publishDiagnosticContexts } from "./memory-init-contexts.js";
+function refuse(reason) {
+    throw new AppError("memory_init_controller_start_invalid", "Init controller requires its exact published startup request", 1, { reason, effect: "no_effect", next_action: "reconcile_exact_request" });
+}
+/** Bridge the already published logical RUN to the existing controller. The
+ * RUN-start owner admits the root; startup custody supplies the objective.
+ * An existing controller replays before candidate publication, so missing
+ * productive inputs are never reconstructed here. No process is launched. */
+export function prepareMemoryInitControllerStart(context, scope) {
+    return prepareMemoryControllerStart(context, scope, "mb-init");
+}
+export function prepareMemoryUpgradeControllerStart(context, scope) {
+    return prepareMemoryControllerStart(context, scope, "mb-upgrade");
+}
+export function prepareDiagnosticControllerStart(context, scope, flowId) {
+    return prepareMemoryControllerStart(context, scope, flowId);
+}
+function prepareMemoryControllerStart(context, scope, flowId) {
+    validateMemoryInitStartupScope(scope);
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    parseRuntimeBudget(context.env.DD_FLOW_RUNTIME_BUDGET);
+    if (flowId === "mb-init") {
+        const startup = readMemoryInitStartupInput(context, scope);
+        if (!startup || !["dd-flow/memory-init-startup-input@2", "dd-flow/memory-init-startup-input@3"].includes(startup.payload.schema_id))
+            refuse("retained_objective_required");
+    }
+    const project = requireProjectByRoot(context, scope.projectRoot);
+    const request = readRunStartRequest(context, project.id, scope.requestId);
+    if (!request?.published || request.payload.initial_index.flow_kind !== flowId
+        || request.payload.workspace_root !== scope.workspaceRoot)
+        refuse("published_run_required");
+    // Restores the exact request and verifies independent SQL/physical root
+    // ownership without consulting current canon/profiles or creating a RUN.
+    const started = isDiagnosticFlow(flowId) ? startDiagnosticRun(context, { projectRoot: scope.projectRoot, requestId: scope.requestId, flowId })
+        : flowId === "mb-init" ? startMemoryInitRun(context, scope) : startMemoryUpgradeRun(context, scope);
+    const run = requireRun(context, project.id, started.runId);
+    const bundle = readFlowRunExecutionBundle(context, { projectRoot: scope.projectRoot, runId: run.id });
+    if (!bundle || bundle.sha256 !== started.bundleSha256)
+        refuse("retained_bundle_required");
+    if (bundle.execution.settings.execution !== "managed")
+        refuse("managed_execution_required");
+    const contexts = isDiagnosticFlow(flowId) ? prepareDiagnosticContextsFromRequest(context, bundle, run.run_root)
+        : flowId === "mb-init" ? prepareMemoryInitContextsFromStartup(context, bundle, run.run_root)
+            : prepareMemoryUpgradeContextsFromStartup(context, bundle, run.run_root);
+    const input = { projectRoot: scope.projectRoot, runId: run.id, requestId: scope.requestId,
+        contextFile: contexts.file, contextSha256: contexts.sha256 };
+    const controllers = context.db.get("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='run_controllers'")
+        ? context.db.all("SELECT request_id FROM run_controllers WHERE project_id=? AND run_id=?", [project.id, run.id]) : [];
+    if (controllers.some(row => row.request_id === scope.requestId))
+        return { input, prepared: prepareRunControllerLaunch(context, input) };
+    if (controllers.length)
+        refuse("foreign_controller_request");
+    // A directory without a receipt is an interrupted/unknown outcome, not
+    // evidence that no owner ran. Do not create another physical controller.
+    let controllerRootFound = false;
+    try {
+        fs.lstatSync(path.join(run.run_root, "controllers"));
+        controllerRootFound = true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (controllerRootFound)
+        refuse("controller_custody_missing");
+    if (context.db.get("SELECT 1 FROM sessions WHERE project_id=? AND run_id=? LIMIT 1", [project.id, run.id]))
+        refuse("session_owner_requires_reconciliation");
+    const rootOwner = context.db.readSnapshot(() => {
+        if (readRunStartRequest(context, project.id, scope.requestId)?.sha256 !== request.sha256)
+            refuse("run_request_changed");
+        const row = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.start_root_owned' AND json_extract(payload_json,'$.run_id')=?", [project.id, run.id]);
+        if (!row)
+            refuse("root_owner_missing");
+        return JSON.parse(row.payload_json).owner;
+    });
+    if (!rootOwner || !Number.isSafeInteger(rootOwner.dev) || !Number.isSafeInteger(rootOwner.ino))
+        refuse("root_owner_changed");
+    const publish = isDiagnosticFlow(flowId) ? publishDiagnosticContexts : flowId === "mb-init" ? publishMemoryInitContexts : publishMemoryUpgradeContexts;
+    publish(bundle, contexts.objective, run.run_root, contexts.sha256, rootOwner);
+    try {
+        return { input, prepared: prepareRunControllerLaunch(context, input) };
+    }
+    catch (error) {
+        throw new AppError("memory_init_controller_start_incomplete", "Retained context candidates require exact-request reconciliation", 1, { effect: "partial", run_id: run.id, request_id: scope.requestId, context_sha256: contexts.sha256,
+            cause: errorRecord(error), next_action: "reconcile_exact_request" });
+    }
+}

package/dist/services/memory-init-engine-release.js

@@ -0,0 +1,223 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { readSetupStatus } from "./setup.js";
+import { inspectReleaseArchive } from "./release-archive.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { engineVersionRoot } from "../storage/paths.js";
+import { engineSnapshotChecksum, installPackageEngine } from "./engines.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("memory_init_engine_release_invalid", "Selected engine is not the verified installed release payload", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+/** Select already delivered release bytes, never the invoking CLI or highest
+ * package version. Ambiguous dependency snapshots require explicit selection. */
+export function selectMemoryInitInstalledEngine(home, installationSha256, checksum) {
+    if (!path.isAbsolute(home) || path.resolve(home) !== home || fs.realpathSync(home) !== home)
+        refuse("noncanonical_installation_home");
+    const selected = readSetupStatus(home), installation = selected.installation;
+    if (!installation || selected.installation_readiness !== "installed" || installation.manifest_sha256 !== installationSha256)
+        refuse("installation_selection_changed");
+    if (checksum !== undefined && !/^[a-f0-9]{64}$/.test(checksum))
+        refuse("invalid_engine_checksum");
+    const base = engineVersionRoot(home, installation.manifest.engine.package, installation.manifest.engine.version);
+    const parent = path.dirname(base), version = path.basename(base), candidates = [];
+    if (!fs.existsSync(parent))
+        refuse("selected_engine_not_delivered");
+    if (!fs.lstatSync(parent).isDirectory() || fs.realpathSync(parent) !== parent)
+        refuse("unsafe_engine_store");
+    for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !(entry.name === version || entry.name.startsWith(`${version}--`)
+            && /^[a-f0-9]{64}$/.test(entry.name.slice(version.length + 2))))
+            continue;
+        const root = path.join(parent, entry.name);
+        try {
+            const bytes = readBoundedReleaseFile(path.join(root, "engine.json"), 1024 * 1024);
+            const manifest = JSON.parse(bytes.toString("utf8"));
+            if (manifest.snapshot_root !== root || entry.name !== version && entry.name !== `${version}--${manifest.integrity?.checksum}`
+                || checksum !== undefined && manifest.integrity?.checksum !== checksum)
+                continue;
+            const engine = AdmittedFrozenEngine.admitSelection({ package_name: manifest.package_name, package_version: manifest.package_version,
+                engine_version: manifest.engine_version, snapshot_root: root, integrity_checksum: manifest.integrity?.checksum }, hash(bytes));
+            prepareMemoryInitEngineRelease(home, installationSha256, engine);
+            candidates.push(engine);
+        }
+        catch (error) {
+            // An unavailable or mismatching old snapshot cannot authorize this release.
+            if (error instanceof AppError || error instanceof SyntaxError || error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+    }
+    if (candidates.length !== 1)
+        refuse(candidates.length ? "ambiguous_selected_engine" : "selected_engine_not_delivered");
+    return candidates[0];
+}
+function checkFile(root, entry) {
+    let file = root;
+    const parts = entry.path.split("/");
+    for (const [index, part] of parts.entries()) {
+        file = path.join(file, part);
+        const stat = fs.lstatSync(file);
+        if (stat.isSymbolicLink() || (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory()))
+            refuse("unsafe_snapshot_path");
+    }
+    if ((fs.lstatSync(file).mode & 0o111) !== entry.executable_mode)
+        refuse("snapshot_payload_mode_changed");
+    if (entry.bytes === 0) {
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || stat.size !== 0 || fs.readSync(fd, Buffer.alloc(1), 0, 1, 0) !== 0)
+                refuse("snapshot_payload_changed");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    else if (hash(readBoundedReleaseFile(file, entry.bytes)) !== entry.sha256)
+        refuse("snapshot_payload_changed");
+}
+function checkInventory(root, inventory) {
+    const expected = new Set(inventory.map(entry => entry.path));
+    for (const entry of fs.readdirSync(root, { recursive: true, withFileTypes: true })) {
+        const logical = path.relative(root, path.join(entry.parentPath, entry.name)).split(path.sep).join("/");
+        if (!entry.isFile() && !entry.isDirectory())
+            refuse("unsafe_snapshot_path");
+        if (logical !== "engine.json" && !expected.has(logical)
+            && (entry.name === "engine.json" || entry.isFile() && !logical.startsWith("node_modules/")))
+            refuse("unselected_snapshot_file");
+    }
+}
+function archiveInventory(archive, engineRoot) {
+    const entries = inspectReleaseArchive(archive, readBoundedReleaseFile(path.join(path.dirname(engineRoot), "archive.tgz"), Math.min(archive.bytes, 256 * 1024 * 1024)));
+    const inventory = [];
+    for (const entry of entries) {
+        if (entry.path !== "package" && !entry.path.startsWith("package/"))
+            refuse("foreign_payload_root");
+        if (entry.kind !== "file")
+            continue;
+        const logical = entry.path.slice("package/".length);
+        if (!logical || logical === "engine.json")
+            refuse("reserved_payload_path");
+        inventory.push({ path: logical, sha256: hash(entry.bytes), executable_mode: entry.mode & 0o111, bytes: entry.bytes.length });
+    }
+    return inventory;
+}
+/** Existing package/dependency acquisition supplies the independently selected
+ * full checksum. This gate binds transferred package files to verified setup
+ * bytes before delivery and again in the owned staging directory. */
+export function deliverMemoryInitReleaseEngine(context, input) {
+    const home = context.ddFlowHome;
+    if (!path.isAbsolute(home) || fs.realpathSync(home) !== home || !path.isAbsolute(input.packageRoot)
+        || fs.realpathSync(input.packageRoot) !== input.packageRoot || !/^[a-f0-9]{64}$/.test(input.expectedChecksum))
+        refuse("invalid_delivery_selection");
+    const selected = readSetupStatus(home), installation = selected.installation;
+    if (!installation || selected.installation_readiness !== "installed" || installation.manifest_sha256 !== input.installationSha256)
+        refuse("installation_selection_changed");
+    const inventory = archiveInventory(installation.manifest.engine.archive, installation.engine_root);
+    const check = (root) => {
+        try {
+            for (const file of inventory)
+                checkFile(root, file);
+            checkInventory(root, inventory);
+            if (engineSnapshotChecksum(root) !== input.expectedChecksum)
+                refuse("delivery_checksum_changed");
+            const current = readSetupStatus(home);
+            if (current.installation_readiness !== "installed" || hybridDigest(current.installation) !== hybridDigest(installation))
+                refuse("installation_changed_during_delivery");
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_init_engine_release_invalid")
+                throw error;
+            return refuse("payload_unavailable_or_changed");
+        }
+    };
+    check(input.packageRoot);
+    const delivered = installPackageEngine(context, { packageRoot: input.packageRoot, packageName: installation.manifest.engine.package,
+        version: installation.manifest.engine.version, expectedChecksum: input.expectedChecksum, validateStaged: check });
+    try {
+        return selectMemoryInitInstalledEngine(home, input.installationSha256, input.expectedChecksum);
+    }
+    catch (error) {
+        throw new AppError("memory_init_engine_delivery_incomplete", "Delivered engine requires exact selection reconciliation", 1, { effect: delivered.changed ? "partial" : "no_effect", path: delivered.path, reason: error instanceof AppError ? error.details.reason ?? error.code : "delivered_selection_changed" });
+    }
+}
+/** expectedSha256 must come from independent request custody. No current
+ * installation/canon/profile reads and no restoration of missing files. */
+export function revalidateMemoryInitEngineRelease(input, expectedSha256, engine) {
+    try {
+        if (!(engine instanceof AdmittedFrozenEngine) || !input || typeof input !== "object" || Array.isArray(input))
+            refuse("invalid_retained_pairing");
+        const facts = input, digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+        if (Object.keys(facts).sort().join() !== "archive_sha256,engine_manifest_sha256,engine_sha256,installation_sha256,inventory,schema_id"
+            || facts.schema_id !== "dd-flow/memory-init-engine-release@1" || !digest(expectedSha256)
+            || [facts.installation_sha256, facts.archive_sha256, facts.engine_manifest_sha256, facts.engine_sha256].some(value => !digest(value))
+            || !Array.isArray(facts.inventory) || !facts.inventory.length || facts.inventory.length > 100_000
+            || hybridDigest(facts) !== expectedSha256)
+            refuse("invalid_retained_pairing");
+        const manifest = engine.manifest();
+        if (engine.manifestSha256 !== facts.engine_manifest_sha256 || manifest.integrity.checksum !== facts.engine_sha256)
+            refuse("foreign_engine_identity");
+        const seen = new Set();
+        let total = 0;
+        for (const entry of facts.inventory) {
+            if (!entry || Object.keys(entry).sort().join() !== "bytes,executable_mode,path,sha256" || typeof entry.path !== "string"
+                || entry.path.length > 1024 || entry.path !== entry.path.normalize("NFC") || /[\\:]/.test(entry.path)
+                || [...entry.path].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)
+                || entry.path.split("/").some(part => !part || part === "." || part === "..") || entry.path === "engine.json"
+                || seen.has(entry.path.toLowerCase()) || !digest(entry.sha256) || !Number.isSafeInteger(entry.bytes) || entry.bytes < 0
+                || entry.bytes === 0 && entry.sha256 !== hash(Buffer.alloc(0))
+                || !Number.isSafeInteger(entry.executable_mode) || entry.executable_mode < 0 || entry.executable_mode > 0o111 || (entry.executable_mode & ~0o111) !== 0
+                || (total += entry.bytes) > 512 * 1024 * 1024)
+                refuse("invalid_retained_inventory");
+            seen.add(entry.path.toLowerCase());
+            checkFile(manifest.snapshot_root, entry);
+        }
+        checkInventory(manifest.snapshot_root, facts.inventory);
+        AdmittedFrozenEngine.admitSelection({ package_name: manifest.package_name, package_version: manifest.package_version,
+            engine_version: manifest.engine_version, snapshot_root: manifest.snapshot_root, integrity_checksum: facts.engine_sha256 }, facts.engine_manifest_sha256);
+        return { facts: structuredClone(facts), sha256: expectedSha256 };
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "memory_init_engine_release_invalid")
+            throw error;
+        return refuse("payload_unavailable_or_changed");
+    }
+}
+/** Fresh selection only. Restarts must retain this inventory independently,
+ * not consult the current installation. This does not install dependencies,
+ * admit handlers/storage/provider access or grant project effects. */
+export function prepareMemoryInitEngineRelease(home, installationSha256, engine) {
+    try {
+        if (!(engine instanceof AdmittedFrozenEngine))
+            refuse("unprepared_engine");
+        if (!path.isAbsolute(home) || path.resolve(home) !== home || fs.realpathSync(home) !== home)
+            refuse("noncanonical_installation_home");
+        const selected = readSetupStatus(home), installation = selected.installation;
+        if (!installation || selected.installation_readiness !== "installed" || installation.manifest_sha256 !== installationSha256)
+            refuse("installation_selection_changed");
+        const manifest = engine.manifest();
+        if (manifest.package_name !== installation.manifest.engine.package || manifest.package_version !== installation.manifest.engine.version)
+            refuse("foreign_engine_identity");
+        AdmittedFrozenEngine.admitSelection({ package_name: manifest.package_name, package_version: manifest.package_version,
+            engine_version: manifest.engine_version, snapshot_root: manifest.snapshot_root, integrity_checksum: manifest.integrity.checksum }, engine.manifestSha256);
+        const archive = installation.manifest.engine.archive;
+        const inventory = archiveInventory(archive, installation.engine_root);
+        const final = readSetupStatus(home);
+        if (final.installation_readiness !== "installed" || hybridDigest(final.installation) !== hybridDigest(installation))
+            refuse("installation_changed_during_admission");
+        const facts = { schema_id: "dd-flow/memory-init-engine-release@1", installation_sha256: installationSha256,
+            archive_sha256: archive.sha256, engine_manifest_sha256: engine.manifestSha256,
+            engine_sha256: manifest.integrity.checksum, inventory: inventory.sort((a, b) => a.path.localeCompare(b.path, "en")) };
+        return revalidateMemoryInitEngineRelease(facts, hybridDigest(facts), engine);
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "memory_init_engine_release_invalid")
+            throw error;
+        return refuse("payload_unavailable_or_changed");
+    }
+}

package/dist/services/memory-init-git-policy.js

@@ -0,0 +1,165 @@
+import path from "node:path";
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { PreparedMemoryInitTarget } from "./memory-init-preflight.js";
+const event = "memory.init_git_policy", token = Symbol("memory-init-git-policy");
+function refuse(reason) {
+    throw new AppError("memory_init_git_policy_invalid", "Init lacks explicit retained Git policy", 2, { reason, effect: "no_effect" });
+}
+function validScope(scope) {
+    if (!scope || typeof scope.requestId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(scope.requestId)
+        || typeof scope.projectRoot !== "string" || !path.isAbsolute(scope.projectRoot)
+        || typeof scope.workspaceRoot !== "string" || !path.isAbsolute(scope.workspaceRoot)
+        || Object.keys(scope).sort().join() !== "projectRoot,requestId,workspaceRoot")
+        refuse("invalid_request_scope");
+}
+/** Shared read-only policy observation for init and upgrade. The caller owns
+ * retained input custody; these facts grant neither dispatch nor push. */
+export function observeMemoryGitPolicySelection(environment, input) {
+    validScope(input.scope);
+    const { scope, selection } = input;
+    if (!selection || Object.keys(selection).sort().join() !== "integrationBranch,route"
+        || !["integration_branch_direct", "feature_worktree"].includes(selection.route)
+        || typeof selection.integrationBranch !== "string" || !selection.integrationBranch || selection.integrationBranch.startsWith("-") || selection.integrationBranch.length > 1024
+        || [...selection.integrationBranch].some(character => character.charCodeAt(0) <= 32 || character.charCodeAt(0) === 127))
+        refuse("explicit_policy_required");
+    if (typeof input.gitExecutable !== "string" || !path.isAbsolute(input.gitExecutable))
+        refuse("explicit_git_required");
+    const env = Object.fromEntries(Object.entries(environment).filter(([key]) => !key.startsWith("GIT_")));
+    const git = (directory, args, optional = false) => {
+        const result = spawnSync(input.gitExecutable, ["-c", "core.fsmonitor=false", "-C", directory, ...args], { env: { ...env, GIT_OPTIONAL_LOCKS: "0" }, encoding: "utf8", timeout: 5000, maxBuffer: 64 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || !optional && result.status !== 0)
+            refuse("git_policy_observation_failed");
+        return result.status === 0 ? result.stdout.trim() : null;
+    };
+    const valid = spawnSync(input.gitExecutable, ["check-ref-format", `refs/heads/${selection.integrationBranch}`], { env: { ...env, GIT_OPTIONAL_LOCKS: "0" }, timeout: 5000, maxBuffer: 64 * 1024, shell: false, windowsHide: true });
+    if (valid.error || valid.signal || valid.status !== 0)
+        refuse("invalid_integration_branch");
+    const common = (directory) => {
+        if (git(directory, ["rev-parse", "--is-bare-repository"]) !== "false"
+            || fs.realpathSync(git(directory, ["rev-parse", "--show-toplevel"])) !== directory)
+            refuse("not_repository_root");
+        return fs.realpathSync(path.resolve(directory, git(directory, ["rev-parse", "--git-common-dir"])));
+    };
+    const repository = common(scope.projectRoot);
+    if (common(scope.workspaceRoot) !== repository)
+        refuse("foreign_workspace_repository");
+    const branch = git(scope.workspaceRoot, ["symbolic-ref", "--short", "HEAD"]);
+    if (!branch)
+        refuse("workspace_branch_unavailable");
+    if (selection.route === "integration_branch_direct"
+        ? scope.projectRoot !== scope.workspaceRoot || branch !== selection.integrationBranch
+        : scope.projectRoot === scope.workspaceRoot || branch === selection.integrationBranch)
+        refuse("route_workspace_mismatch");
+    if (selection.route === "feature_worktree"
+        && !/^[a-f0-9]{40,64}$/.test(git(scope.projectRoot, ["rev-parse", "--verify", `refs/heads/${selection.integrationBranch}^{commit}`], true) ?? ""))
+        refuse("integration_branch_unavailable");
+    const head = git(scope.workspaceRoot, ["rev-parse", "--verify", "HEAD"], true);
+    return { repository, workspace_branch: branch, initial_head: head, source: "explicit_request",
+        route: selection.route, integration_branch: selection.integrationBranch, push_authorized: false };
+}
+/** SQL preservation, not fresh policy inference, Git execution or permission. */
+export function readMemoryInitGitPolicy(context, scope) {
+    validScope(scope);
+    const rows = context.db.all(`SELECT payload_json FROM audit_events WHERE event_type=?
+    AND json_extract(payload_json,'$.scope.requestId')=? AND json_extract(payload_json,'$.scope.projectRoot')=?
+    AND json_extract(payload_json,'$.scope.workspaceRoot')=? LIMIT 2`, [event, scope.requestId, scope.projectRoot, scope.workspaceRoot]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 32 * 1024)
+        refuse("ambiguous_or_unbounded_policy");
+    let value;
+    try {
+        value = JSON.parse(rows[0].payload_json);
+    }
+    catch {
+        return refuse("invalid_policy_receipt");
+    }
+    if (!value || value.schema_id !== "dd-flow/memory-init-git-policy@1" || hybridDigest(value.scope) !== hybridDigest(scope)
+        || Object.keys(value).sort().join() !== "initial_head,integration_branch,push_authorized,repository,route,schema_id,scope,source,target_sha256,workspace_branch"
+        || value.source !== "explicit_request" || value.push_authorized !== false
+        || !["integration_branch_direct", "feature_worktree"].includes(value.route)
+        || typeof value.target_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.target_sha256)
+        || typeof value.repository !== "string" || !path.isAbsolute(value.repository)
+        || typeof value.workspace_branch !== "string" || !value.workspace_branch
+        || typeof value.integration_branch !== "string" || !value.integration_branch
+        || (value.initial_head !== null && (typeof value.initial_head !== "string" || !/^[a-f0-9]{40,64}$/.test(value.initial_head))))
+        refuse("policy_receipt_changed");
+    return structuredClone(value);
+}
+/** Explicit request choice frozen against genuine no-effect target preflight.
+ * Retaining this receipt must precede bootstrap publication. It grants no
+ * dispatch authority by itself or compatibility with a historical bootstrap.
+ * Memory finish integrates only after independently accepted current review;
+ * this receipt never authorizes push. */
+export class PreparedMemoryInitGitPolicy {
+    #target;
+    #receipt;
+    constructor(key, target, receipt) {
+        if (key !== token)
+            refuse("policy_token_required");
+        this.#target = target;
+        this.#receipt = structuredClone(receipt);
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.target instanceof PreparedMemoryInitTarget))
+            refuse("prepared_target_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        const prepared = this.prepareFresh(context.env, input);
+        const receipt = prepared.value(), retained = readMemoryInitGitPolicy(context, receipt.scope);
+        if (retained && hybridDigest(retained) !== hybridDigest(receipt))
+            refuse("policy_request_conflict");
+        return prepared;
+    }
+    /** Fresh explicit policy before opening runtime stores. This checks Git and
+     * scope, but grants no SQL custody, integration or provider authority. */
+    static prepareFresh(environment, input) {
+        if (!(input.target instanceof PreparedMemoryInitTarget))
+            refuse("prepared_target_required");
+        input.target.revalidate();
+        const facts = input.target.facts(), scope = { requestId: facts.request_id, projectRoot: facts.project_root, workspaceRoot: facts.workspace_root };
+        if (!facts.tool_probes)
+            refuse("fresh_target_required");
+        const policy = observeMemoryGitPolicySelection(environment, { scope, gitExecutable: facts.tools.git, selection: input.selection });
+        if (policy.repository !== facts.repository || policy.workspace_branch !== facts.branch || policy.initial_head !== facts.head)
+            refuse("target_changed_after_preparation");
+        const receipt = { schema_id: "dd-flow/memory-init-git-policy@1", scope, target_sha256: input.target.sha256,
+            ...policy };
+        return new PreparedMemoryInitGitPolicy(token, input.target, receipt);
+    }
+    value() { return structuredClone(this.#receipt); }
+    retain(context) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        this.#target.revalidate();
+        return context.db.writeTransaction(() => this.retainPreparedSql(context), "memoryInit.retainGitPolicy");
+    }
+    /** Metadata-only publication for an already prepared aggregate owner. */
+    retainPreparedSql(context) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_policy_writer_required");
+        const receipt = readMemoryInitGitPolicy(context, this.#receipt.scope);
+        if (receipt) {
+            if (hybridDigest(receipt) !== hybridDigest(this.#receipt))
+                refuse("policy_request_conflict");
+            return receipt;
+        }
+        const scope = this.#receipt.scope;
+        if (context.db.get(`SELECT 1 FROM audit_events WHERE event_type IN ('memory.init_project_bootstrap_intent','memory.init_project_bootstrap')
+        AND json_extract(payload_json,'$.scope.requestId')=? AND json_extract(payload_json,'$.scope.projectRoot')=?
+        AND json_extract(payload_json,'$.scope.workspaceRoot')=? LIMIT 1`, [scope.requestId, scope.projectRoot, scope.workspaceRoot]))
+            refuse("policy_must_precede_bootstrap");
+        appendAudit(context, { eventType: event, payload: this.#receipt });
+        this.assertCustody(context);
+        return this.value();
+    }
+    assertCustody(context) {
+        if (hybridDigest(readMemoryInitGitPolicy(context, this.#receipt.scope)) !== hybridDigest(this.#receipt))
+            refuse("policy_receipt_changed");
+    }
+}