@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/memory-stage-results.js

@@ -0,0 +1,290 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { validateMemoryCompositionGraph, memoryCompositionOutputAllowed } from "./memory-composition-graph.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+const memoryStages = {
+    "mb-init": ["preflight", "discover", "compose", "verify", "review", "finish"],
+    "mb-upgrade": ["preflight", "diff-analysis", "upgrade", "verify", "review", "finish"]
+};
+const sha = (value) => /^[a-f0-9]{64}$/.test(value);
+// Proposal relationships/scopes can be corrected before any acceptance or Work
+// allocation. Missing/foreign runtime bindings and identities remain fatal.
+const correctableProposalReasons = new Set([
+    "unsafe_reference_path",
+    "foreign_predecessor_reference", "duplicate_unit", "changed_unit_coverage", "duplicate_finding", "foreign_finding_unit",
+    "duplicate_fact", "foreign_fact_unit", "foreign_unit_reference", "unobserved_or_changed_source",
+    "duplicate_preservation_invariant", "weakened_upgrade_mode", "changed_preservation_invariants", "missing_applicable_unit_preservation",
+    "duplicate_preservation_assessment", "incomplete_preservation_assessment", "foreign_preservation_unit", "unreviewable_preservation_unit", "unapproved_composition_profile",
+    "unresolved_composition_applicability", "duplicate_composition_work", "unknown_composition_dependency", "duplicate_composition_scope",
+    "unbounded_composition_write", "foreign_composition_write", "canonical_composition_write", "private_composition_write",
+    "authority_composition_write", "foreign_composition_run_write", "cyclic_composition_dependency", "invalid_assembly_membership",
+    "mechanical_unit_cannot_allocate_agent_work", "inapplicable_composition_work", "incomplete_composition_coverage",
+    "assembly_precedes_unit_writers", "unordered_composition_writers", "unordered_composition_read_write"
+]);
+function refuse(reason, details = {}) {
+    throw new AppError("memory_stage_result_invalid", reason === "missing_applicable_unit_preservation"
+        ? "Every applicable upgrade unit requires a source-backed preservation invariant. In preflight add the invariant; in diff-analysis keep the accepted invariants unchanged and assign the planned work to their existing units"
+        : "Memory stage result is not bound to its retained input", 2, { ...details, reason, phase: "prepare", effect: "no_effect" });
+}
+function contained(logical, allowRoot = false, proposal = false) {
+    if (allowRoot && logical === ".")
+        return;
+    if (!logical || path.posix.isAbsolute(logical) || path.win32.isAbsolute(logical) || logical.includes("\\")
+        || logical.includes("\0") || logical.split("/").some(segment => !segment || segment === "." || segment === ".."))
+        refuse("unsafe_reference_path", { recoverable: proposal });
+}
+export function memorySourceKey(root, logical) { return `${root}\0${logical}`; }
+function unique(values, reason) {
+    if (new Set(values).size !== values.length)
+        refuse(reason);
+    return new Set(values);
+}
+/** Read-only result preparation. The stage handler must still establish physical check,
+ * Work/reviewer, bootstrap, integration and readiness custody before settlement.
+ * Schema validity and source identity are not semantic completeness or finish authority.
+ */
+export class PreparedMemoryStageResult {
+    sha256;
+    #bytes;
+    #value;
+    #routes;
+    #executionSha256;
+    #preflight;
+    #upgradeWritePaths;
+    #mechanicalUnits;
+    #preservationInvariants;
+    #upgradeEvidenceIndex;
+    constructor(bytes, value, routes, executionSha256, preflight, upgradeWritePaths, mechanicalUnits, preservationInvariants, upgradeEvidenceIndex) {
+        this.#bytes = Buffer.from(bytes);
+        this.#value = structuredClone(value);
+        this.#routes = structuredClone(routes);
+        this.#executionSha256 = executionSha256;
+        this.#preflight = structuredClone(preflight);
+        this.#upgradeWritePaths = upgradeWritePaths ? new Set(upgradeWritePaths) : null;
+        this.#mechanicalUnits = new Set(mechanicalUnits);
+        this.#preservationInvariants = structuredClone(preservationInvariants);
+        this.#upgradeEvidenceIndex = structuredClone(upgradeEvidenceIndex);
+        this.sha256 = createHash("sha256").update(bytes).digest("hex");
+        Object.freeze(this);
+    }
+    static prepare(input, flow, binding) {
+        try {
+            const stages = memoryStages[flow.descriptor.id], upgrade = flow.descriptor.id === "mb-upgrade";
+            if (input.byteLength < 1 || input.byteLength > 1024 * 1024 || !stages
+                || !stages.includes(binding.stage) || !binding.runId || !sha(binding.inputSha256))
+                refuse("invalid_input_binding");
+            if (upgrade && (!binding.upgrade || !["patch", "targeted_minor", "full_migration"].includes(binding.upgrade.minimumMode)))
+                refuse("missing_upgrade_impact_binding");
+            if (binding.upgrade?.evidenceIndex && (binding.upgrade.evidenceIndex.path !== "upgrade-baseline.json" || !sha(binding.upgrade.evidenceIndex.sha256)))
+                refuse("invalid_upgrade_evidence_binding");
+            const bytes = Buffer.from(input), value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+            const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(flow.stageBlob(binding.stage, "result_schema")));
+            if (schema.$id !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : `dd-flow/mb-init-${binding.stage}-result@1`))
+                refuse("invalid_result_schema");
+            const validate = new Ajv2020({ strict: true, strictRequired: false, validateFormats: false }).compile(schema);
+            if (!validate(value))
+                throw new AppError("memory_stage_result_invalid", "Memory stage result proposal does not match its schema", 2, { reason: "invalid_result_schema", phase: "prepare", effect: "no_effect", recoverable: true,
+                    errors: structuredClone(validate.errors), result_sha256: createHash("sha256").update(bytes).digest("hex") });
+            if (value.run_id !== binding.runId || value.stage !== binding.stage || value.input_sha256 !== binding.inputSha256)
+                refuse("foreign_result_identity");
+            const isEntry = flow.descriptor.entry_stage === binding.stage;
+            if (binding.predecessors.length !== (isEntry ? 0 : 1))
+                refuse("incomplete_predecessor_binding");
+            for (const predecessor of binding.predecessors) {
+                contained(predecessor.result.path);
+                if (!sha(predecessor.result.sha256) || !sha(predecessor.input_sha256)
+                    || flow.successor(predecessor.stage, "accepted") !== binding.stage)
+                    refuse("foreign_predecessor_binding");
+            }
+            if (hybridDigest(value.predecessors) !== hybridDigest(binding.predecessors))
+                refuse("foreign_predecessor_reference");
+            const units = unique(value.units.map(unit => unit.id), "duplicate_unit");
+            if (binding.unitIds === null) {
+                if (!["preflight", upgrade ? "diff-analysis" : "discover"].includes(binding.stage))
+                    refuse("missing_unit_inventory");
+            }
+            else {
+                const expected = unique(binding.unitIds, "duplicate_bound_unit");
+                if (units.size !== expected.size || [...units].some(id => !expected.has(id)))
+                    refuse("changed_unit_coverage");
+            }
+            unique(value.findings.map(finding => finding.id), "duplicate_finding");
+            if (value.findings.some(finding => !units.has(finding.unit_id)))
+                refuse("foreign_finding_unit");
+            const facts = value.details.facts;
+            if (binding.stage === "discover") {
+                unique(facts.map(fact => fact.id), "duplicate_fact");
+                if (facts.some(fact => !units.has(fact.unit_id)))
+                    refuse("foreign_fact_unit");
+            }
+            const visit = (node, role = "source") => {
+                if (Array.isArray(node)) {
+                    node.forEach(child => visit(child, role));
+                    return;
+                }
+                if (!node || typeof node !== "object")
+                    return;
+                const record = node;
+                if (typeof record.unit_id === "string" && !units.has(record.unit_id))
+                    refuse("foreign_unit_reference", { unit_id: record.unit_id.slice(0, 256) });
+                if (Array.isArray(record.unit_ids) && record.unit_ids.some(id => typeof id !== "string" || !units.has(id)))
+                    refuse("foreign_unit_reference", { unit_ids: record.unit_ids.filter(id => typeof id !== "string" || !units.has(id)).slice(0, 8).map(id => String(id).slice(0, 256)) });
+                if (typeof record.path === "string" && (typeof record.root === "string" || typeof record.sha256 === "string"))
+                    contained(record.path, typeof record.root === "string" && record.sha256 === undefined, true);
+                if (typeof record.root === "string" && typeof record.path === "string" && typeof record.sha256 === "string") {
+                    const key = memorySourceKey(record.root, record.path);
+                    if (binding.sources.get(key) !== record.sha256 && !(role === "evidence" && binding.historicalEvidence?.has(`${key}\0${record.sha256}`)))
+                        refuse("unobserved_or_changed_source");
+                }
+                Object.entries(record).forEach(([key, child]) => visit(child, key === "evidence" || key === "artifacts" ? key : role));
+            };
+            visit(value);
+            if (upgrade) {
+                const invariants = value.details.preservation_invariants;
+                if (invariants)
+                    unique(invariants.map(item => String(item.id)), "duplicate_preservation_invariant");
+                const expected = binding.upgrade.preservationInvariants;
+                if (binding.stage !== "preflight" && !expected)
+                    refuse("missing_upgrade_preservation_binding");
+                if (binding.stage === "diff-analysis") {
+                    const modes = ["patch", "targeted_minor", "full_migration"];
+                    if (modes.indexOf(String(value.details.mode)) < modes.indexOf(binding.upgrade.minimumMode))
+                        refuse("weakened_upgrade_mode");
+                    const ordered = (items) => [...items].sort((a, b) => String(a.id).localeCompare(String(b.id), "en"));
+                    if (hybridDigest(ordered(invariants)) !== hybridDigest(ordered(expected)))
+                        refuse("changed_preservation_invariants");
+                    for (const change of value.details.path_map) {
+                        if (change.from !== null)
+                            contained(change.from, false, true);
+                        if (change.to !== null)
+                            contained(change.to, false, true);
+                    }
+                }
+                const unreviewable = (invariants ?? expected ?? []).filter(item => !value.units.some(unit => unit.id === item.unit_id && unit.applicability === "applicable"));
+                if (unreviewable.length)
+                    refuse("unreviewable_preservation_unit", {
+                        unit_ids: [...new Set(unreviewable.map(item => item.unit_id))].slice(0, 8),
+                        invariant_ids: unreviewable.map(item => item.id).slice(0, 8),
+                        hint: binding.stage === "preflight"
+                            ? "Each preservation criterion needs an applicable assessment unit. Bind a no-migration criterion to an applicable provenance/readiness unit; this does not require migration Work or an apply receipt."
+                            : "Keep each retained preservation criterion assigned to an applicable assessment unit. Correct proposed applicability, not accepted invariant identities or predecessor bytes."
+                    });
+                if (binding.stage === "preflight" || binding.stage === "diff-analysis") {
+                    const uncovered = value.units.filter(unit => unit.applicability === "applicable" && !invariants.some(item => item.unit_id === unit.id));
+                    if (uncovered.length)
+                        refuse("missing_applicable_unit_preservation", { unit_ids: uncovered.map(unit => unit.id).slice(0, 8) });
+                }
+                if (binding.stage === "verify") {
+                    const assessments = value.details.preservation_assessments;
+                    const selected = unique(assessments.map(item => item.invariant_id), "duplicate_preservation_assessment");
+                    if (selected.size !== expected.length || expected.some(item => !selected.has(String(item.id))))
+                        refuse("incomplete_preservation_assessment");
+                    if (assessments.some(item => expected.find(original => original.id === item.invariant_id)?.unit_id !== item.unit_id))
+                        refuse("foreign_preservation_unit");
+                }
+            }
+            let routes = null;
+            const authoringPaths = upgrade && binding.stage === "upgrade" ? binding.upgrade?.authoringPaths : undefined;
+            if (binding.stage === "compose" || authoringPaths) {
+                validateMemoryCompositionGraph(value, authoringPaths, authoringPaths ? binding.upgrade?.mechanicalUnits : undefined);
+                if (!(binding.execution instanceof FrozenGenericExecution) || binding.execution.settings.flow_id !== flow.descriptor.id
+                    || binding.execution.settings.descriptor_sha256 !== flow.sha256 || binding.execution.sha256 !== binding.executionSha256)
+                    refuse("missing_or_foreign_composition_execution");
+                const works = value.details.works;
+                try {
+                    routes = works.map(work => ({ key: work.key, execution: binding.execution.work(binding.stage, work.profile_id ?? undefined) }));
+                }
+                catch {
+                    refuse("unapproved_composition_profile");
+                }
+            }
+            if (binding.preflight) {
+                contained(binding.preflight.result.path);
+                if (!sha(binding.preflight.result.sha256) || !sha(binding.preflight.input_sha256)
+                    || typeof binding.preflight.semantic_scope !== "string" || !binding.preflight.semantic_scope.trim()
+                    || Buffer.byteLength(binding.preflight.semantic_scope) > 16384 || binding.preflight.semantic_scope.includes("\0"))
+                    refuse("invalid_preflight_binding");
+                if (binding.preflight.preserved_paths !== undefined) {
+                    if (!Array.isArray(binding.preflight.preserved_paths) || binding.preflight.preserved_paths.length > 4096)
+                        refuse("invalid_preflight_binding");
+                    unique(binding.preflight.preserved_paths, "duplicate_preserved_path");
+                    for (const logical of binding.preflight.preserved_paths) {
+                        if (typeof logical !== "string" || logical.length > 4096)
+                            refuse("invalid_preflight_binding");
+                        contained(logical);
+                    }
+                }
+            }
+            return new PreparedMemoryStageResult(bytes, value, routes, routes ? binding.executionSha256 : null, binding.preflight ?? null, authoringPaths ? new Set([...authoringPaths.values()].flatMap(paths => [...paths])) : null, authoringPaths ? binding.upgrade?.mechanicalUnits ?? new Set() : new Set(), upgrade ? binding.upgrade?.preservationInvariants ?? [] : [], upgrade ? binding.upgrade?.evidenceIndex ?? null : null);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_stage_result_invalid") {
+                if (correctableProposalReasons.has(String(error.details.reason)) && error.details.recoverable !== false)
+                    throw new AppError(error.code, `Correct the proposed result (${error.details.reason}) without changing retained RUN, predecessor or execution bindings`, error.exitCode, { ...error.details, recoverable: true, result_sha256: createHash("sha256").update(input).digest("hex") });
+                throw error;
+            }
+            return refuse("invalid_result_or_binding");
+        }
+    }
+    bytes() { return Buffer.from(this.#bytes); }
+    mechanicalUnitIds() { return new Set(this.#mechanicalUnits); }
+    preservationInvariants() { return structuredClone(this.#preservationInvariants); }
+    value() { return structuredClone(this.#value); }
+    authoringStage() {
+        if (!this.#routes || !["compose", "upgrade"].includes(this.#value.stage))
+            refuse("not_a_composition_result");
+        return this.#value.stage;
+    }
+    allowsCompositionOutput(root, logical) {
+        return memoryCompositionOutputAllowed(logical, root === "workspace" && this.#upgradeWritePaths ? this.#upgradeWritePaths : undefined);
+    }
+    compositionRoutes() {
+        if (!this.#routes)
+            refuse("not_a_composition_result");
+        return structuredClone(this.#routes);
+    }
+    /** Pure registration input, not allocation, dispatch or stage completion authority.
+     * The handler must select a registered result schema and independently bind
+     * this result's predecessor/source custody before passing the batch to its writer.
+     */
+    compositionBatch(binding) {
+        const stage = this.authoringStage();
+        // Registration assigns unfinished authoring; only final acceptance attests
+        // settled outputs. A repairable blueprint is not a blocked dispatch.
+        if (this.#value.outcome === "blocked")
+            refuse("composition_not_accepted");
+        // Unknown facts may survive DISCOVER with a reason/next action. Unknown
+        // target applicability must be resolved before immutable Work assignment,
+        // rather than dispatching a graph that cannot later accept its own units.
+        if (this.#value.units.some(unit => unit.applicability === "unknown"))
+            refuse("unresolved_composition_applicability");
+        if (binding.runId !== this.#value.run_id || binding.inputSha256 !== this.#value.input_sha256
+            || binding.executionSha256 !== this.#executionSha256)
+            refuse("foreign_composition_batch_binding");
+        if (typeof binding.resultSchema !== "string" || !/^dd-flow\/[A-Za-z0-9][A-Za-z0-9._-]*@[1-9][0-9]*$/.test(binding.resultSchema))
+            refuse("invalid_composition_work_schema");
+        const routes = new Map(this.#routes.map(route => [route.key, route]));
+        const works = this.#value.details.works;
+        return { works: works.map(work => {
+                // Historical retained schemas can still be read, but cannot invent tasks.
+                if (typeof work.task !== "string" || !work.task.trim() || work.task.length > 16384)
+                    refuse("missing_composition_work_task");
+                const packet = { schema_id: "dd-flow/memory-composition-work-packet@1", run_id: binding.runId,
+                    stage, key: work.key, role: work.role, unit_ids: work.unit_ids,
+                    task: work.task, depends_on: work.depends_on, result_schema: binding.resultSchema,
+                    read_scopes: work.read_scopes, write_scopes: work.write_scopes,
+                    compose_result_sha256: this.sha256, compose_input_sha256: binding.inputSha256,
+                    execution_sha256: binding.executionSha256, predecessors: this.#value.predecessors };
+                const scopedPacket = { ...packet, ...(this.#preflight ? { preflight: structuredClone(this.#preflight) } : {}),
+                    ...(this.#upgradeEvidenceIndex ? { upgrade_baseline: { root: "run", ...this.#upgradeEvidenceIndex },
+                        preservation_invariants: this.#preservationInvariants.filter(item => work.unit_ids.includes(String(item.unit_id))) } : {}) };
+                return { key: work.key, task: work.task, depends_on: [...work.depends_on],
+                    launch_policy: "fresh_agent_required", result_schema: binding.resultSchema,
+                    payload: structuredClone({ memory_composition: { ...scopedPacket, packet_sha256: hybridDigest(scopedPacket) },
+                        execution_override: { agent_profile_id: routes.get(work.key).execution.worker.id } }) };
+            }) };
+    }
+}

package/dist/services/memory-tool-probe.js

@@ -0,0 +1,25 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { SETUP_STARTUP_MS, setupReporter } from "../harness-runtime/lib/setup-progress.mjs";
+/** Silent, local prerequisite tools are not agent Turns. Reuse the CLI setup
+ * startup budget; do not invent heartbeat progress or retry a failed probe. */
+export function runMemoryToolProbe(executable, args, options) {
+    const started = performance.now();
+    const report = setupReporter(options.env.DD_EVAL_OPERATION_ID);
+    const step = createHash("sha256").update(JSON.stringify([executable, args])).digest("hex");
+    report("probe_started", step);
+    const result = spawnSync(executable, args, { ...options, shell: false, windowsHide: true,
+        timeout: SETUP_STARTUP_MS, maxBuffer: options.maxBuffer ?? 256 * 1024 });
+    report("probe_completed", step);
+    const error = result.error?.code ?? null;
+    const output = (bytes) => ({ bytes: bytes?.length ?? null,
+        sha256: bytes ? createHash("sha256").update(bytes).digest("hex") : null });
+    const stdout = output(result.stdout), stderr = output(result.stderr);
+    // Arbitrary tool output may contain credentials. Public errors retain typed
+    // outcomes and bounded custody facts, never the uncontrolled output itself.
+    return { result, diagnostics: { executable, args, timeout_ms: SETUP_STARTUP_MS,
+            elapsed_ms: Math.round(performance.now() - started), status: result.status,
+            signal: result.signal, error_code: error, timed_out: error === "ETIMEDOUT",
+            stdout_bytes: stdout.bytes, stdout_sha256: stdout.sha256,
+            stderr_bytes: stderr.bytes, stderr_sha256: stderr.sha256 } };
+}

package/dist/services/memory-upgrade-analysis-handler.js

@@ -0,0 +1,243 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { assertPreparedRunBundleSqlAuthority, readFlowRunExecutionBundle } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedMemoryUpgradeBootstrapReadiness, readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness, resolveUpgradeHistoricalScope } from "./memory-upgrade-storage-readiness.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator, readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { assertMemoryOrdinaryUpgradeConfigurationCoverage } from "./memory-ordinary-defaults.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedMemoryResultBinding } from "./memory-result-binding.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { localEnvironmentAllowed, workspaceGitFiles } from "./workspace-files.js";
+import { validateUpgradePathMap } from "./memory-upgrade-inventory.js";
+import { readMemoryUpgradeEvidence, readIssuedMemoryUpgradeTarget } from "./memory-upgrade-evidence.js";
+function refuse(reason) {
+    throw new AppError("memory_upgrade_analysis_handler_invalid", "Upgrade analysis requires its accepted bootstrap and original project", 2, { reason, effect: "no_effect" });
+}
+function rejectResult(bytes, reason, reference) {
+    const message = reason === "missing_impact_checks" ? "Include every required check from the issued adjacent release-impact chain in the proposed analysis result"
+        : reason === "symlink_source_reference" ? "Cite the issued run upgrade-baseline.json project_link_metadata for link identity, and a selected regular target file for contents; direct symlink sources are not admitted"
+            : reason === "analysis_not_accepted" ? "Accepted analysis cannot carry unresolved major/blocking findings. Represent planned upgrade work in units, path_map and required_checks; for a real blocker use the issued pause command. Do not mark unresolved work resolved merely to pass this gate"
+                : "Correct the result evidence using issued stage inputs and old/target references; controller response views and logs are not admitted evidence";
+    throw new AppError("memory_stage_result_invalid", message, 2, { reason, phase: "prepare", effect: "no_effect", recoverable: true,
+        result_sha256: createHash("sha256").update(bytes).digest("hex"),
+        ...(reference ? { reference: { root: String(reference.root).slice(0, 32), path: String(reference.path).slice(0, 1024) } } : {}) });
+}
+function selected(context, input) {
+    if (!["preflight", "diff-analysis"].includes(input.stage) || !(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
+        refuse("invalid_stage_input");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-upgrade"
+        || bundle.descriptor.descriptor.entry_stage !== "preflight" || bundle.descriptor.successor("preflight", "accepted") !== "diff-analysis")
+        refuse("registered_upgrade_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    const frozen = bundle.execution.snapshot().scope;
+    const bootstrapScope = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, bootstrapScope);
+    if (!ready?.hasPreservationBaseline || ready.projectId !== project.id || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const predecessor = input.stage === "diff-analysis" ? readAcceptedStageData(context, { ...scope, stage: "preflight" }) : null;
+    const authority = hybridDigest(ready.authority);
+    const fence = (writer) => {
+        const current = readMemoryUpgradeBootstrapReadiness(writer, bootstrapScope);
+        if (!current || hybridDigest(current.authority) !== authority
+            || predecessor && readAcceptedStageData(writer, { ...scope, stage: "preflight" }).authority_sha256 !== predecessor.authority_sha256)
+            refuse("analysis_dependencies_changed");
+    };
+    return { bundle, scope, bootstrapScope, predecessor, fence, accepted: index.stage_runs.find((stage) => stage.stage === input.stage)?.status === "done" };
+}
+/** Agent references select current observations from the CLI inventory, not
+ * arbitrary local files. Canonical/receipt inputs come from the retained RUN
+ * bundle; old document evidence is independently supplied by the SQL binding.
+ */
+function sources(context, input, state) {
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes));
+    }
+    catch {
+        return rejectResult(input.bytes, "invalid_result_json");
+    }
+    const storage = readUpgradeStorageReadiness(context, state.bootstrapScope);
+    if (!storage?.selection)
+        refuse("retained_selection_required");
+    const run = assertPreparedRunBundleSqlAuthority(context, state.scope, state.bundle);
+    const workspace = run.workspace_root ?? run.project_root;
+    const projectIsWorkspace = workspace === run.project_root;
+    const allowed = new Set([...(workspaceGitFiles(workspace, ["--cached", "--others", "--exclude-standard"]) ?? []),
+        ...storage.selection.payload.current.inventory.inventory.entries.filter(entry => entry.current?.kind === "file" || entry.target).map(entry => `.memory-bank/${entry.path}`)]);
+    const allowedRun = new Set(state.bundle.manifest.inventory.map(entry => `execution-bundle/${entry.path}`));
+    const oldEvidence = readMemoryUpgradeEvidence(context, state.bootstrapScope);
+    const oldRunHashes = new Map([[oldEvidence.reference.path, oldEvidence.reference.sha256],
+        ...oldEvidence.index.entries.map(entry => [entry.retained.path, entry.retained.sha256])]);
+    const target = readIssuedMemoryUpgradeTarget(context, state.bootstrapScope, state.scope.projectId);
+    if (target)
+        for (const ref of [target.reference, ...target.index.entries.map(entry => entry.retained)]) {
+            allowedRun.add(ref.path);
+            oldRunHashes.set(ref.path, ref.sha256);
+        }
+    const inputStage = JSON.parse(run.index_json).stage_runs.find((stage) => stage.stage === state.scope.stage);
+    const inputPath = `${state.bundle.descriptor.stage(state.scope.stage).directory}/stage-input.json`;
+    if (typeof inputStage?.input_sha256 === "string")
+        allowedRun.add(inputPath);
+    allowedRun.add(oldEvidence.reference.path);
+    for (const entry of oldEvidence.index.entries)
+        allowedRun.add(entry.retained.path);
+    if (state.predecessor)
+        allowedRun.add(state.predecessor.result.path);
+    const position = state.bundle.descriptor.descriptor.stages.findIndex(stage => stage.id === state.scope.stage);
+    for (const stage of state.bundle.descriptor.descriptor.stages.slice(0, position)) {
+        const accepted = readAcceptedStageData(context, { ...state.scope, stage: stage.id });
+        allowedRun.add(accepted.result.path);
+        // Accepted invariants can cite the packet that originally established
+        // their scope. Retain that exact issued input, not arbitrary RUN files.
+        if (typeof accepted.input_sha256 === "string") {
+            const logical = `${stage.directory}/stage-input.json`;
+            allowedRun.add(logical);
+            oldRunHashes.set(logical, accepted.input_sha256);
+        }
+    }
+    const historical = new Set(oldEvidence.index.entries.map(entry => `${entry.source.path}\0${entry.source.sha256}`));
+    const locations = new Map(), pending = [{ value, role: "source" }];
+    let nodes = 0;
+    while (pending.length) {
+        if (++nodes > 100_000)
+            rejectResult(input.bytes, "unbounded_result_tree");
+        const item = pending.pop(), node = item.value;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                pending.push({ value: child, role: item.role });
+            continue;
+        }
+        if (!node || typeof node !== "object")
+            continue;
+        const ref = node;
+        if (typeof ref.root === "string" && typeof ref.path === "string" && typeof ref.sha256 === "string") {
+            if (ref.root === "workspace" || ref.root === "project" && projectIsWorkspace) {
+                if (!allowed.has(ref.path) || ref.path.split("/").some(part => [".git", "node_modules", ".dd-flow"].includes(part) || !localEnvironmentAllowed(part)))
+                    rejectResult(input.bytes, "unselected_project_source", ref);
+                if (!(item.role === "evidence" && historical.has(`${ref.path}\0${ref.sha256}`))) {
+                    // Historical retained bytes need not exist in today's tree.
+                    let parent = workspace;
+                    for (const part of ref.path.split("/").slice(0, -1)) {
+                        parent = path.join(parent, part);
+                        if (!fs.lstatSync(parent).isDirectory())
+                            rejectResult(input.bytes, "symlink_source_reference", ref);
+                    }
+                    if (fs.lstatSync(path.join(workspace, ref.path), { throwIfNoEntry: false })?.isSymbolicLink())
+                        rejectResult(input.bytes, "symlink_source_reference", ref);
+                }
+            }
+            else if (ref.root === "run") {
+                if (!allowedRun.has(ref.path))
+                    rejectResult(input.bytes, "unselected_run_source", ref);
+                if (ref.path === inputPath && ref.sha256 !== inputStage?.input_sha256)
+                    rejectResult(input.bytes, "changed_stage_input", ref);
+                if (oldRunHashes.has(ref.path) && oldRunHashes.get(ref.path) !== ref.sha256)
+                    rejectResult(input.bytes, "changed_old_evidence", ref);
+            }
+            else
+                rejectResult(input.bytes, "unselected_source_root", ref);
+            // The accepted old tree remains evidence after a canonical path is
+            // replaced or archived. It never qualifies a current output artifact.
+            if (!(item.role === "evidence" && ["workspace", "project"].includes(ref.root) && historical.has(`${ref.path}\0${ref.sha256}`)))
+                locations.set(`${ref.root}\0${ref.path}`, { root: ref.root, path: ref.path });
+        }
+        for (const [key, child] of Object.entries(ref))
+            pending.push({ value: child, role: key === "evidence" || key === "artifacts" ? key : item.role });
+    }
+    return ObservedMemorySources.capture({ workspace, ...(projectIsWorkspace ? { project: workspace } : {}), run: run.run_root ?? run.run_dir }, [...locations.values()]);
+}
+/** Shared upgrade observation path for registered authoring/review consumers.
+ * The source witness grants no Stage, Work or canonical-write authority. */
+export function captureMemoryUpgradeSources(context, bundle, stage, bytes) {
+    if (bundle.descriptor.descriptor.id !== "mb-upgrade" || !(bytes instanceof Uint8Array) || bytes.length > 1024 * 1024)
+        refuse("invalid_stage_input");
+    bundle.descriptor.stage(stage);
+    const frozen = bundle.execution.snapshot().scope;
+    const bootstrapScope = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const { projectId } = resolveUpgradeHistoricalScope(context, bootstrapScope);
+    const scope = { projectId, runId: bundle.manifest.run_id, stage };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, bootstrapScope);
+    if (!ready?.hasPreservationBaseline || ready.projectId !== projectId || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const edges = bundle.descriptor.descriptor.edges.filter(edge => edge.to === stage && edge.on === "accepted");
+    if (edges.length !== (stage === bundle.descriptor.descriptor.entry_stage ? 0 : 1))
+        refuse("invalid_stage_predecessor");
+    const predecessor = edges.length ? readAcceptedStageData(context, { ...scope, stage: edges[0].from }) : null;
+    return sources(context, { bytes }, { bundle, scope, bootstrapScope, predecessor });
+}
+/** Upgrade analysis uses the registered six-stage group. Generic lifecycle
+ * owns Work, prompts and dispatch; RUN admission still owns bootstrap readiness.
+ */
+export function startMemoryUpgradeAnalysis(context, input) {
+    const state = selected(context, input);
+    if (state.accepted)
+        refuse("use_accepted_finish_replay");
+    PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(context, state.bundle);
+    const start = PreparedDescriptorStageStart.prepare(context, input);
+    const stage = start.apply(context, state.fence);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input);
+    PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(context, state.bundle);
+    return { ...stage, ...coordinator.apply(context, state.fence) };
+}
+export function finishMemoryUpgradeAnalysis(context, input) {
+    const state = selected(context, input);
+    if (state.accepted) {
+        // Historical acknowledgement must not reinterpret old artifacts after the
+        // upgrade has intentionally changed them. SQL settlement owns acceptance.
+        const binding = PreparedMemoryResultBinding.prepare(context, { ...state.scope, flow: state.bundle.descriptor,
+            execution: state.bundle.execution, bundle: state.bundle, sources: ObservedMemorySources.capture({}, []), acceptedReplay: true });
+        if (!binding.acceptedBytes()?.equals(input.bytes))
+            refuse("accepted_result_changed");
+        const settlement = PreparedDescriptorStageSettlement.prepare(context, input);
+        return settlement.apply(context, writer => { state.fence(writer); binding.assertCustody(writer); });
+    }
+    const observed = sources(context, input, state);
+    const binding = PreparedMemoryResultBinding.prepare(context, { ...state.scope, flow: state.bundle.descriptor,
+        execution: state.bundle.execution, bundle: state.bundle, sources: observed, acceptedReplay: state.accepted });
+    const accepted = binding.acceptedBytes();
+    if (accepted && !accepted.equals(input.bytes))
+        refuse("accepted_result_changed");
+    const result = PreparedMemoryStageResult.prepare(input.bytes, state.bundle.descriptor, binding.binding()), value = result.value();
+    if (value.outcome !== "accepted" || value.findings.some(finding => finding.severity !== "minor" && finding.status !== "resolved"))
+        rejectResult(input.bytes, "analysis_not_accepted");
+    const details = value.details;
+    if (input.stage === "diff-analysis") {
+        const defaults = readDescriptorStageInput(context, state.scope, state.bundle).input.ordinary_defaults;
+        if (defaults) {
+            assertMemoryOrdinaryUpgradeConfigurationCoverage(value, defaults);
+            if (defaults.missing.length && !context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_resumed' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='diff-analysis' LIMIT 1", [state.scope.projectId, state.scope.runId])) {
+                throw new AppError("memory_stage_result_invalid", "Resolve the ordinary configuration choice through the existing diff-analysis pause/answer path before accepting the upgrade plan", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_choice_required", missing: defaults.missing });
+            }
+        }
+        const storage = readUpgradeStorageReadiness(context, state.bootstrapScope);
+        const checks = details.required_checks;
+        if (!storage?.selection || storage.selection.payload.impact.chain.steps.some(step => !Array.isArray(step.required_checks)
+            || step.required_checks.some(check => typeof check !== "string" || !checks.includes(check))))
+            rejectResult(input.bytes, "missing_impact_checks");
+        try {
+            validateUpgradePathMap(storage.selection.payload.current.inventory.inventory, details.path_map);
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || error.code !== "upgrade_inventory_invalid")
+                throw error;
+            throw new AppError("memory_stage_result_invalid", "Correct the proposed upgrade path map before it becomes an immutable accepted plan", 2, { reason: "invalid_upgrade_path_map", cause: error.details.reason, pointer: "/details/path_map", phase: "prepare", effect: "no_effect",
+                recoverable: true, result_sha256: result.sha256 });
+        }
+    }
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes: result.bytes() });
+    PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(context, state.bundle);
+    binding.revalidate(context);
+    return settlement.apply(context, writer => { state.fence(writer); binding.assertCustody(writer); });
+}