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

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

@@ -0,0 +1,375 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { PreparedMemoryStageResult, memorySourceKey } from "./memory-stage-results.js";
+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" });
+}
+function object(bytes, reason) {
+    try {
+        const value = JSON.parse(bytes);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            refuse(reason);
+        return value;
+    }
+    catch {
+        return refuse(reason);
+    }
+}
+function roots(context, scope) {
+    const row = context.db.get("SELECT workspace_root,run_root,run_dir FROM runs WHERE project_id=? AND id=?", [scope.project_id, scope.run_id]);
+    if (!row || !path.isAbsolute(row.workspace_root) || !path.isAbsolute(row.run_root ?? row.run_dir))
+        refuse("assigned_roots_missing");
+    return { workspace: row.workspace_root, run: row.run_root ?? row.run_dir };
+}
+/** SQL-only selection. Neither a completed status nor a mutable result file
+ * can substitute for the output-preparation receipt committed by the memory
+ * Work writer together with its result and WorkSession.
+ */
+function settled(context, scope, workId, harness, registrationSha256, assigned) {
+    const allocation = readWorkBatchCustody(context, workId);
+    if (hybridDigest(allocation.scope) !== hybridDigest(scope))
+        refuse("foreign_work_allocation");
+    const work = context.db.get("SELECT status,result,result_schema FROM works WHERE project_id=? AND run_id=? AND work_id=?", [scope.project_id, scope.run_id, workId]);
+    if (!work || work.status !== "completed" || work.result_schema !== "dd-flow/memory-composition-work-result@1"
+        || typeof work.result !== "string" || !work.result.length || Buffer.byteLength(work.result) > 1024 * 1024)
+        refuse("work_not_settled");
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.composition_work_settlement' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 2", [scope.project_id, scope.run_id, workId]);
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 32768)
+        refuse("work_settlement_receipt_missing");
+    const receipt = object(rows[0].payload_json, "invalid_work_settlement_receipt");
+    const links = context.db.all("SELECT id,session_id,status,result_path,result_receipt_json FROM work_sessions WHERE work_id=? AND status='completed' LIMIT 2", [workId]);
+    if (links.length !== 1 || !links[0].result_receipt_json || Buffer.byteLength(links[0].result_receipt_json) > 32768
+        || context.db.get("SELECT 1 FROM work_sessions WHERE work_id=? AND status='running'", [workId]))
+        refuse("completed_work_session_missing");
+    const link = links[0], publication = object(link.result_receipt_json, "invalid_work_result_receipt");
+    const session = context.db.get("SELECT provider_session_id FROM sessions WHERE project_id=? AND session_id=? AND run_id=? AND harness=?", [scope.project_id, link.session_id, scope.run_id, harness]);
+    if (!session)
+        refuse("work_session_identity_changed");
+    const bytes = Buffer.from(work.result), resultSha256 = hash(bytes);
+    if (hybridDigest(receipt) !== hybridDigest({ schema_id: "dd-flow/memory-composition-work-settlement@1", run_id: scope.run_id, work_id: workId,
+        work_session_id: link.id, session_id: link.session_id, harness, provider_session_id: session.provider_session_id,
+        scope, registration_sha256: registrationSha256, allocation_sha256: hybridDigest(allocation), roots: assigned, result_sha256: resultSha256 }))
+        refuse("work_settlement_custody_changed");
+    if (publication.work_id !== workId || publication.work_session_id !== link.id || publication.status !== "completed" || publication.result_sha256 !== resultSha256
+        || publication.previous_sha256 !== null && (typeof publication.previous_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(publication.previous_sha256)))
+        refuse("work_result_receipt_changed");
+    if (link.result_path !== path.join(assigned.run, "works", workId, "result.json"))
+        refuse("work_result_path_changed");
+    return { bytes, authority: hybridDigest({ receipt, publication }), assigned,
+        evidence: { root: "run", path: `works/${workId}/result.json`, sha256: resultSha256 } };
+}
+/** Final compose output custody, not semantic verification/review/finish.
+ * The blueprint is restored from registration; it is never rewritten using
+ * the final result. Historical worker bytes are schema-checked without
+ * asserting that a dependent assembly left their artifacts untouched.
+ */
+export class PreparedMemoryCompositionAcceptance {
+    #scope;
+    #original;
+    #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 = 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;
+        const batch = original.compositionBatch({ runId: input.scope.run_id, inputSha256: input.binding.inputSha256, executionSha256: input.binding.executionSha256, resultSchema: "dd-flow/memory-composition-work-result@1" });
+        const routes = new Map(original.compositionRoutes().map(route => [route.key, runtimeHarness(route.execution.worker)]));
+        const registrationSha256 = hybridDigest(registration), assigned = roots(context, input.scope);
+        const selected = context.db.readSnapshot(() => works.map(work => {
+            const id = registration.work_ids[work.key], harness = routes.get(work.key);
+            return { key: work.key, id, harness, ...settled(context, input.scope, id, harness, registrationSha256, assigned) };
+        }));
+        const outputs = new Map(selected.map(item => [item.key, validateMemoryCompositionWorkResult(item.bytes, input.engine, {
+                runId: input.scope.run_id, inputSha256: input.binding.inputSha256, executionSha256: input.binding.executionSha256,
+                workId: item.id, workKey: item.key, composition: original, compositionSha256: original.sha256
+            })]));
+        // The admitted graph has ordered all overlapping writers. Use its real
+        // dependencies, not array order, wall-clock timestamps or agent claims.
+        const remaining = new Map(works.map(work => [work.key, work.depends_on.length])), children = new Map();
+        for (const work of works)
+            for (const dependency of work.depends_on)
+                children.set(dependency, [...(children.get(dependency) ?? []), work.key]);
+        const ready = works.filter(work => !work.depends_on.length).map(work => work.key);
+        const current = new Map(), aliases = new Map();
+        for (let index = 0; index < ready.length; index++) {
+            const key = ready[index], output = outputs.get(key), emitted = new Map();
+            for (const unit of output.units)
+                for (const artifact of unit.artifacts) {
+                    const identity = memorySourceKey(artifact.root, artifact.path), alias = memorySourceKey(artifact.root, artifact.path.normalize("NFC").toLowerCase());
+                    if (aliases.has(alias) && aliases.get(alias) !== identity)
+                        refuse("aliased_output_paths");
+                    aliases.set(alias, identity);
+                    const record = emitted.get(identity) ?? { artifact, units: new Set() };
+                    record.units.add(unit.id);
+                    emitted.set(identity, record);
+                }
+            for (const [identity, record] of emitted)
+                current.set(identity, record);
+            for (const child of children.get(key) ?? []) {
+                const count = remaining.get(child) - 1;
+                remaining.set(child, count);
+                if (!count)
+                    ready.push(child);
+            }
+        }
+        if (ready.length !== batch.works.length)
+            refuse("registered_graph_changed");
+        const artifacts = new Map();
+        for (const record of current.values())
+            for (const id of record.units)
+                artifacts.set(id, [...(artifacts.get(id) ?? []), record.artifact]);
+        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() { 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([...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() {
+        const selected = new Map();
+        for (const artifacts of this.#artifacts.values())
+            for (const artifact of artifacts)
+                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");
+        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]));
+        if (value.units.length !== inventory.size || new Set(value.units.map(unit => unit.id)).size !== inventory.size)
+            refuse("changed_unit_coverage");
+        for (const unit of value.units) {
+            const initial = inventory.get(unit.id);
+            if (!initial || unit.aspect !== initial.aspect || unit.applicability !== initial.applicability || unit.applicability === "unknown"
+                || unit.outcome !== (unit.applicability === "not-applicable" ? "not-applicable" : "accepted"))
+                refuse("unaccepted_unit_or_changed_assignment");
+            const expected = this.#artifacts.get(unit.id) ?? [], identities = new Set(unit.artifacts.map(artifact => hybridDigest(artifact)));
+            if (unit.applicability !== "not-applicable" && !expected.length || identities.size !== expected.length
+                || expected.some(artifact => !identities.has(hybridDigest(artifact))))
+                refuse("unit_outputs_not_settled");
+        }
+    }
+    assertCustody(context) {
+        context.db.readSnapshot(() => {
+            if (hybridDigest(readMemoryCompositionRegistration(context, this.#scope)) !== this.#registrationSha256)
+                refuse("registration_changed");
+            const assigned = roots(context, this.#scope);
+            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) {
+        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

@@ -0,0 +1,165 @@
+import { AppError } from "../shared/errors.js";
+import { localEnvironmentAllowed } from "./workspace-files.js";
+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();
+const projectConfigurationPaths = [".memory-bank/dd-flow/project-execution.json", ".memory-bank/dd-flow/project-workspace.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, 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)));
+}
+function overlaps(left, right) {
+    const a = physicalPath(left), b = physicalPath(right);
+    return a === "." || b === "." || a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+/** Called only after strict result-schema and contained-path admission. These
+ * 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, upgradePaths, mechanicalUnits) {
+    if (mechanicalUnits && !upgradePaths)
+        refuse("missing_upgrade_authority");
+    const result = value;
+    const unresolved = result.units.findIndex(unit => unit.applicability === "unknown");
+    if (unresolved !== -1)
+        throw new AppError("memory_stage_result_invalid", "Resolve the composition target before assigning Work; missing facts may remain explicit in its content", 2, { reason: "unresolved_composition_applicability", phase: "prepare", effect: "no_effect", unit_id: result.units[unresolved].id,
+            pointer: `/units/${unresolved}/applicability`, hint: "Choose applicable for an intended document or compact shelf, or not-applicable with a reason and no assigned writer. Do not invent missing project facts." });
+    const works = result.details.works;
+    const byKey = new Map(works.map(work => [work.key, work]));
+    if (byKey.size !== works.length || new Set(works.map(work => physicalPath(work.key))).size !== works.length)
+        refuse("duplicate_composition_work");
+    for (const work of works) {
+        if (work.depends_on.some(key => !byKey.has(key)))
+            refuse("unknown_composition_dependency");
+        for (const scopes of [work.read_scopes, work.write_scopes]) {
+            if (new Set(scopes.map(scope => `${scope.root}\0${physicalPath(scope.path)}`)).size !== scopes.length)
+                refuse("duplicate_composition_scope");
+        }
+        for (const scope of work.write_scopes) {
+            if (scope.path === ".")
+                refuse("unbounded_composition_write");
+            if (scope.root === "workspace" && (scope.path !== ".memory-bank" && !scope.path.startsWith(".memory-bank/")))
+                refuse("foreign_composition_write");
+            // These exact files are project-owned defaults consumed by ordinary
+            // 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 (!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, 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/${upgradePaths ? "upgrade" : "compose"}/${work.key}`;
+                if (scope.path !== namespace && !scope.path.startsWith(`${namespace}/`))
+                    refuse("foreign_composition_run_write");
+            }
+        }
+    }
+    // Iterative topological order avoids recursion on an agent-sized graph.
+    const remaining = new Map(works.map(work => [work.key, work.depends_on.length]));
+    const children = new Map();
+    for (const work of works)
+        for (const dependency of work.depends_on) {
+            const list = children.get(dependency) ?? [];
+            list.push(work.key);
+            children.set(dependency, list);
+        }
+    const ready = works.filter(work => !work.depends_on.length).map(work => work.key);
+    const positions = new Map(works.map((work, index) => [work.key, index]));
+    const ancestors = new Map();
+    const dependsOn = (work, dependency) => {
+        const position = positions.get(dependency);
+        return Boolean(ancestors.get(work)[position >>> 5] & (1 << (position & 31)));
+    };
+    for (let cursor = 0; cursor < ready.length; cursor++) {
+        const key = ready[cursor], work = byKey.get(key);
+        const inherited = new Uint32Array(Math.ceil(works.length / 32));
+        for (const dependency of work.depends_on) {
+            const position = positions.get(dependency);
+            inherited[position >>> 5] |= 1 << (position & 31);
+            const prior = ancestors.get(dependency);
+            for (let word = 0; word < prior.length; word++)
+                inherited[word] |= prior[word];
+        }
+        ancestors.set(key, inherited);
+        for (const child of children.get(key) ?? []) {
+            const count = remaining.get(child) - 1;
+            remaining.set(child, count);
+            if (!count)
+                ready.push(child);
+        }
+    }
+    if (ready.length !== works.length)
+        refuse("cyclic_composition_dependency");
+    const assemblies = works.filter(work => work.role === "index-assembly");
+    const declared = new Set(result.details.assembly_work_keys);
+    if (declared.size !== result.details.assembly_work_keys.length || declared.size !== assemblies.length
+        || 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));
+        // 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");
+    }
+    for (let index = 0; index < works.length; index++) {
+        const left = works[index];
+        for (const right of works.slice(index + 1)) {
+            if (dependsOn(left.key, right.key) || dependsOn(right.key, left.key))
+                continue;
+            if (left.write_scopes.some(a => right.write_scopes.some(b => a.root === b.root && overlaps(a.path, b.path))))
+                refuse("unordered_composition_writers");
+            if (left.write_scopes.some(a => right.read_scopes.some(b => a.root === b.root && overlaps(a.path, b.path)))
+                || right.write_scopes.some(a => left.read_scopes.some(b => a.root === b.root && overlaps(a.path, b.path))))
+                refuse("unordered_composition_read_write");
+        }
+    }
+}