@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.149

package/dist/services/memory-compose-handler.js

@@ -20,6 +20,14 @@ import { PreparedMemoryCompositionAcceptance } from "./memory-composition-accept
 import { readAcceptedStageData } from "./stage-report-renderer.js";
 import { ObservedMemorySources } from "./memory-source-observations.js";
 import { PreparedCheckEvidence } from "./code-checks.js";
+import { captureMemoryUpgradeSources } from "./memory-upgrade-analysis-handler.js";
+import { PreparedMemoryUpgradeBootstrapReadiness, readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { PreparedMemoryUpgradePublication } from "./memory-upgrade-publication.js";
+import { PreparedMemoryLayer } from "./memory-layer.js";
+import { appendAudit } from "./audit.js";
+import { assertImportAdmission } from "../storage/import-guard.js";
+import { readMemoryUpgradePublication, upgradePublicationKey, upgradePublicationReceipt, upgradePublicationIntentEvent, upgradePublicationCompleteEvent } from "./memory-upgrade-publication-custody.js";
 function refuse(reason) {
     throw new AppError("memory_compose_handler_invalid", "Memory composition lacks retained scope, plan or output custody", 2, { reason, effect: "no_effect" });
 }
@@ -27,12 +35,30 @@ function selected(context, input) {
     if (!(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
         refuse("invalid_input_bytes");
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.successor("discover", "accepted") !== "compose"
-        || bundle.descriptor.successor("compose", "accepted") !== "verify")
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
         refuse("registered_memory_bundle_required");
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId, stage: "compose" };
+    const stage = bundle.descriptor.descriptor.id === "mb-init" ? "compose" : "upgrade";
+    if (bundle.descriptor.successor(stage === "compose" ? "discover" : "diff-analysis", "accepted") !== stage
+        || bundle.descriptor.successor(stage, "accepted") !== "verify")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId, stage };
     const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
-    return { bundle, scope, run, accepted: index.stage_runs.find((stage) => stage.stage === "compose")?.status === "done" };
+    return { bundle, scope, run, accepted: index.stage_runs.find((item) => item.stage === stage)?.status === "done" };
+}
+function compositionBaseline(context, bundle) {
+    if (bundle.descriptor.descriptor.id === "mb-init")
+        return PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const selected = bundle.execution.snapshot().scope;
+    const scope = { requestId: selected.requestId, projectRoot: selected.projectRoot, workspaceRoot: selected.workspace };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, scope);
+    if (!ready?.hasPreservationBaseline || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const authority = hybridDigest(ready.authority);
+    return {
+        assertCustody(writer) { const current = readMemoryUpgradeBootstrapReadiness(writer, scope); if (!current || hybridDigest(current.authority) !== authority)
+            refuse("upgrade_bootstrap_changed"); },
+        revalidate(reader) { PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(reader, bundle); this.assertCustody(reader); }
+    };
 }
 /** SQL-only physical binding proof; allocation/prompt custody is checked
  * separately. No new Session, hook claim or provider invocation is created.
@@ -70,14 +96,14 @@ export function registerMemoryCompositionFromStage(context, input) {
     const { bundle, scope, accepted } = selected(context, input);
     if (accepted)
         refuse("use_accepted_finish_replay");
-    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "compose" });
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: scope.stage });
     const allocated = context.db.readSnapshot(() => {
         coordinator.assertAllocatedCustody(context);
         const root = readDescriptorRootWork(context, scope, bundle);
         return { workId: root.workId, physical: coordinatorSession(context, scope, bundle, root.workId) };
     });
     const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle,
-        sources: captureMemoryPreflightSources(context, bundle, input.bytes) });
+        sources: scope.stage === "compose" ? captureMemoryPreflightSources(context, bundle, input.bytes) : captureMemoryUpgradeSources(context, bundle, scope.stage, input.bytes) });
     let composition;
     try {
         composition = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
@@ -94,7 +120,7 @@ export function registerMemoryCompositionFromStage(context, input) {
     const ordinaryDefaults = readDescriptorStageInput(context, scope, bundle).input.ordinary_defaults;
     if (ordinaryDefaults) {
         assertMemoryOrdinaryConfigurationCoverage(composition.value(), ordinaryDefaults);
-        if (ordinaryDefaults.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')='compose' LIMIT 1", [scope.projectId, scope.runId])) {
+        if (scope.stage === "compose" && ordinaryDefaults.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')='compose' LIMIT 1", [scope.projectId, scope.runId])) {
             throw new AppError("memory_stage_result_invalid", "Resolve the missing ordinary configuration choice through the existing compose pause/answer path before registering Work", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_choice_required", missing: ordinaryDefaults.missing });
         }
     }
@@ -114,25 +140,136 @@ export function startMemoryComposition(context, input) {
     const { bundle, scope, accepted } = selected(context, input);
     if (accepted)
         refuse("use_accepted_finish_replay");
-    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
-    const inherited = context.db.readSnapshot(() => ({ discovery: readAcceptedStageData(context, { ...scope, stage: "discover" }), preflight: readAcceptedStageData(context, { ...scope, stage: "preflight" }) }));
+    const preservation = compositionBaseline(context, bundle), discoveryStage = scope.stage === "compose" ? "discover" : "diff-analysis";
+    const inherited = context.db.readSnapshot(() => ({ discovery: readAcceptedStageData(context, { ...scope, stage: discoveryStage }), preflight: readAcceptedStageData(context, { ...scope, stage: "preflight" }) }));
     const preflight = JSON.parse(inherited.preflight.bytes.toString("utf8")), discovery = JSON.parse(inherited.discovery.bytes.toString("utf8"));
-    if (preflight.schema_id !== "dd-flow/mb-init-preflight-result@1" || preflight.run_id !== input.runId || preflight.outcome !== "accepted"
-        || discovery.schema_id !== "dd-flow/mb-init-discover-result@1"
+    if (preflight.schema_id !== (scope.stage === "compose" ? "dd-flow/mb-init-preflight-result@1" : "dd-flow/mb-upgrade-stage-result@1") || preflight.run_id !== input.runId || preflight.outcome !== "accepted"
+        || discovery.schema_id !== (scope.stage === "compose" ? "dd-flow/mb-init-discover-result@1" : "dd-flow/mb-upgrade-stage-result@1")
+        || preflight.stage !== "preflight" || discovery.stage !== discoveryStage
         || discovery.run_id !== input.runId || discovery.outcome !== "accepted")
         refuse("accepted_discovery_and_baseline_required");
     const fence = (writer) => {
         preservation.assertCustody(writer);
-        if (readAcceptedStageData(writer, { ...scope, stage: "discover" }).authority_sha256 !== inherited.discovery.authority_sha256
+        if (readAcceptedStageData(writer, { ...scope, stage: discoveryStage }).authority_sha256 !== inherited.discovery.authority_sha256
             || readAcceptedStageData(writer, { ...scope, stage: "preflight" }).authority_sha256 !== inherited.preflight.authority_sha256)
             refuse("inherited_custody_changed");
     };
-    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: "compose" });
+    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: scope.stage });
     preservation.revalidate(context);
-    const stage = start.apply(context, fence), coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "compose" });
+    const stage = start.apply(context, fence), coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: scope.stage });
     preservation.revalidate(context);
     return { ...stage, ...coordinator.apply(context, fence) };
 }
+/** Mechanical upgrade continuation, not final Stage acceptance. Reuses the
+ * registered blueprint and settled Work; the plan is retained in SQL before
+ * the first filesystem effect. No provider or second controller is launched.
+ * Kept outside the registry until the complete upgrade lifecycle is admitted.
+ */
+export function publishMemoryUpgradeFromStage(context, input) {
+    const { bundle, scope, accepted } = selected(context, { ...input, bytes: Buffer.alloc(0) });
+    if (scope.stage !== "upgrade" || accepted)
+        refuse("active_upgrade_publication_required");
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "upgrade" });
+    const allocated = context.db.readSnapshot(() => {
+        coordinator.assertAllocatedCustody(context);
+        const root = readDescriptorRootWork(context, scope, bundle);
+        return { workId: root.workId, physical: coordinatorSession(context, scope, bundle, root.workId) };
+    });
+    const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, "upgrade"), stage: "upgrade", parent_work_id: allocated.workId });
+    const binding = PreparedMemoryResultBinding.prepareRegisteredComposition(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle, registrationScope: registration.scope });
+    const outputs = PreparedMemoryCompositionAcceptance.prepareForUpgradePublication(context, { scope: registration.scope, flow: bundle.descriptor, engine: bundle.engine(), binding: binding.binding() });
+    const frozen = bundle.execution.snapshot().scope, bootstrapScope = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, bootstrapScope), storage = readUpgradeStorageReadiness(context, bootstrapScope);
+    if (!ready || !storage?.selection || ready.authority.binding.storage_sha256 !== storage.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const identity = { scope: registration.scope, selection_sha256: storage.selection.sha256, execution_sha256: bundle.execution.sha256,
+        registration_sha256: hybridDigest(registration), bootstrap_sha256: hybridDigest(ready.authority),
+        work_custody_sha256: outputs.custodySha256() };
+    const fence = (writer) => {
+        assertPreparedRunBundleSqlAuthority(writer, scope, bundle);
+        coordinator.assertAllocatedCustody(writer);
+        binding.assertCustody(writer);
+        outputs.assertCustody(writer);
+        if (readDescriptorRootWork(writer, scope, bundle).workId !== allocated.workId
+            || coordinatorSession(writer, scope, bundle, allocated.workId) !== allocated.physical)
+            refuse("upgrade_publication_coordinator_changed");
+        const current = readMemoryUpgradeBootstrapReadiness(writer, bootstrapScope), retained = readUpgradeStorageReadiness(writer, bootstrapScope);
+        if (!current || hybridDigest(current.authority) !== identity.bootstrap_sha256 || retained?.selection?.sha256 !== identity.selection_sha256)
+            refuse("upgrade_publication_dependencies_changed");
+    };
+    const read = (reader) => readMemoryUpgradePublication(reader, identity);
+    let plan = read(context)?.plan;
+    if (!plan) {
+        binding.revalidate(context);
+        outputs.revalidate(context);
+        const selected = storage.selection.payload, layer = selected.layer;
+        if (!selected.current.old_tree || !selected.current.version_source)
+            refuse("upgrade_publication_baseline_required");
+        const target = PreparedMemoryLayer.restoreRetained(new Map(layer.files.map(file => [file.path, Buffer.from(file.base64, "base64")])), layer.sha256, layer.installation_sha256);
+        const diff = readAcceptedStageData(context, { ...scope, stage: "diff-analysis" }), details = JSON.parse(diff.bytes.toString("utf8")).details;
+        plan = PreparedMemoryUpgradePublication.prepare({ selectionSha256: storage.selection.sha256, inventory: selected.current.inventory,
+            oldTree: selected.current.old_tree, layer: target, changes: details.path_map, versionSource: selected.current.version_source });
+        const before = new Map(plan.beforeFiles().map(file => [file.path, file]));
+        const settled = new Map(outputs.settledArtifacts().filter(item => item.artifact.root === "workspace").map(item => [item.artifact.path, item.artifact.sha256]));
+        for (const entry of selected.current.inventory.inventory.entries)
+            if (entry.current && !before.has(entry.path))
+                refuse("unsettled_semantic_removal");
+        for (const [name, file] of before) {
+            const original = selected.current.inventory.inventory.entries.find(entry => entry.path === name)?.current;
+            if (original && file.kind === original.kind && file.mode === original.mode && file.sha256 === original.sha256)
+                continue;
+            if (file.kind !== "file" || original && file.mode !== original.mode || settled.get(`.memory-bank/${name}`) !== file.sha256)
+                refuse("unsettled_semantic_change");
+        }
+        const prepared = plan;
+        plan = context.db.writeTransaction(() => {
+            fence(context);
+            const prior = read(context)?.plan;
+            if (prior) {
+                if (prior.sha256 !== prepared.sha256)
+                    refuse("upgrade_publication_plan_changed");
+                return prior;
+            }
+            const now = context.now();
+            context.db.run("INSERT INTO runtime_config (key,value_json,created_at,updated_at) VALUES (?,?,?,?)", [upgradePublicationKey(identity), JSON.stringify({ binding: identity, plan_json: prepared.bytes().toString("utf8"), plan_sha256: prepared.sha256 }), now, now]);
+            appendAudit(context, { projectId: scope.projectId, eventType: upgradePublicationIntentEvent, payload: upgradePublicationReceipt(identity, prepared) });
+            const retained = read(context);
+            if (!retained)
+                refuse("upgrade_publication_intent_readback_failed");
+            return retained.plan;
+        });
+    }
+    const publication = plan;
+    try {
+        while (true) {
+            assertImportAdmission(context.ddFlowHome);
+            context.db.readSnapshot(() => { fence(context); if (read(context)?.plan.sha256 !== publication.sha256)
+                refuse("upgrade_publication_intent_changed"); });
+            if (publication.applyNextAction().status === "applied")
+                break;
+        }
+        context.db.writeTransaction(() => {
+            fence(context);
+            if (read(context)?.plan.sha256 !== publication.sha256)
+                refuse("upgrade_publication_intent_changed");
+            if (!read(context)?.completed)
+                appendAudit(context, { projectId: scope.projectId, eventType: upgradePublicationCompleteEvent, payload: upgradePublicationReceipt(identity, publication, true) });
+            if (!read(context)?.completed)
+                refuse("upgrade_publication_completion_readback_failed");
+        });
+        const state = publication.classify();
+        if (state.completed !== state.total)
+            refuse("upgrade_publication_not_complete");
+        const record = publication.outputs().find(output => output.path === `archive/mb-upgrade/${identity.selection_sha256}/migration.json`);
+        if (!record)
+            refuse("upgrade_migration_record_missing");
+        return { status: "applied", publication_sha256: publication.sha256, migration_record: { path: `.memory-bank/${record.path}`, sha256: record.sha256 },
+            artifacts: publication.outputs().map(output => ({ root: "workspace", path: `.memory-bank/${output.path}`, sha256: output.sha256 })) };
+    }
+    catch (error) {
+        throw new AppError("memory_upgrade_publication_pending", "Preserve the accepted SQL plan and reconcile this upgrade continuation", 1, { effect: "publication_pending", publication_sha256: publication.sha256, cause: error instanceof Error ? error.message : String(error) });
+    }
+}
 /** Agent references are selectors, not permissions. Supplement independent
  * baseline evidence only with current outputs admitted by completed Work.
  */
@@ -207,7 +344,10 @@ export function captureMemoryCompositionSources(context, bundle, runRoot, bytes,
     }
     // Keep evidence/artifact roles for the shared collector; settled child output
     // references already have their independent output owner above.
-    const observedBaseline = captureMemoryPreflightSources(context, bundle, Buffer.from(JSON.stringify(value))), locations = new Map();
+    const observedBaseline = bundle.descriptor.descriptor.id === "mb-upgrade"
+        ? captureMemoryUpgradeSources(context, bundle, value.stage, Buffer.from(JSON.stringify(value)))
+        : captureMemoryPreflightSources(context, bundle, Buffer.from(JSON.stringify(value)));
+    const locations = new Map();
     for (const key of observedBaseline.hashes().keys()) {
         const [root, logical] = key.split("\0");
         locations.set(key, { root: root, path: logical });
@@ -230,27 +370,29 @@ export function captureMemoryCompositionSources(context, bundle, runRoot, bytes,
  * Semantic quality remains the following VERIFY and independent REVIEW gates.
  */
 export function finishMemoryComposition(context, input) {
-    const { bundle, scope, run, accepted } = selected(context, input), root = readDescriptorRootWork(context, scope, bundle);
+    const { bundle, scope, run, accepted } = selected(context, input);
+    const root = readDescriptorRootWork(context, scope, bundle);
     if (!input.bytes.length)
         refuse("invalid_result_bytes");
-    const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: "compose", parent_work_id: root.workId });
+    const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: scope.stage, parent_work_id: root.workId });
     const registrationScope = registration.scope;
     const blueprintBinding = PreparedMemoryResultBinding.prepareRegisteredComposition(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle,
         registrationScope, acceptedReplay: accepted });
     const outputs = PreparedMemoryCompositionAcceptance.prepare(context, { scope: registrationScope, flow: bundle.descriptor, engine: bundle.engine(), binding: blueprintBinding.binding() });
-    const sources = captureMemoryCompositionSources(context, bundle, run.run_root ?? run.run_dir, input.bytes, outputs);
+    const bytes = outputs.projectResult(input.bytes);
+    const sources = captureMemoryCompositionSources(context, bundle, run.run_root ?? run.run_dir, bytes, outputs);
     const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle, sources, acceptedReplay: accepted, historicalEvidence: outputs.historicalEvidence() });
     const replay = binding.acceptedBytes();
-    if (replay && !replay.equals(input.bytes))
+    if (replay && !replay.equals(bytes))
         refuse("accepted_result_changed");
-    const result = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
+    const result = PreparedMemoryStageResult.prepare(bytes, bundle.descriptor, binding.binding());
     outputs.assertResult(result);
     const ordinaryDefaults = readDescriptorStageInput(context, scope, bundle, true, accepted).input.ordinary_defaults;
     if (ordinaryDefaults && !replay) {
         const selected = bundle.execution.snapshot().scope;
         assertMemoryOrdinaryConfigurationOutputs(context, selected.workspace, ordinaryDefaults, result.value().units.flatMap(unit => unit.artifacts), { requestId: selected.requestId, projectRoot: selected.projectRoot, workspaceRoot: selected.workspace });
     }
-    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "compose", bytes: result.bytes() });
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: scope.stage, bytes: result.bytes() });
     blueprintBinding.revalidate(context);
     binding.revalidate(context);
     outputs.revalidate(context);

package/dist/services/memory-composition-acceptance.js

@@ -8,6 +8,11 @@ import { ObservedMemorySources } from "./memory-source-observations.js";
 import { readWorkBatchCustody } from "./work-registry.js";
 import { readMemoryCompositionRegistration, readRegisteredMemoryComposition } from "./memory-composition-registration.js";
 import { validateMemoryCompositionWorkResult } from "./memory-composition-work-results.js";
+import { readMemoryUpgradePublication } from "./memory-upgrade-publication-custody.js";
+import { readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { getProjectVersionStatus } from "./version-status.js";
 const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
 function refuse(reason) {
     throw new AppError("memory_composition_acceptance_invalid", "Composition lacks registered, settled and current output custody", 2, { reason, effect: "no_effect" });
@@ -77,17 +82,34 @@ export class PreparedMemoryCompositionAcceptance {
     #registrationSha256;
     #workers;
     #artifacts;
+    #semanticArtifacts;
+    #publication = null;
+    #migrationRecord = null;
+    #historicalEvidence = new Set();
     #observed;
     constructor(scope, original, registrationSha256, workers, artifacts, observed) {
         this.#scope = structuredClone(scope);
         this.#original = original;
         this.#registrationSha256 = registrationSha256;
         this.#workers = workers;
-        this.#artifacts = artifacts;
+        this.#artifacts = structuredClone(artifacts);
+        this.#semanticArtifacts = structuredClone(artifacts);
         this.#observed = observed;
         Object.freeze(this);
     }
     static prepare(context, input) {
+        return this.#prepare(context, input, true);
+    }
+    /** Restore settled semantic Work independently of today's possibly partly
+     * published marker bytes. The publication owner still checks the before view
+     * before retaining its intent; this method does not accept current artifacts.
+     */
+    static prepareForUpgradePublication(context, input) {
+        if (input.scope.stage !== "upgrade")
+            refuse("upgrade_publication_scope_required");
+        return this.#prepare(context, input, false);
+    }
+    static #prepare(context, input, observe) {
         const registration = readMemoryCompositionRegistration(context, input.scope);
         const original = readRegisteredMemoryComposition(context, input), value = original.value();
         const works = value.details.works;
@@ -137,21 +159,127 @@ export class PreparedMemoryCompositionAcceptance {
         for (const record of current.values())
             for (const id of record.units)
                 artifacts.set(id, [...(artifacts.get(id) ?? []), record.artifact]);
-        const observed = ObservedMemorySources.capture(assigned, [...current.values()].map(record => ({ root: record.artifact.root, path: record.artifact.path })));
-        const hashes = observed.hashes();
-        if ([...current.values()].some(record => hashes.get(memorySourceKey(record.artifact.root, record.artifact.path)) !== record.artifact.sha256))
-            refuse("current_output_bytes_changed");
-        const prepared = new PreparedMemoryCompositionAcceptance(input.scope, original, registrationSha256, selected.map(item => ({ id: item.id, harness: item.harness, authority: item.authority, evidence: item.evidence })), artifacts, observed);
+        const prepared = new PreparedMemoryCompositionAcceptance(input.scope, original, registrationSha256, selected.map(item => ({ id: item.id, harness: item.harness, authority: item.authority, evidence: item.evidence })), artifacts, null);
+        if (input.scope.stage === "upgrade")
+            prepared.#historicalEvidence = new Set(input.binding.historicalEvidence);
+        if (observe) {
+            if (input.scope.stage === "upgrade")
+                prepared.#includePublication(context, input.binding);
+            prepared.#observed = ObservedMemorySources.capture(assigned, prepared.outputLocations());
+            const hashes = prepared.#observed.hashes();
+            if ([...prepared.#artifacts.values()].flat().some(artifact => hashes.get(memorySourceKey(artifact.root, artifact.path)) !== artifact.sha256))
+                refuse("current_output_bytes_changed");
+        }
         prepared.assertCustody(context);
         return prepared;
     }
+    #includePublication(context, binding) {
+        const frozen = binding.execution?.snapshot().scope;
+        if (!frozen)
+            refuse("upgrade_execution_required");
+        const scope = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+        const ready = readMemoryUpgradeBootstrapReadiness(context, scope), storage = readUpgradeStorageReadiness(context, scope);
+        if (!ready || !storage?.selection || ready.authority.binding.storage_sha256 !== storage.sha256)
+            refuse("upgrade_bootstrap_required");
+        const identity = { scope: this.#scope, selection_sha256: storage.selection.sha256, execution_sha256: binding.executionSha256,
+            registration_sha256: this.#registrationSha256, bootstrap_sha256: hybridDigest(ready.authority), work_custody_sha256: this.custodySha256() };
+        const publication = readMemoryUpgradePublication(context, identity);
+        if (!publication?.completed)
+            refuse("completed_upgrade_publication_required");
+        const state = publication.plan.classify();
+        if (state.completed !== state.total)
+            refuse("upgrade_publication_not_current");
+        const actions = new Map(publication.plan.actions().map(action => [`.memory-bank/${action.path}`, action]));
+        for (const artifacts of this.#artifacts.values())
+            for (const artifact of artifacts) {
+                const action = artifact.root === "workspace" ? actions.get(artifact.path) : undefined;
+                if (!action)
+                    continue;
+                // Only the exact CLI transition can advance a settled worker hash. No
+                // caller-provided allowlist may excuse an arbitrary changed document.
+                if (action.before?.sha256 !== artifact.sha256 || action.after?.kind !== "file")
+                    refuse("unbound_semantic_output_transition");
+                artifact.sha256 = action.after.sha256;
+            }
+        const outputs = new Map(publication.plan.outputs().map(output => [`.memory-bank/${output.path}`, output]));
+        const recordPath = `.memory-bank/archive/mb-upgrade/${identity.selection_sha256}/migration.json`, record = outputs.get(recordPath);
+        if (!record)
+            refuse("upgrade_migration_record_missing");
+        this.#migrationRecord = { path: recordPath, sha256: record.sha256 };
+        const add = (unit, path, sha256) => {
+            const values = this.#artifacts.get(unit) ?? [], artifact = { root: "workspace", path, sha256 };
+            const prior = values.find(value => value.root === artifact.root && value.path === path);
+            if (prior && prior.sha256 !== sha256)
+                refuse("conflicting_mechanical_artifact");
+            if (!prior)
+                values.push(artifact);
+            this.#artifacts.set(unit, values);
+        };
+        const diff = readAcceptedStageData(context, { projectId: this.#scope.project_id, runId: this.#scope.run_id, stage: "diff-analysis" });
+        const changes = JSON.parse(diff.bytes.toString("utf8")).details.path_map;
+        const old = new Map(storage.selection.payload.current.inventory.inventory.entries.map(entry => [`.memory-bank/${entry.path}`, entry]));
+        const final = new Map(publication.plan.beforeFiles().map(entry => [entry.path, entry]));
+        for (const action of publication.plan.actions()) {
+            if (action.after)
+                final.set(action.path, action.after);
+            else
+                final.delete(action.path);
+        }
+        for (const entry of storage.selection.payload.current.inventory.inventory.entries) {
+            const name = `.memory-bank/${entry.path}`, actual = final.get(entry.path);
+            const semantic = changes.some(change => change.to === name && change.action === "semantic-work");
+            if (entry.target && (entry.ownership === "generated" || entry.ownership === "canonical" && !semantic)
+                && (actual?.kind !== "file" || actual.sha256 !== entry.target.sha256))
+                refuse("incomplete_canonical_publication");
+            if (entry.ownership === "canonical" && entry.action === "archive" && actual)
+                refuse("obsolete_canonical_path_active");
+        }
+        const status = getProjectVersionStatus({ projectRoot: frozen.workspace, rootSource: "explicit", canon: null });
+        if (status?.memory_bank.version !== storage.selection.release.canon.version
+            || status.flow_pack.canon_version_at_source_commit !== storage.selection.release.canon.version
+            || status.flow_pack.source_commit !== storage.selection.release.canon.commit)
+            refuse("upgrade_versions_inconsistent");
+        for (const change of changes) {
+            if (change.action === "retain" && change.from) {
+                const source = old.get(change.from)?.current;
+                if (source?.kind === "file")
+                    add(change.unit_id, change.from, outputs.get(change.from)?.sha256 ?? source.sha256);
+            }
+            else if (["canonical", "generated"].includes(change.ownership) && change.action !== "semantic-work") {
+                if (change.to) {
+                    const output = outputs.get(change.to) ?? final.get(change.to.slice(13));
+                    if (!output || output.kind !== "file")
+                        refuse("missing_mechanical_artifact");
+                    add(change.unit_id, change.to, output.sha256);
+                }
+                if (change.from) {
+                    const archive = `.memory-bank/archive/mb-upgrade/${identity.selection_sha256}/files/${change.from.slice(13)}.bin`, output = outputs.get(archive);
+                    if (!output)
+                        refuse("missing_recovery_artifact");
+                    add(change.unit_id, archive, output.sha256);
+                }
+            }
+        }
+        for (const unit of this.#original.value().units)
+            if (unit.applicability === "applicable")
+                add(unit.id, recordPath, record.sha256);
+        this.#publication = { binding: identity, sha256: publication.plan.sha256 };
+    }
     /** Only these independently settled output locations may supplement baseline
      * evidence in the final result binding. The returned map is a defensive copy.
      */
-    outputHashes() { return this.#observed.hashes(); }
+    outputHashes() { if (!this.#observed)
+        refuse("current_output_observation_required"); return this.#observed.hashes(); }
+    /** SQL-settled before-publication facts, not current filesystem witnesses. */
+    settledArtifacts() {
+        return [...this.#semanticArtifacts].flatMap(([unit_id, artifacts]) => artifacts.map(artifact => ({ unit_id, artifact: structuredClone(artifact) })));
+    }
+    custodySha256() {
+        return hybridDigest({ scope: this.#scope, registration_sha256: this.#registrationSha256, workers: this.#workers, artifacts: [...this.#semanticArtifacts] });
+    }
     historicalEvidence() {
         const units = this.#original.value().units;
-        return new Set(units.flatMap(unit => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`)));
+        return new Set([...this.#historicalEvidence, ...units.flatMap(unit => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`))]);
     }
     resultEvidence() { return this.#workers.map(worker => structuredClone(worker.evidence)); }
     outputLocations() {
@@ -161,14 +289,48 @@ export class PreparedMemoryCompositionAcceptance {
                 selected.set(memorySourceKey(artifact.root, artifact.path), { root: artifact.root, path: artifact.path });
         return [...selected.values()];
     }
+    /** Runtime projection from completed SQL publication, never an agent map.
+     * Keep substantive fields and immutable graph intact. Existing invented
+     * references are rejected rather than silently overwritten by this helper.
+     */
+    projectResult(bytes) {
+        if (!this.#migrationRecord)
+            return Buffer.from(bytes);
+        const value = object(Buffer.from(bytes).toString("utf8"), "invalid_result_json");
+        const reject = (pointer) => {
+            throw new AppError("memory_stage_result_invalid", "Use the selected upgrade outputs; do not invent or rerun publication", 2, { reason: "unselected_upgrade_output", phase: "prepare", effect: "no_effect", recoverable: true, result_sha256: hash(bytes), pointer });
+        };
+        if (Array.isArray(value.units))
+            for (const [index, unit] of value.units.entries()) {
+                if (!unit || typeof unit !== "object" || typeof unit.id !== "string" || !this.#original.mechanicalUnitIds().has(unit.id) && !this.#artifacts.has(unit.id))
+                    continue;
+                const expected = this.#artifacts.get(unit.id) ?? [], before = this.#semanticArtifacts.get(unit.id) ?? [];
+                if (unit.artifacts !== undefined && !Array.isArray(unit.artifacts))
+                    continue;
+                for (const reference of unit.artifacts ?? [])
+                    if (![...expected, ...before].some(artifact => hybridDigest(artifact) === hybridDigest(reference)))
+                        reject(`/units/${index}/artifacts`);
+                unit.artifacts = structuredClone(expected);
+            }
+        if (value.details && typeof value.details === "object" && !Array.isArray(value.details)) {
+            const details = value.details, original = this.#original.value().details;
+            if (details.migration_record !== undefined && ![original.migration_record, this.#migrationRecord].some(reference => hybridDigest(reference) === hybridDigest(details.migration_record)))
+                reject("/details/migration_record");
+            details.migration_record = { ...this.#migrationRecord };
+        }
+        return Buffer.from(JSON.stringify(value));
+    }
     assertResult(result) {
         if (!(result instanceof PreparedMemoryStageResult))
             refuse("prepared_result_required");
+        if (this.#scope.stage === "upgrade" && !this.#publication)
+            refuse("completed_upgrade_publication_required");
         const original = this.#original.value(), final = result.value(), value = final;
         const identity = ["schema_id", "run_id", "input_sha256", "predecessors"];
         if (hybridDigest(identity.map(field => original[field])) !== hybridDigest(identity.map(field => final[field])))
             refuse("foreign_result_identity");
-        if (value.stage !== "compose" || value.outcome !== "accepted" || hybridDigest(value.details) !== hybridDigest(original.details)
+        const details = this.#migrationRecord ? { ...original.details, migration_record: this.#migrationRecord } : original.details;
+        if (value.stage !== this.#original.authoringStage() || value.outcome !== "accepted" || hybridDigest(value.details) !== hybridDigest(details)
             || value.findings.some(finding => finding.severity !== "minor" && finding.status !== "resolved"))
             refuse("composition_not_accepted_or_plan_changed");
         const inventory = new Map(original.units.map(unit => [unit.id, unit]));
@@ -193,7 +355,21 @@ export class PreparedMemoryCompositionAcceptance {
             for (const worker of this.#workers)
                 if (settled(context, this.#scope, worker.id, worker.harness, this.#registrationSha256, assigned).authority !== worker.authority)
                     refuse("work_settlement_changed");
+            if (this.#publication) {
+                const publication = readMemoryUpgradePublication(context, this.#publication.binding);
+                if (!publication?.completed || publication.plan.sha256 !== this.#publication.sha256)
+                    refuse("publication_custody_changed");
+            }
         });
     }
-    revalidate(context) { this.#observed.revalidate(); this.assertCustody(context); }
+    revalidate(context) {
+        if (this.#observed)
+            this.#observed.revalidate();
+        else {
+            const hashes = ObservedMemorySources.capture(roots(context, this.#scope), this.outputLocations()).hashes();
+            if (this.settledArtifacts().some(({ artifact }) => hashes.get(memorySourceKey(artifact.root, artifact.path)) !== artifact.sha256))
+                refuse("current_output_bytes_changed");
+        }
+        this.assertCustody(context);
+    }
 }

package/dist/services/memory-composition-graph.js

@@ -1,7 +1,7 @@
 import { AppError } from "../shared/errors.js";
 import { localEnvironmentAllowed } from "./workspace-files.js";
-function refuse(reason) {
-    throw new AppError("memory_stage_result_invalid", "Memory composition graph cannot be dispatched", 2, { reason, phase: "prepare", effect: "no_effect" });
+function refuse(reason, details = {}) {
+    throw new AppError("memory_stage_result_invalid", "Memory composition graph cannot be dispatched", 2, { ...details, reason, phase: "prepare", effect: "no_effect" });
 }
 // Portable scopes must remain safe on case-insensitive/normalizing filesystems.
 const physicalPath = (value) => value.normalize("NFC").toLowerCase();
@@ -9,8 +9,10 @@ const projectConfigurationPaths = [".memory-bank/dd-flow/project-execution.json"
 /** Exact project-owned defaults, never directory or case aliases of canon. */
 export function memoryProjectConfigurationPath(value) { return projectConfigurationPaths.includes(value); }
 /** Check both assigned directories and their concrete output descendants. */
-export function memoryCompositionOutputAllowed(value) {
-    if (overlaps(value, ".memory-bank/dd-flow") && !memoryProjectConfigurationPath(value))
+export function memoryCompositionOutputAllowed(value, upgradeWritePaths) {
+    if (upgradeWritePaths && !upgradeWritePaths.has(value))
+        return false;
+    if (!upgradeWritePaths && overlaps(value, ".memory-bank/dd-flow") && !memoryProjectConfigurationPath(value))
         return false;
     return value.split("/").every(part => localEnvironmentAllowed(part)
         && ![".git", "node_modules", ".dd-flow"].includes(physicalPath(part)));
@@ -23,7 +25,9 @@ function overlaps(left, right) {
  * semantic graph checks precede Work allocation, not merely worker dispatch.
  * They do not grant filesystem access or replace frozen profile/Work custody.
  */
-export function validateMemoryCompositionGraph(value) {
+export function validateMemoryCompositionGraph(value, upgradePaths, mechanicalUnits) {
+    if (mechanicalUnits && !upgradePaths)
+        refuse("missing_upgrade_authority");
     const result = value;
     const unresolved = result.units.findIndex(unit => unit.applicability === "unknown");
     if (unresolved !== -1)
@@ -49,17 +53,24 @@ export function validateMemoryCompositionGraph(value) {
             // entry, not selected canon. Never grant their enclosing directory or
             // case/normalization aliases; the installed prompt/schema pack is sealed.
             const projectConfig = memoryProjectConfigurationPath(scope.path);
-            if (scope.root === "workspace" && !projectConfig && [".memory-bank/mbb", ".memory-bank/dd-flow"].some(canonical => overlaps(scope.path, canonical)))
+            if (!upgradePaths && scope.root === "workspace" && !projectConfig && [".memory-bank/mbb", ".memory-bank/dd-flow"].some(canonical => overlaps(scope.path, canonical)))
                 refuse("canonical_composition_write");
+            const selectedPaths = upgradePaths && scope.root === "workspace" ? new Set(work.unit_ids.flatMap(id => [...upgradePaths.get(id) ?? []])) : undefined;
             // A contained semantic scope is not permission to alter credentials,
             // repository metadata, installed dependencies or runtime state.
-            if (!memoryCompositionOutputAllowed(scope.path))
-                refuse("private_composition_write");
+            if (!memoryCompositionOutputAllowed(scope.path, selectedPaths))
+                refuse("private_composition_write", {
+                    work_key: work.key, scope: { ...scope },
+                    hint: selectedPaths && work.unit_ids.every(id => mechanicalUnits?.has(id))
+                        ? "These units are mechanical: remove their agent Work and use memory upgrade publish after graph registration. Do not change accepted predecessor or ownership files."
+                        : selectedPaths ? "This path is outside this Work's accepted upgrade authoring paths. Mechanical canonical/generated changes use memory upgrade publish, not agent workspace writes. Correct only the proposed scopes; keep accepted predecessor and ownership files unchanged."
+                            : "Remove the private filesystem scope from the proposed Work; credentials, repository metadata and runtime state are not semantic outputs."
+                });
             if (scope.root === "run" && ["execution-bundle", "run.json"].some(authority => overlaps(scope.path, authority)))
                 refuse("authority_composition_write");
             // Mechanical RUN files and another Work's evidence are never semantic outputs.
             if (scope.root === "run") {
-                const namespace = `memory-artifacts/compose/${work.key}`;
+                const namespace = `memory-artifacts/${upgradePaths ? "upgrade" : "compose"}/${work.key}`;
                 if (scope.path !== namespace && !scope.path.startsWith(`${namespace}/`))
                     refuse("foreign_composition_run_write");
             }
@@ -107,15 +118,35 @@ export function validateMemoryCompositionGraph(value) {
         || assemblies.some(work => !declared.has(work.key)))
         refuse("invalid_assembly_membership");
     const applicable = new Set(result.units.filter(unit => unit.applicability !== "not-applicable").map(unit => unit.id));
+    for (const unit of mechanicalUnits ?? []) {
+        if (!applicable.has(unit) || upgradePaths?.has(unit))
+            refuse("invalid_mechanical_unit");
+        const assigned = works.filter(work => work.unit_ids.includes(unit));
+        if (assigned.length)
+            refuse("mechanical_unit_cannot_allocate_agent_work", {
+                unit_id: unit, work_keys: assigned.map(work => work.key).slice(0, 8),
+                hint: "Remove this unit from agent Work assignments, but keep the unit in the result inventory. CLI owns its mechanical publication through memory upgrade publish."
+            });
+    }
     for (const work of works)
         if (work.unit_ids.some(id => !applicable.has(id)))
             refuse("inapplicable_composition_work");
     for (const unit of applicable) {
+        if (mechanicalUnits?.has(unit))
+            continue;
         const authors = works.filter(work => work.unit_ids.includes(unit));
         const writers = authors.filter(work => work.role === "writer");
         const collectors = assemblies.filter(work => work.unit_ids.includes(unit));
-        if (!authors.length || !collectors.length)
-            refuse("incomplete_composition_coverage");
+        // Init assembles a new knowledge shelf. Upgrade may reconcile one existing
+        // document without changing its navigation; do not invent a collector Work.
+        // Explicit collectors still depend on every writer, in either flow.
+        if (!authors.length || !upgradePaths && !collectors.length)
+            refuse("incomplete_composition_coverage", {
+                unit_id: unit,
+                hint: upgradePaths
+                    ? "Assign this applicable non-mechanical unit to Work. For preservation evidence only, group it into an existing evidence Work with its RUN-local output; keep accepted unit identities and workspace write scopes unchanged."
+                    : "Assign this applicable unit to composition Work and its index-assembly collector. Keep accepted unit identities unchanged."
+            });
         if (collectors.some(collector => writers.some(writer => !dependsOn(collector.key, writer.key))))
             refuse("assembly_precedes_unit_writers");
     }