@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.138

package/dist/services/memory-preflight-bootstrap-custody.js

@@ -0,0 +1,115 @@
+import { AppError } from "../shared/errors.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { PreparedMemoryInitProjectBootstrap } from "./memory-init-project-bootstrap.js";
+import { PreparedMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { observeMemoryInitSourceInventory } from "./memory-init-preflight.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+function refuse(reason) {
+    throw new AppError("memory_preflight_bootstrap_custody_invalid", "Preflight does not consume its independently accepted bootstrap", 2, { reason, effect: "no_effect" });
+}
+/** Bootstrap-specific admission for the productive preflight handler. Result
+ * schema, RUN/input identity, physical revalidation and coordinator settlement
+ * remain separate handler obligations; this is not stage completion authority.
+ */
+export class PreparedMemoryPreflightBootstrapCustody {
+    #scope;
+    #authoritySha256;
+    #resultSha256;
+    #physical = null;
+    #semanticScope;
+    constructor(scope, authoritySha256, resultSha256, semanticScope) {
+        this.#scope = { ...scope };
+        this.#authoritySha256 = authoritySha256;
+        this.#resultSha256 = resultSha256;
+        this.#semanticScope = semanticScope;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.execution instanceof FrozenGenericExecution) || !(input.result instanceof PreparedMemoryStageResult)
+            || input.execution.settings.flow_id !== "mb-init")
+            refuse("unprepared_preflight");
+        const frozen = input.execution.snapshot();
+        const scope = { requestId: frozen.scope.requestId, projectRoot: frozen.scope.projectRoot, workspaceRoot: frozen.scope.workspace };
+        const accepted = readMemoryInitBootstrapReadiness(context, scope);
+        if (!accepted || accepted.authority.binding.execution_sha256 !== input.execution.sha256)
+            refuse("missing_or_foreign_bootstrap");
+        const result = input.result.value(), details = result.details;
+        if (result.stage !== "preflight" || result.schema_id !== "dd-flow/mb-init-preflight-result@1")
+            refuse("foreign_stage");
+        const semanticScope = details.semantic_scope;
+        if (typeof semanticScope !== "string" || !semanticScope.trim() || Buffer.byteLength(semanticScope) > 16384 || semanticScope.includes("\0"))
+            refuse("invalid_semantic_scope");
+        return new PreparedMemoryPreflightBootstrapCustody(scope, hybridDigest(accepted.authority), input.result.sha256, semanticScope);
+    }
+    /** Productive preparation additionally restores the request-owned bootstrap
+     * and rechecks its physical prerequisites. No publication or model probe is
+     * dispatched. Result/RUN input and invoking assertBundleReference remain
+     * obligations of the registered stage handler, not this bootstrap fence.
+     */
+    static preparePhysical(context, input) {
+        if (!(input.engine instanceof AdmittedFrozenEngine))
+            refuse("selected_engine_not_admitted");
+        const prepared = PreparedMemoryPreflightBootstrapCustody.prepare(context, input);
+        const bootstrap = PreparedMemoryInitProjectBootstrap.restore(context, input.execution);
+        PreparedMemoryInitBootstrapReadiness.prepare(context, { bootstrap, engine: input.engine });
+        const inventory = prepared.observeInventory(context);
+        prepared.assertCustody(context);
+        prepared.#physical = { bootstrap, engine: input.engine, inventorySha256: inventory.sha256 };
+        return prepared;
+    }
+    /** Outside writers: recheck current root/source/tools/pack/engine/storage.
+     * The acceptance writer uses assertCustody only, with no filesystem access.
+     */
+    revalidate(context) {
+        if (!this.#physical)
+            refuse("physical_preparation_required");
+        PreparedMemoryInitBootstrapReadiness.prepare(context, this.#physical);
+        if (this.observeInventory(context).sha256 !== this.#physical.inventorySha256)
+            refuse("preserved_inventory_changed");
+        this.assertCustody(context);
+    }
+    /** SQL-only fence for the handler's eventual atomic acceptance writer. */
+    assertCustody(context) {
+        const accepted = readMemoryInitBootstrapReadiness(context, this.#scope);
+        if (!accepted || hybridDigest(accepted.authority) !== this.#authoritySha256)
+            refuse("bootstrap_changed_after_preparation");
+    }
+    /** Exact manifest reference, not merely a same-hash path supplied by an agent.
+     * RUN/input identity is separately fenced by its prepared result binding and
+     * descriptor settlement; this method alone is not RUN execution authority.
+     */
+    assertBundleReference(context, bundle, result) {
+        if (!(bundle instanceof RetainedExecutionBundle) || !(result instanceof PreparedMemoryStageResult))
+            refuse("unprepared_bundle_reference");
+        context.db.readSnapshot(() => {
+            this.assertCustody(context);
+            const frozen = bundle.execution.snapshot(), accepted = readMemoryInitBootstrapReadiness(context, this.#scope);
+            if (!accepted)
+                refuse("missing_or_foreign_bootstrap");
+            const value = result.value(), details = value.details;
+            if (bundle.descriptor.descriptor.id !== "mb-init" || bundle.execution.sha256 !== accepted.authority.binding.execution_sha256
+                || frozen.scope.requestId !== this.#scope.requestId || frozen.scope.projectRoot !== this.#scope.projectRoot || frozen.scope.workspace !== this.#scope.workspaceRoot
+                || value.stage !== "preflight" || value.run_id !== bundle.manifest.run_id
+                || bundle.manifest.bootstrap_receipts.length !== 1
+                || bundle.manifest.bootstrap_receipts[0].sha256 !== accepted.authority.bootstrap_sha256
+                || !bundle.blob(bundle.manifest.bootstrap_receipts[0].path).equals(Buffer.from(JSON.stringify(accepted.authority.receipt))))
+                refuse("foreign_bundle_bootstrap_reference");
+            if (details.semantic_scope !== this.#semanticScope)
+                refuse("foreign_preflight_semantic_scope");
+            // Bootstrap/physical preparation belongs to the exact result that was
+            // checked, not another schema-valid result with the same selected fields.
+            if (result.sha256 !== this.#resultSha256)
+                refuse("preflight_result_changed_after_preparation");
+        });
+    }
+    observeInventory(context) {
+        const accepted = readMemoryInitBootstrapReadiness(context, this.#scope);
+        if (!accepted)
+            refuse("missing_or_foreign_bootstrap");
+        return observeMemoryInitSourceInventory(accepted.authority.binding.target, accepted.authority.receipt.baseline_sha256, context.env);
+    }
+}

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

@@ -0,0 +1,259 @@
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { PreparedMemoryPreflightBootstrapCustody } from "./memory-preflight-bootstrap-custody.js";
+import { PreparedMemoryBaselinePreservation } from "./memory-baseline-preservation.js";
+import { PreparedMemoryResultBinding } from "./memory-result-binding.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { observeMemoryInitSourceInventory } from "./memory-init-preflight.js";
+import { readMemoryInitProjectBootstrap } from "./memory-init-project-bootstrap.js";
+import { readPublishedMemoryReferenceInventory } from "./memory-layer-publication.js";
+import path from "node:path";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator, readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { assertPreparedRunBundleSqlAuthority, readFlowRunExecutionBundle } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { readMemoryCompositionRegistration } from "./memory-composition-registration.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) {
+    throw new AppError("memory_preflight_handler_invalid", "Memory preflight cannot accept this execution or result", 2, { reason, effect: "no_effect" });
+}
+function bounded(bytes, empty = false) {
+    if (!(bytes instanceof Uint8Array) || bytes.length > 1024 * 1024 || !empty && !bytes.length)
+        refuse("invalid_result_bytes");
+}
+function selected(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.descriptor.entry_stage !== "preflight")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const scope = { projectId: project.id, runId: input.runId, stage: "preflight" };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const stage = JSON.parse(run.index_json).stage_runs.find((entry) => entry.stage === "preflight");
+    return { bundle, scope, accepted: stage?.status === "done" };
+}
+/** Proposed references select a subset, never establish the source allowlist.
+ * Only regular files in the independently restored bootstrap baseline may be
+ * preflight project evidence. Ignored/private, linked, runtime and canon paths
+ * are not silently read as project truth. Their other proof roles are separate.
+ */
+export function captureMemoryPreflightSources(context, bundle, bytes) {
+    return captureSources(context, bundle, bytes).sources;
+}
+/** Historical blueprint support comes only from the independently registered
+ * graph. It is not a current output observation or a caller-supplied allowlist. */
+export function captureRegisteredMemoryCompositionSources(context, bundle, registrationScope) {
+    const registration = readMemoryCompositionRegistration(context, registrationScope);
+    if (registration.run_id !== bundle.manifest.run_id || registration.execution_sha256 !== bundle.execution.sha256)
+        refuse("foreign_composition_registration");
+    return { ...captureSources(context, bundle, Buffer.from(registration.result_base64, "base64"), true),
+        registrationSha256: hybridDigest(registration), inputSha256: registration.input_sha256 };
+}
+function captureSources(context, bundle, bytes, registeredBlueprint = false) {
+    bounded(bytes);
+    if (!(bundle instanceof RetainedExecutionBundle) || bundle.descriptor.descriptor.id !== "mb-init")
+        refuse("prepared_memory_bundle_required");
+    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution), scope = bundle.execution.snapshot().scope;
+    const ready = readMemoryInitBootstrapReadiness(context, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace });
+    if (!ready || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_bootstrap_required");
+    const inventory = observeMemoryInitSourceInventory(ready.authority.binding.target, ready.authority.receipt.baseline_sha256, context.env);
+    const allowed = new Map(inventory.entries.filter(entry => entry.kind === "file").map(entry => [entry.path, entry.sha256]));
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        refuse("invalid_result_json");
+    }
+    const registered = readMemoryInitProjectBootstrap(context, ready.authority.binding.scope);
+    if (!registered)
+        refuse("accepted_bootstrap_required");
+    const owned = readPublishedMemoryReferenceInventory(context.ddFlowHome, { ...ready.authority.binding.scope,
+        targetSha256: registered.receipt.target_sha256, layerSha256: registered.receipt.layer_sha256,
+        packSha256: ready.authority.binding.pack_sha256, installationSha256: ready.authority.binding.installation_manifest_sha256 }, ready.authority.binding.target, registered.receipt.layer_publication_sha256, registered.receipt.draft_identity_sha256);
+    const receipts = new Map(bundle.manifest.bootstrap_receipts.map(ref => [`execution-bundle/${ref.path}`, ref.sha256]));
+    for (const ref of ready.authority.evidence) {
+        const selected = bundle.manifest.inventory.find(item => item.path === ref.path && item.sha256 === ref.sha256);
+        if (selected)
+            receipts.set(`execution-bundle/${ref.path}`, ref.sha256);
+    }
+    let run = null;
+    const acceptedReferences = new Map();
+    const selectRun = () => run ??= assertPreparedRunBundleSqlAuthority(context, { projectId: ready.projectId, runId: bundle.manifest.run_id }, bundle);
+    let selectedAccepted = false;
+    const rejectProposal = (reason, reference, message) => {
+        const proposal = value;
+        if (registeredBlueprint || proposal.run_id !== bundle.manifest.run_id || typeof proposal.stage !== "string" || typeof proposal.input_sha256 !== "string")
+            refuse("unselected_preflight_source");
+        const index = JSON.parse(selectRun().index_json), stage = index.stage_runs.find((stage) => stage.stage === proposal.stage);
+        if (index.current_stage !== proposal.stage || stage?.status !== "running" || stage.input_sha256 !== proposal.input_sha256)
+            refuse("unselected_preflight_source");
+        throw new AppError("memory_preflight_handler_invalid", message, 2, { reason, ...reference, phase: "prepare", effect: "no_effect", recoverable: true });
+    };
+    const proposedMismatches = [];
+    const pending = [{ value, role: "source", original: false }], locations = new Map(), expected = new Map(), historical = new Map();
+    let nodes = 0;
+    while (pending.length) {
+        if (++nodes > 100000)
+            refuse("result_tree_exceeds_bound");
+        const entry = pending.pop(), node = entry.value;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                pending.push({ ...entry, value: child });
+            continue;
+        }
+        if (!node || typeof node !== "object")
+            continue;
+        const record = node;
+        if (typeof record.root === "string" && typeof record.path === "string" && typeof record.sha256 === "string") {
+            let selected;
+            if (["project", "workspace"].includes(record.root)) {
+                selected = allowed.get(record.path) ?? undefined;
+                if (!entry.original && ["evidence", "artifacts"].includes(entry.role))
+                    selected ??= owned.artifacts.get(record.path);
+            }
+            else if (!entry.original && (entry.role === "evidence" || entry.role === "artifacts")) {
+                if (record.root === "run") {
+                    selected = receipts.get(record.path);
+                    if (selected === undefined) {
+                        if (!selectedAccepted) {
+                            let stage = value.stage;
+                            const declared = bundle.descriptor.descriptor.stages.find(item => item.id === stage);
+                            if (!declared)
+                                refuse("unselected_preflight_source");
+                            selectedAccepted = true;
+                            const index = JSON.parse(selectRun().index_json);
+                            const acceptedStage = index.stage_runs?.some((item) => item.stage === stage && item.status === "done");
+                            if (acceptedStage)
+                                readAcceptedStageData(context, { projectId: ready.projectId, runId: bundle.manifest.run_id, stage: declared.id });
+                            if (index.current_stage === stage || acceptedStage) {
+                                const input = readDescriptorStageInput(context, { projectId: ready.projectId, runId: bundle.manifest.run_id, stage: declared.id }, bundle, true, acceptedStage);
+                                acceptedReferences.set(`${declared.directory}/stage-input.json`, input.inputSha256);
+                            }
+                            const visited = new Set();
+                            while (stage && !visited.has(stage)) {
+                                visited.add(stage);
+                                stage = bundle.descriptor.descriptor.edges.find(edge => edge.to === stage && edge.on === "accepted")?.from;
+                                if (stage && index.stage_runs?.some((item) => item.stage === stage && item.status === "done")) {
+                                    const accepted = readAcceptedStageData(context, { projectId: ready.projectId, runId: bundle.manifest.run_id, stage });
+                                    const result = JSON.parse(accepted.bytes.toString("utf8"));
+                                    if (result.schema_id !== `dd-flow/mb-init-${stage}-result@1` || result.run_id !== bundle.manifest.run_id
+                                        || result.stage !== stage || !(result.outcome === "accepted" || stage === "verify" && result.outcome === "needs_repair" && bundle.descriptor.successor("verify", "needs_repair") === "review"))
+                                        refuse("unselected_preflight_source");
+                                    acceptedReferences.set(accepted.result.path, accepted.result.sha256);
+                                    const input = readDescriptorStageInput(context, { projectId: ready.projectId, runId: bundle.manifest.run_id, stage }, bundle, true, true);
+                                    acceptedReferences.set(`${bundle.descriptor.stage(stage).directory}/stage-input.json`, input.inputSha256);
+                                }
+                            }
+                        }
+                        selected = acceptedReferences.get(record.path);
+                    }
+                }
+                if (record.root === "canon")
+                    selected = owned.canon.get(record.path);
+            }
+            if (selected === undefined)
+                return rejectProposal("unselected_preflight_source", { root: record.root, path: record.path }, "Remove or replace this unselected reference with an admitted project source, preflight result or Stage input; Git metadata is not project source evidence");
+            if (selected !== record.sha256) {
+                if (registeredBlueprint)
+                    refuse("registered_source_sha256_mismatch");
+                proposedMismatches.push({ root: record.root, path: record.path });
+            }
+            const key = memorySourceKey(record.root, record.path);
+            if (registeredBlueprint && !entry.original && ["evidence", "artifacts"].includes(entry.role)
+                && ["project", "workspace"].includes(record.root) && !allowed.has(record.path) && owned.artifacts.get(record.path) === selected) {
+                historical.set(key, selected);
+            }
+            else {
+                expected.set(key, selected);
+                locations.set(key, { root: record.root, path: record.path });
+            }
+        }
+        for (const [key, child] of Object.entries(record))
+            pending.push({ value: child, role: ["evidence", "artifacts"].includes(key) ? key : entry.role,
+                original: entry.original || key === "inventory" });
+    }
+    const selectedRun = [...locations.values()].some(location => location.root === "run") ? selectRun() : null;
+    const observation = ObservedMemorySources.capture({ project: scope.projectRoot, workspace: scope.workspace,
+        canon: path.join(scope.workspace, ".memory-bank"), ...(selectedRun ? { run: selectedRun.run_root ?? selectedRun.run_dir } : {}) }, [...locations.values()]);
+    const hashes = observation.hashes();
+    for (const [key, sha256] of expected)
+        if (hashes.get(key) !== sha256)
+            refuse("preflight_source_changed");
+    preservation.assertCustody(context);
+    if (proposedMismatches.length) {
+        rejectProposal("proposed_source_sha256_mismatch", proposedMismatches[0], "Proposed evidence SHA differs from the CLI-selected source; correct the result reference without changing the source");
+    }
+    return { sources: observation, historical };
+}
+/** The bootstrap-specific acceptance part of the preflight handler. It does
+ * not establish RUN/input/coordinator authority; finishMemoryPreflight supplies
+ * those independently. Kept separate for actual bootstrap qualification.
+ */
+export class PreparedMemoryPreflightAcceptance {
+    #bundle;
+    #result;
+    #bootstrap;
+    constructor(bundle, result, bootstrap) {
+        this.#bundle = bundle;
+        this.#result = result;
+        this.#bootstrap = bootstrap;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bundle instanceof RetainedExecutionBundle) || !(input.result instanceof PreparedMemoryStageResult))
+            refuse("prepared_bundle_and_result_required");
+        const value = JSON.parse(input.result.bytes().toString("utf8"));
+        // Preliminary units/minor findings are allowed by the frozen contract;
+        // DISCOVER establishes final inventory. Material blockers cannot advance.
+        if (value.stage !== "preflight" || value.outcome !== "accepted"
+            || value.findings.some((finding) => finding.severity !== "minor" && finding.status !== "resolved"))
+            refuse("preflight_not_accepted");
+        const bootstrap = PreparedMemoryPreflightBootstrapCustody.preparePhysical(context, { execution: input.bundle.execution, result: input.result, engine: input.bundle.engine() });
+        const prepared = new PreparedMemoryPreflightAcceptance(input.bundle, input.result, bootstrap);
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    revalidate(context) { this.#bootstrap.revalidate(context); this.assertCustody(context); }
+    assertCustody(context) { this.#bootstrap.assertBundleReference(context, this.#bundle, this.#result); }
+}
+/** Handler implementation awaiting the complete memory-handler registry. No
+ * RUN allocation, profile mutation, installation fallback or provider dispatch.
+ * Returns the retained prompt for the controller's separately fenced dispatch.
+ */
+export function startMemoryPreflight(context, input) {
+    bounded(input.bytes, true);
+    const { bundle, accepted } = selected(context, input);
+    if (accepted)
+        refuse("use_accepted_finish_replay");
+    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: "preflight" });
+    preservation.revalidate(context);
+    const stage = start.apply(context, writer => preservation.assertCustody(writer));
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "preflight" });
+    preservation.revalidate(context);
+    const work = coordinator.apply(context, writer => preservation.assertCustody(writer));
+    return { ...stage, ...work };
+}
+export function finishMemoryPreflight(context, input) {
+    bounded(input.bytes);
+    const { bundle, scope, accepted } = selected(context, input);
+    const sources = captureMemoryPreflightSources(context, bundle, input.bytes);
+    const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle,
+        sources, acceptedReplay: accepted });
+    const replay = binding.acceptedBytes();
+    if (replay && !replay.equals(input.bytes))
+        refuse("accepted_result_changed");
+    const result = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
+    const acceptance = PreparedMemoryPreflightAcceptance.prepare(context, { bundle, result });
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "preflight", bytes: result.bytes() });
+    binding.revalidate(context);
+    acceptance.revalidate(context);
+    return settlement.apply(context, writer => { binding.assertCustody(writer); acceptance.assertCustody(writer); });
+}