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

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

@@ -0,0 +1,585 @@
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { PreparedMemoryBaselinePreservation } from "./memory-baseline-preservation.js";
+import { PreparedAcceptedMemoryComposition } from "./memory-accepted-composition.js";
+import { PreparedAcceptedMemoryVerification } from "./memory-verification-receipt.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator } from "./descriptor-stage-coordinator.js";
+import { PreparedMemoryInitialReviewInputs, memoryReviewEvidenceTriples } from "./memory-review-inputs.js";
+import { registerMemoryInitialReview } from "./memory-review-registration.js";
+import { PreparedMemoryInitialReviewAcceptance, projectMemoryReviewResult } from "./memory-review-acceptance.js";
+import { runtimeCommand } from "./runtime-command.js";
+import { PreparedRetainedMemoryReviewAuthority } from "./memory-retained-review-authority.js";
+import { PreparedRetainedMemoryReviewResults } from "./memory-retained-review-results.js";
+import { PreparedMemoryInitialCorrectionPlan } from "./memory-review-correction-plan.js";
+import { PreparedRegisteredMemoryCorrections, registerMemoryInitialCorrections } from "./memory-repair-registration.js";
+import { PreparedMemoryRepairWorkBaseline } from "./memory-repair-work-baseline.js";
+import { PreparedMemoryRepairCurrentView } from "./memory-repair-current-view.js";
+import { PreparedMemoryRepairPublicationSource } from "./memory-repair-publication-source.js";
+import { PreparedRetainedMemoryRepairPublication } from "./memory-repair-publication.js";
+import { PreparedPublishedMemoryRepairWorkResult } from "./memory-repair-work-custody.js";
+import { finishPublishedMemoryRepairWork } from "./work-registry.js";
+import { PreparedBoundMemoryRepairCopy, PreparedMemoryRepairWriterCopy } from "./memory-repair-writer-copy.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedMemoryResultBinding } from "./memory-result-binding.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { PreparedMemoryInitialReviewReceipt, PreparedAcceptedMemoryInitialReview } from "./memory-review-receipt.js";
+import { PreparedCompletedMemoryCorrectionWave } from "./memory-completed-correction-wave.js";
+import { PreparedCorrectedMemoryReviewInputs } from "./memory-corrected-review-inputs.js";
+import { PreparedMemoryVerificationChecks } from "./memory-verification-checks.js";
+import { PreparedMemoryCorrectionCheckReceipt } from "./memory-correction-check-receipt.js";
+import { PreparedSecondMemoryReviewAcceptance } from "./memory-second-review-acceptance.js";
+import { registerCorrectedMemoryReview, PreparedRegisteredCorrectedMemoryReview } from "./memory-corrected-review-registration.js";
+import { PreparedCorrectedMemoryReviewAcceptance } from "./memory-corrected-review-acceptance.js";
+import { PreparedMemoryCorrectedReviewReceipt, PreparedAcceptedMemoryCorrectedReview } from "./memory-corrected-review-receipt.js";
+import { PreparedMemorySecondCorrectionPlan } from "./memory-second-correction-plan.js";
+import { registerMemorySecondCorrections } from "./memory-second-repair-registration.js";
+import { PreparedRetainedSecondMemoryRepairs } from "./memory-retained-second-repairs.js";
+import { PreparedSecondMemoryRepairSource } from "./memory-second-repair-source.js";
+import { PreparedSecondMemoryRepairBaseline } from "./memory-second-repair-baseline.js";
+import { PreparedRetainedSecondMemoryBaseline } from "./memory-retained-second-baseline.js";
+import { PreparedSecondMemoryRepairLaunch } from "./memory-second-repair-launch.js";
+import { PreparedSettledMemoryRepair } from "./memory-repair-history.js";
+import { PreparedSecondCorrectedMemoryReviewInputs } from "./memory-second-corrected-review-inputs.js";
+function refuse(reason) {
+    throw new AppError("memory_review_handler_invalid", "Memory review lacks accepted verification and current document custody", 2, { reason, effect: "no_effect" });
+}
+/** Initial independent-review entry; does not register reviewers, copy a
+ * workspace or dispatch a provider. Those operations require the separately
+ * registered per-unit/wave input adapter, not just read_only=true. The full
+ * memory handler group remains unregistered until review/repair/finish is ready.
+ */
+export function startMemoryReview(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || bundle.descriptor.successor("verify", "accepted") !== "review"
+        || bundle.descriptor.successor("review", "accepted") !== "finish")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    if (index.stage_runs.find((stage) => stage.stage === "review")?.status === "done")
+        refuse("use_accepted_finish_replay");
+    const composition = PreparedAcceptedMemoryComposition.prepare(context, { scope, bundle });
+    const preservation = bundle.descriptor.descriptor.id === "mb-upgrade" ? composition : PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const data = readAcceptedStageData(context, { ...scope, stage: "verify" });
+    const verification = PreparedAcceptedMemoryVerification.prepare(context, { ...scope, bytes: data.bytes });
+    const fence = (writer) => { preservation.assertCustody(writer); composition.assertCustody(writer); verification.assertCustody(writer); };
+    const revalidate = () => { preservation.revalidate(context); composition.revalidate(context); verification.revalidate(context); };
+    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: "review" });
+    revalidate();
+    const stage = start.apply(context, fence);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "review" });
+    revalidate();
+    return { ...stage, ...coordinator.apply(context, fence) };
+}
+/** Independent initial wave allocation only; review remains unregistered in
+ * the productive handler group until repair and terminal settlement are ready.
+ */
+export function registerMemoryReviewFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const inputs = PreparedMemoryInitialReviewInputs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    return registerMemoryInitialReview(context, inputs);
+}
+/** Collect registered initial-wave results without closing the Stage or
+ * granting correction authority. Repair/finish consume separately admitted
+ * views and cannot manufacture this proof from coordinator result JSON.
+ */
+export function collectMemoryInitialReviewFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const inputs = PreparedMemoryInitialReviewInputs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    return PreparedMemoryInitialReviewAcceptance.prepare(context, inputs, bundle);
+}
+/** Close only independently accepted initial or selective review. Registered
+ * repairs select the corrected path; missing custody never falls back to the
+ * original document view. Accepted replay is historical, not re-admission. */
+export function finishMemoryReview(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_result_bytes");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || bundle.descriptor.successor("verify", "accepted") !== "review"
+        || bundle.descriptor.successor("review", "accepted") !== "finish")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    const stage = index.stage_runs.find((stage) => stage.stage === "review");
+    if (!stage || typeof stage.attempt !== "string")
+        refuse("review_identity_missing");
+    if (stage?.status === "done") {
+        const corrected = context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.corrected_review_acceptance' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.attempt')=? LIMIT 1", [scope.projectId, scope.runId, stage.attempt]);
+        const accepted = corrected ? PreparedAcceptedMemoryCorrectedReview.prepare(context, { scope, bundle, bytes: input.bytes })
+            : PreparedAcceptedMemoryInitialReview.prepare(context, { scope, bundle, bytes: input.bytes });
+        const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "review" });
+        accepted.revalidate(context);
+        return settlement.apply(context, writer => accepted.assertCustody(writer));
+    }
+    const corrected = context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.repair_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=? LIMIT 1", [scope.projectId, scope.runId, stage?.attempt]);
+    const second = context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.second_repair_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=? LIMIT 1", [scope.projectId, scope.runId, stage.attempt]);
+    const inputs = second ? PreparedSecondCorrectedMemoryReviewInputs.prepareFromBundle(context, { scope, bundle })
+        : corrected ? PreparedCorrectedMemoryReviewInputs.prepareFromBundle(context, { scope, bundle })
+            : PreparedMemoryInitialReviewInputs.prepare(context, { scope, bundle });
+    const wave = PreparedSecondCorrectedMemoryReviewInputs.isPrepared(inputs)
+        ? PreparedSecondMemoryReviewAcceptance.prepare(context, PreparedRegisteredCorrectedMemoryReview.restore(context, inputs, PreparedMemoryCorrectionCheckReceipt.restore(context, inputs)))
+        : PreparedCorrectedMemoryReviewInputs.isPrepared(inputs)
+            ? PreparedCorrectedMemoryReviewAcceptance.prepare(context, PreparedRegisteredCorrectedMemoryReview.restore(context, inputs, PreparedMemoryCorrectionCheckReceipt.restore(context, inputs)))
+            : PreparedMemoryInitialReviewAcceptance.prepare(context, inputs, bundle);
+    const view = inputs.value();
+    const roots = { run: run.run_root ?? run.run_dir, workspace: bundle.execution.snapshot().scope.workspace };
+    const sources = ObservedMemorySources.capture(roots, [...view.run_inputs.map(ref => ({ root: ref.root, path: ref.path })),
+        ...wave.references().map(ref => ({ root: "run", path: ref.result.path }))]);
+    const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, stage: "review", flow: bundle.descriptor,
+        execution: bundle.execution, bundle, sources,
+        historicalEvidence: memoryReviewEvidenceTriples(view.unit_inventory) });
+    const proposal = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
+    const projection = wave.resultProjection();
+    if (projection.outcome !== "accepted") {
+        const correctionWave = view.wave + 1;
+        const command = runtimeCommand(context, ["memory", "review", view.wave ? "selective-collect" : "collect",
+            "--run", input.runId, "--project-root", input.projectRoot, ...(view.wave ? ["--wave", String(view.wave)] : []), "--json"]);
+        throw new AppError("memory_review_corrections_required", "Independent review cannot close until its material findings are resolved", 2, { phase: "prepare", effect: "no_effect", recoverable: projection.outcome === "needs_repair" && correctionWave <= 2,
+            projection, result_sha256: proposal.sha256,
+            correction_instruction: projection.outcome === "needs_repair" && correctionWave <= 2
+                ? `Run ${command} to obtain the canonical findings and correction_plan_binding. Author substantive repair tasks and exact owned write_paths; register that plan with the issued memory corrections register command for wave ${correctionWave}, then end this Turn so the controller can dispatch it. Use retry_command only after its checks and independent selective review complete. Do not calculate finding hashes, merge findings, or retry Finish before corrections.`
+                : "The independent review is blocked or its two correction waves are exhausted. Use the issued pause command for the concrete unresolved blocker; do not mark it accepted." });
+    }
+    const result = PreparedMemoryStageResult.prepare(Buffer.from(JSON.stringify(projectMemoryReviewResult(proposal.value(), projection))), bundle.descriptor, binding.binding());
+    const receipt = PreparedCorrectedMemoryReviewAcceptance.isPrepared(wave) || PreparedSecondMemoryReviewAcceptance.isPrepared(wave)
+        ? PreparedMemoryCorrectedReviewReceipt.prepare(context, { scope, wave, result })
+        : PreparedMemoryInitialReviewReceipt.prepare(context, { scope, wave, result });
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "review", bytes: result.bytes() });
+    inputs.revalidate(context);
+    wave.revalidate(context);
+    binding.revalidate(context);
+    return settlement.apply(context, writer => { binding.assertCustody(writer); wave.assertCustody(writer); receipt.record(writer); });
+}
+/** Initial repair plan intake or exact retained-plan replay. A replay does not
+ * re-admit original document bytes after repairs; it only returns the existing
+ * allocated graph. Independent writer/delta admission still owns execution.
+ */
+export function registerMemoryCorrectionsFromStage(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const original = PreparedRetainedMemoryReviewAuthority.prepare(context, { projectId: project.id, runId: input.runId }, bundle);
+    const review = PreparedRetainedMemoryReviewResults.prepare(context, original);
+    try {
+        const retained = PreparedRegisteredMemoryCorrections.restore(context, review, input.bytes);
+        return retained.replay(context);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "memory_repair_registration_invalid" || error.details?.reason !== "repair_registration_missing")
+            throw error;
+    }
+    return registerMemoryInitialCorrections(context, PreparedMemoryInitialCorrectionPlan.prepare(context, review, input.bytes));
+}
+/** Pre-launch original-document receipt only. Launch/start/private copy and
+ * bounded publication remain separate owners; this does not unlock dispatch.
+ */
+export function registerMemoryRepairBaselineFromStage(context, input) {
+    return prepareMemoryRepairBaselineFromStage(context, input).register(context);
+}
+function prepareMemoryRepairBaselineFromStage(context, input) {
+    const registration = prepareMemoryRepairRegistrationFromStage(context, input);
+    const owner = registration.receipt(), batch = registration.batch();
+    const assigned = batch.works.find(item => owner.work_ids[item.key] === input.workId);
+    if (!assigned)
+        refuse("foreign_repair_work");
+    const rows = context.db.all("SELECT json_extract(payload_json,'$.schema_id') AS schema_id FROM audit_events WHERE project_id=? AND event_type='memory.repair_work_baseline' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 2", [owner.scope.project_id, owner.run_id, input.workId]);
+    if (rows.length > 1)
+        refuse("ambiguous_repair_baseline");
+    // An existing baseline is immutable; never promote an admitted original
+    // baseline into a newer current view merely because a peer has finished.
+    if (rows[0]?.schema_id === "dd-flow/memory-repair-work-baseline@2")
+        return PreparedMemoryRepairWorkBaseline.prepare(context, registration, input.workId);
+    const needsCurrent = Boolean(rows.length || assigned.depends_on.length || batch.works.some(item => context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND work_id=? AND status='completed'", [owner.scope.project_id, owner.run_id, owner.work_ids[item.key]])));
+    if (!needsCurrent)
+        return PreparedMemoryRepairWorkBaseline.prepare(context, registration, input.workId);
+    let view;
+    try {
+        view = PreparedMemoryRepairCurrentView.restore(context, registration, input.workId);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "memory_repair_current_view_invalid" || error.details.reason !== "registered_view_required")
+            throw error;
+        // This helper also prepares copy operations. It must not commit a new
+        // view as a hidden side effect before the requested baseline/copy fails.
+        refuse(rows.length ? "registered_current_view_missing" : "current_view_registration_required");
+    }
+    return PreparedMemoryRepairWorkBaseline.prepareFromCurrentView(context, registration, input.workId, view);
+}
+function prepareMemoryRepairRegistrationFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const original = PreparedRetainedMemoryReviewAuthority.prepare(context, { projectId: project.id, runId: input.runId }, bundle);
+    const review = PreparedRetainedMemoryReviewResults.prepare(context, original);
+    return PreparedRegisteredMemoryCorrections.restore(context, review);
+}
+/** Admit the current post-correction view only after the complete registered
+ * graph has settled. This does not allocate reviewers or resolve findings. */
+export function prepareCompletedMemoryCorrectionsFromStage(context, input) {
+    return PreparedCompletedMemoryCorrectionWave.prepare(context, prepareMemoryRepairRegistrationFromStage(context, input));
+}
+/** Prepare selective current inputs; independent fresh checks and reviewer
+ * registration must still precede any actual Work dispatch. */
+export function prepareCorrectedMemoryReviewFromStage(context, input) {
+    return PreparedCorrectedMemoryReviewInputs.prepare(context, prepareCompletedMemoryCorrectionsFromStage(context, input));
+}
+/** Register only selective independent reviewers. No provider is launched;
+ * missing, changed or lost check/Work receipts refuse instead of reallocating. */
+export function registerCorrectedMemoryReviewFromStage(context, input) {
+    const corrected = prepareCorrectedMemoryReviewFromStage(context, input);
+    const checks = PreparedMemoryCorrectionCheckReceipt.restore(context, corrected);
+    return registerCorrectedMemoryReview(context, corrected, checks);
+}
+/** Independent selective fan-in; this does not accept Stage completion,
+ * authorize wave two or mark old material findings resolved. */
+export function collectCorrectedMemoryReviewFromStage(context, input) {
+    const corrected = prepareCorrectedMemoryReviewFromStage(context, input);
+    const checks = PreparedMemoryCorrectionCheckReceipt.restore(context, corrected);
+    return PreparedCorrectedMemoryReviewAcceptance.prepare(context, PreparedRegisteredCorrectedMemoryReview.restore(context, corrected, checks));
+}
+/** Wave-two intake uses the actual settled first selective review. It does
+ * not reuse initial review findings, allocate a graph or dispatch repairs. */
+export function prepareMemorySecondCorrectionsFromStage(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    return PreparedMemorySecondCorrectionPlan.prepare(context, collectCorrectedMemoryReviewFromStage(context, input), input.bytes);
+}
+export function registerMemorySecondCorrectionsFromStage(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    try {
+        const retained = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId },
+            bundle, expectedBytes: input.bytes });
+        const receipt = retained.receipt();
+        return { wave: 2, plan_sha256: receipt.plan_sha256, work_ids: { ...receipt.work_ids }, replayed: true };
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "memory_retained_second_repairs_invalid" || error.details.reason !== "registration_missing")
+            throw error;
+    }
+    return registerMemorySecondCorrections(context, prepareMemorySecondCorrectionsFromStage(context, input));
+}
+export function prepareMemorySecondRepairSourceFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    if (context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.repair_current_view' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 1", [project.id, input.runId, input.workId])) {
+        const current = PreparedMemoryRepairCurrentView.restore(context, registration, input.workId);
+        return PreparedSecondMemoryRepairSource.prepareCurrent(context, { registration, bundle, workId: input.workId, current });
+    }
+    return PreparedSecondMemoryRepairSource.prepare(context, { registration, bundle, workId: input.workId });
+}
+/** Explained post-peer second input view. Registration preserves this view
+ * only; consuming it as a dependent baseline/start requires separate owners. */
+export function prepareMemorySecondRepairCurrentViewFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    return PreparedMemoryRepairCurrentView.prepare(context, registration, input.workId);
+}
+export function registerMemorySecondRepairCurrentViewFromStage(context, input) {
+    return prepareMemorySecondRepairCurrentViewFromStage(context, input).register(context);
+}
+export function restoreMemorySecondRepairCurrentViewFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    return PreparedMemoryRepairCurrentView.restore(context, registration, input.workId);
+}
+export function prepareMemorySecondRepairCurrentSourceFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    const current = PreparedMemoryRepairCurrentView.restore(context, registration, input.workId);
+    return PreparedSecondMemoryRepairSource.prepareCurrent(context, { registration, bundle, workId: input.workId, current });
+}
+export function registerMemorySecondRepairCurrentBaselineFromStage(context, input) {
+    return PreparedSecondMemoryRepairBaseline.prepare(context, prepareMemorySecondRepairCurrentSourceFromStage(context, input)).register(context);
+}
+export function registerMemorySecondRepairBaselineFromStage(context, input) {
+    return PreparedSecondMemoryRepairBaseline.prepare(context, prepareMemorySecondRepairSourceFromStage(context, input)).register(context);
+}
+function prepareMemorySecondRepairCopyFromStage(context, input) {
+    const baseline = PreparedSecondMemoryRepairBaseline.prepare(context, prepareMemorySecondRepairSourceFromStage(context, input));
+    return PreparedMemoryRepairWriterCopy.prepare(context, baseline);
+}
+export function reserveMemorySecondRepairCopyFromStage(context, input) {
+    return prepareMemorySecondRepairCopyFromStage(context, input).reserve(context);
+}
+export function materializeMemorySecondRepairCopyFromStage(context, input) {
+    return prepareMemorySecondRepairCopyFromStage(context, input).materialize(context);
+}
+export function prepareMemorySecondRepairDispatchFromStage(context, input) {
+    return prepareMemorySecondRepairCopyFromStage(context, input).secondWaveLaunchPacket(context);
+}
+export function restoreMemorySecondRepairBaselineFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    return PreparedRetainedSecondMemoryBaseline.prepare(context, { registration, bundle, workId: input.workId });
+}
+export function prepareMemorySecondRepairLaunchFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    const baseline = PreparedRetainedSecondMemoryBaseline.prepare(context, { registration, bundle, workId: input.workId });
+    return PreparedSecondMemoryRepairLaunch.prepare(context, { registration, baseline, bundle });
+}
+export function restoreStartedMemorySecondRepairLaunchFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    const baseline = PreparedRetainedSecondMemoryBaseline.prepare(context, { registration, bundle, workId: input.workId });
+    return PreparedSecondMemoryRepairLaunch.restoreForStartedWork(context, { registration, baseline, bundle, workSessionId: input.workSessionId });
+}
+export function prepareMemorySecondRepairPublicationFromStage(context, input) {
+    const owner = restoreStartedMemorySecondRepairLaunchFromStage(context, input);
+    return PreparedRetainedMemoryRepairPublication.prepareSecond(context, owner);
+}
+export function reserveMemorySecondRepairPublicationFromStage(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    return restoreStartedMemorySecondRepairLaunchFromStage(context, input).reservePublication(context, input.bytes);
+}
+export function applyMemorySecondRepairPublicationFromStage(context, input) {
+    return prepareMemorySecondRepairPublicationFromStage(context, input).applyNextAction(context);
+}
+export function finishMemorySecondRepairPublicationFromStage(context, input) {
+    const publication = prepareMemorySecondRepairPublicationFromStage(context, input);
+    return finishPublishedMemoryRepairWork(context, PreparedPublishedMemoryRepairWorkResult.prepare(context, publication));
+}
+/** Historical settlement proof, not a new writer baseline or provider start.
+ * The whole independent start/publication/SDK settlement chain is required. */
+export function prepareSettledMemorySecondRepairFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    return PreparedSettledMemoryRepair.prepare(context, registration, input.workId);
+}
+/** Complete second graph/current document proof. This is not independent
+ * semantic re-review acceptance and does not close the review Stage. */
+export function prepareCompletedMemorySecondCorrectionsFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const registration = PreparedRetainedSecondMemoryRepairs.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+    return PreparedCompletedMemoryCorrectionWave.prepare(context, registration);
+}
+export function prepareSecondCorrectedMemoryReviewFromStage(context, input) {
+    return PreparedSecondCorrectedMemoryReviewInputs.prepare(context, prepareCompletedMemorySecondCorrectionsFromStage(context, input));
+}
+/** Allocate wave-two independent reviewers only after its own committed checks.
+ * This does not launch Sessions or authorize a third correction wave. */
+export function registerSecondCorrectedMemoryReviewFromStage(context, input) {
+    const corrected = prepareSecondCorrectedMemoryReviewFromStage(context, input);
+    return registerCorrectedMemoryReview(context, corrected, PreparedMemoryCorrectionCheckReceipt.restore(context, corrected));
+}
+export function collectSecondCorrectedMemoryReviewFromStage(context, input) {
+    const corrected = prepareSecondCorrectedMemoryReviewFromStage(context, input);
+    return PreparedSecondMemoryReviewAcceptance.prepare(context, PreparedRegisteredCorrectedMemoryReview.restore(context, corrected, PreparedMemoryCorrectionCheckReceipt.restore(context, corrected)));
+}
+/** Finite owning-policy checks over the settled corrected view. Callers
+ * cannot choose commands, policy hashes or a substitute evidence context.
+ * This does not allocate reviewers or accept semantic correction quality. */
+export function prepareMemoryCorrectionChecksFromStage(context, input) {
+    const corrected = prepareCorrectedMemoryReviewFromStage(context, input), bundle = corrected.bundle(), scope = corrected.value().scope;
+    return PreparedMemoryVerificationChecks.prepare(context, { projectId: scope.project_id, runId: scope.run_id,
+        execution: bundle.execution, flow: bundle.descriptor, corrected });
+}
+export function runMemoryCorrectionChecksFromStage(context, input) {
+    return runCorrectionChecks(context, prepareCorrectedMemoryReviewFromStage(context, input));
+}
+export function prepareMemorySecondCorrectionChecksFromStage(context, input) {
+    const corrected = prepareSecondCorrectedMemoryReviewFromStage(context, input), bundle = corrected.bundle(), scope = corrected.value().scope;
+    return PreparedMemoryVerificationChecks.prepare(context, { projectId: scope.project_id, runId: scope.run_id,
+        execution: bundle.execution, flow: bundle.descriptor, corrected });
+}
+export function runMemorySecondCorrectionChecksFromStage(context, input) {
+    return runCorrectionChecks(context, prepareSecondCorrectedMemoryReviewFromStage(context, input));
+}
+function runCorrectionChecks(context, corrected) {
+    try {
+        const accepted = PreparedMemoryCorrectionCheckReceipt.restore(context, corrected);
+        accepted.assertRegisteredCustody(context);
+        return Promise.resolve({ receipt: accepted.value(), receipt_sha256: accepted.sha256, replay: true });
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "memory_correction_checks_invalid" || error.details.reason !== "registered_check_receipt_required")
+            throw error;
+    }
+    const bundle = corrected.bundle(), scope = corrected.value().scope;
+    const policy = PreparedMemoryVerificationChecks.prepare(context, { projectId: scope.project_id, runId: scope.run_id,
+        execution: bundle.execution, flow: bundle.descriptor, corrected });
+    // A disconnect after the last physical check but before the independent
+    // receipt must not replay the commands merely to reconstruct acceptance.
+    try {
+        const completed = PreparedMemoryCorrectionCheckReceipt.prepare(context, corrected, policy);
+        return Promise.resolve(completed.register(context));
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "check_evidence_stale")
+            throw error;
+    }
+    return policy.execute(context).then(() => PreparedMemoryCorrectionCheckReceipt.prepare(context, corrected, policy).register(context));
+}
+/** Reserve only after the independently committed baseline exists. Neither
+ * this receipt nor its replay admits filesystem contents or provider launch.
+ */
+export function reserveMemoryRepairWriterCopyFromStage(context, input) {
+    const baseline = prepareMemoryRepairBaselineFromStage(context, input);
+    return PreparedMemoryRepairWriterCopy.prepare(context, baseline).reserve(context);
+}
+export function materializeMemoryRepairWriterCopyFromStage(context, input) {
+    const baseline = prepareMemoryRepairBaselineFromStage(context, input);
+    return PreparedMemoryRepairWriterCopy.prepare(context, baseline).materialize(context);
+}
+export function prepareMemoryRepairDispatchFromStage(context, input) {
+    const baseline = prepareMemoryRepairBaselineFromStage(context, input);
+    return PreparedMemoryRepairWriterCopy.prepare(context, baseline).launchPacket(context);
+}
+/** Preparation only; actual Work start must separately prove the Hook
+ * identity, physical Session and this custody again in its claim writer.
+ */
+export function prepareExternalMemoryRepairCopyFromStage(context, input) {
+    const registration = prepareMemoryRepairRegistrationFromStage(context, input);
+    const baseline = PreparedMemoryRepairWorkBaseline.restoreForLaunch(context, registration, input.workId);
+    return PreparedBoundMemoryRepairCopy.prepare(context, baseline, input.workspaceRoot);
+}
+/** Select settled dependency/current documents from this exact registered
+ * stage. Preparation alone neither registers a writer baseline nor launches
+ * a provider; those operations must consume this owner explicitly.
+ */
+export function prepareMemoryRepairCurrentViewFromStage(context, input) {
+    const registration = prepareMemoryRepairRegistrationFromStage(context, input);
+    if (registration.review().original().bundle().execution.snapshot().scope.workspace !== input.workspaceRoot)
+        refuse("current_view_workspace_mismatch");
+    return PreparedMemoryRepairCurrentView.prepare(context, registration, input.workId);
+}
+export function restoreMemoryRepairCurrentViewFromStage(context, input) {
+    const registration = prepareMemoryRepairRegistrationFromStage(context, input);
+    if (registration.review().original().bundle().execution.snapshot().scope.workspace !== input.workspaceRoot)
+        refuse("current_view_workspace_mismatch");
+    return PreparedMemoryRepairCurrentView.restore(context, registration, input.workId);
+}
+export function registerMemoryRepairCurrentViewFromStage(context, input) {
+    const registration = prepareMemoryRepairRegistrationFromStage(context, input);
+    if (input.workspaceRoot !== undefined && registration.review().original().bundle().execution.snapshot().scope.workspace !== input.workspaceRoot)
+        refuse("current_view_workspace_mismatch");
+    let prepared;
+    try {
+        prepared = PreparedMemoryRepairCurrentView.restore(context, registration, input.workId);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "memory_repair_current_view_invalid" || error.details.reason !== "registered_view_required")
+            throw error;
+        prepared = PreparedMemoryRepairCurrentView.prepare(context, registration, input.workId);
+    }
+    return prepared.register(context);
+}
+/** Restore the same registered physical start; never launch or claim another
+ * Session and never replace retained input bytes with today's workspace.
+ */
+export function restoreStartedMemoryRepairCopyFromStage(context, input) {
+    const registration = prepareMemoryRepairRegistrationFromStage(context, input);
+    const baseline = PreparedMemoryRepairWorkBaseline.restoreForStartedWork(context, registration, input.workId, input.workSessionId);
+    return PreparedBoundMemoryRepairCopy.restoreForStartedWork(context, baseline, input.workspaceRoot, input.workSessionId);
+}
+function restoreRepairOutputOwners(context, input) {
+    const registration = prepareMemoryRepairRegistrationFromStage(context, input);
+    const baseline = PreparedMemoryRepairWorkBaseline.restoreForOutput(context, registration, input.workId, input.workSessionId);
+    const copy = PreparedBoundMemoryRepairCopy.restoreForOutput(context, baseline, input.workspaceRoot, input.workSessionId);
+    return { registration, baseline, copy };
+}
+/** Running writer custody remains original; the shared source view is selected
+ * independently from settled peer histories. No publication intent is made. */
+export function prepareMemoryRepairPublicationSourceFromStage(context, input) {
+    const owners = restoreRepairOutputOwners(context, input);
+    return PreparedMemoryRepairPublicationSource.prepare(context, owners.registration, owners.baseline, owners.copy, input.workSessionId);
+}
+export function restoreMemoryRepairPublicationSourceFromStage(context, input) {
+    const owners = restoreRepairOutputOwners(context, input);
+    return PreparedMemoryRepairPublicationSource.restore(context, owners.registration, owners.baseline, owners.copy, input.workSessionId);
+}
+export function registerMemoryRepairPublicationSourceFromStage(context, input) {
+    const owners = restoreRepairOutputOwners(context, input);
+    let source;
+    try {
+        source = PreparedMemoryRepairPublicationSource.restore(context, owners.registration, owners.baseline, owners.copy, input.workSessionId);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "memory_repair_publication_source_invalid" || error.details.reason !== "registered_source_required")
+            throw error;
+        source = PreparedMemoryRepairPublicationSource.prepare(context, owners.registration, owners.baseline, owners.copy, input.workSessionId);
+    }
+    return source.register(context);
+}
+export function prepareMemoryRepairPrivateOutputFromStage(context, input) {
+    const copy = restoreStartedMemoryRepairCopyFromStage(context, input);
+    return copy.prepareOutput(context, input.bytes, input.workSessionId);
+}
+/** Explicit source registration is a prior operation, never a hidden write
+ * during output preparation. Original private evidence remains frozen. */
+export function prepareMemoryRepairPrivateOutputAgainstSourceFromStage(context, input) {
+    const owners = restoreRepairOutputOwners(context, input);
+    const source = PreparedMemoryRepairPublicationSource.restore(context, owners.registration, owners.baseline, owners.copy, input.workSessionId);
+    return owners.copy.prepareOutputAgainstSource(context, input.bytes, input.workSessionId, source);
+}
+export function reserveMemoryRepairPublicationAgainstSourceFromStage(context, input) {
+    return prepareMemoryRepairPrivateOutputAgainstSourceFromStage(context, input).reservePublication(context);
+}
+export function reserveMemoryRepairPublicationFromStage(context, input) {
+    return prepareMemoryRepairPrivateOutputFromStage(context, input).reservePublication(context);
+}
+export function restoreMemoryRepairPublicationFromStage(context, input) {
+    const registration = prepareMemoryRepairRegistrationFromStage(context, input);
+    const baseline = PreparedMemoryRepairWorkBaseline.restoreForPublication(context, registration, input.workId, input.workSessionId);
+    const copy = PreparedBoundMemoryRepairCopy.restoreForPublication(context, baseline, input.workspaceRoot, input.workSessionId);
+    const intent = baseline.registeredPublicationIntent(context, input.workSessionId);
+    const source = intent.schema_id === "dd-flow/memory-repair-publication-intent@2"
+        ? PreparedMemoryRepairPublicationSource.restore(context, registration, baseline, copy, input.workSessionId) : null;
+    return PreparedRetainedMemoryRepairPublication.prepare(context, baseline, copy, input.workSessionId, source);
+}
+export function applyMemoryRepairPublicationFromStage(context, input) {
+    return restoreMemoryRepairPublicationFromStage(context, input).applyNextAction(context);
+}
+export function finishMemoryRepairPublicationFromStage(context, input) {
+    const publication = restoreMemoryRepairPublicationFromStage(context, input);
+    return finishPublishedMemoryRepairWork(context, PreparedPublishedMemoryRepairWorkResult.prepare(context, publication));
+}