@dailephd/my-dev-kit-lab 0.6.1 → 0.6.3

package/dist/src/experiments/plugins/incrementalChangeStaleness/lifecycleV2.js

@@ -0,0 +1,298 @@
+import path from "node:path";
+import { createDisposableTreatmentTarget, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS, INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS } from "./disposableTarget.js";
+import { cloneIncrementalChangeStalenessIndexDirectory } from "./indexClone.js";
+import { defaultIncrementalChangeStalenessLifecycleDeps, fail, incrementalChangeStalenessIndexDir, incrementalChangeStalenessTargetsRoot, LifecycleFailure, prepareTreatmentIndexEvidence } from "./lifecycle.js";
+import { evaluateBaselineStaleFreshness, evaluateChangedPathSymmetry, evaluateRefreshedFreshness, evaluateToolIdentity, normalizeRelativePath, normalizeRootForComparison } from "./lifecyclePolicy.js";
+import { evaluateBaselineBootstrapEvidence, evaluatePartialRefreshRealization, evaluateV2InvocationCounts } from "./lifecyclePolicyV2.js";
+import { compareIncrementalChangeStalenessSourceStates } from "./sourceState.js";
+import { INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_V2_SCHEMA_VERSION } from "./treatmentSessionV2.js";
+const PARTIAL_REFRESH_SCOPES = {
+    "changed-files-refresh": "changed-files",
+    "affected-neighborhood-refresh": "affected-neighborhood"
+};
+/** Every baseline is bootstrapped incrementally so upstream writes the cache metadata a later partial refresh needs. */
+const BOOTSTRAP_MODE = { kind: "incremental", refreshScope: "changed-files" };
+const V2_TREATMENT_IDS = INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_IDS;
+function withRefreshEvidence(evidence, buildMode, incrementalRefresh) {
+    return Object.freeze({ ...evidence, buildMode, incrementalRefresh });
+}
+/**
+ * v0.6.3 internal four-treatment lifecycle for ONE frozen scenario (runtime only; not yet wired into the
+ * public plugin, execution artifact, comparison, or reports):
+ *
+ *  1. four independent disposable copies (stale-index, changed-files-refresh, affected-neighborhood-refresh,
+ *     full-refresh), all derived from the same immutable canonical benchmark;
+ *  2. pre-mutation controlled source-state equivalence of every treatment against the stale-index reference;
+ *  3. all four baselines bootstrapped with `--incremental --refresh-scope changed-files` into brand-new
+ *     index directories (expected bootstrap evidence: full fallback, `cache-missing`);
+ *  4. each partial treatment's untouched baseline is cloned byte-for-byte into its own refreshed directory;
+ *  5. BARRIER: only after every baseline + clone is ready is the same frozen mutation applied to all four;
+ *  6. post-mutation source-state equivalence and symmetric complete-stale baseline freshness;
+ *  7. stale-index keeps its baseline; each partial treatment refreshes its clone in place and full-refresh
+ *     builds a new full index; every refreshed index must be complete `fresh`.
+ *
+ * Seven index invocations and seven freshness assessments per scenario. Performs no retrieval,
+ * affected-neighborhood task traversal, or comparison classification. Sequential by design; deletes nothing.
+ */
+export async function prepareIncrementalChangeStalenessScenarioLifecycleV2(options) {
+    const cloneIndexDirectory = options.deps?.cloneIndexDirectory ?? cloneIncrementalChangeStalenessIndexDirectory;
+    const deps = { ...defaultIncrementalChangeStalenessLifecycleDeps, ...options.deps };
+    const { repoRoot, scenario, baseCase, kitCommand } = options;
+    const runOwnedRoot = path.resolve(options.runOwnedRoot);
+    const events = [];
+    const indexInvocationCounts = Object.fromEntries(V2_TREATMENT_IDS.map((id) => [id, 0]));
+    const freshnessAssessmentCounts = Object.fromEntries(V2_TREATMENT_IDS.map((id) => [id, 0]));
+    const sourceRoots = baseCase.sourceRoots;
+    const controlledChangedPaths = scenario.mutation.files.map((file) => normalizeRelativePath(file.path)).sort();
+    async function prepareIndex(target, role, indexDir, mode, existingIndexDir = false) {
+        const treatmentId = target.treatmentId;
+        indexInvocationCounts[treatmentId] += 1;
+        const { evidence, build } = await prepareTreatmentIndexEvidence({
+            deps,
+            runOwnedRoot,
+            scenarioId: scenario.id,
+            kitCommand,
+            sourceRoots,
+            target,
+            role,
+            indexDir,
+            mode,
+            existingIndexDir,
+            onIndexPrepared: () => events.push(`${treatmentId}:${role}-index-built`, `${treatmentId}:${role}-snapshot-captured`, `${treatmentId}:${role}-graph-loaded`)
+        });
+        events.push(`${treatmentId}:${role}-identity-verified`);
+        return { evidence, build };
+    }
+    async function captureState(target) {
+        return deps.captureSourceState(target.targetRoot, sourceRoots, target.treatmentId, baseCase.benchmarkProjectId);
+    }
+    async function mutate(target) {
+        const receipt = await deps.executeMutation(scenario, target, sourceRoots, repoRoot);
+        if (receipt.status !== "applied") {
+            fail({ code: "mutation-failed", message: `${target.treatmentId} mutation was rejected: ${receipt.errors.join(" ")}`, treatmentId: target.treatmentId });
+        }
+        events.push(`${target.treatmentId}:mutation-applied`);
+        return receipt;
+    }
+    async function assess(index, target) {
+        freshnessAssessmentCounts[target.treatmentId] += 1;
+        return deps.assessIndexFreshness({ snapshot: index.snapshot, targetRoot: target.targetRoot, sourceRoots });
+    }
+    function compareAgainstReference(reference, states, code, phase) {
+        const comparisons = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            if (treatmentId === "stale-index")
+                continue;
+            const comparison = compareIncrementalChangeStalenessSourceStates(reference, states[treatmentId]);
+            comparisons[treatmentId] = comparison;
+            if (comparison.result !== "equivalent") {
+                fail({
+                    code,
+                    message: `${treatmentId} is not ${phase} equivalent to the stale-index reference (${comparison.result}): ${comparison.reasons.join("; ")}`,
+                    treatmentId
+                });
+            }
+        }
+        return comparisons;
+    }
+    try {
+        const baselineDirs = {};
+        const refreshedDirs = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            baselineDirs[treatmentId] = incrementalChangeStalenessIndexDir(runOwnedRoot, scenario.id, treatmentId, "baseline");
+            refreshedDirs[treatmentId] = incrementalChangeStalenessIndexDir(runOwnedRoot, scenario.id, treatmentId, "refreshed");
+        }
+        const allDirs = [...Object.values(baselineDirs), ...Object.values(refreshedDirs)].map(normalizeRootForComparison);
+        if (new Set(allDirs).size !== allDirs.length) {
+            fail({ code: "index-directory-collision", message: "Treatment/phase index directories are not distinct.", treatmentId: null });
+        }
+        // 1. Four independent disposable copies through the established owner, in fixed order.
+        const targets = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            try {
+                targets[treatmentId] = await createDisposableTreatmentTarget({
+                    repoRoot,
+                    runRoot: incrementalChangeStalenessTargetsRoot(runOwnedRoot),
+                    scenarioId: scenario.id,
+                    treatmentId,
+                    benchmarkProjectId: baseCase.benchmarkProjectId,
+                    canonicalProjectRootRelative: baseCase.canonicalProjectRootRelative
+                });
+            }
+            catch (error) {
+                fail({ code: "treatment-target-creation-failed", message: `${treatmentId}: ${error.message}`, treatmentId });
+            }
+        }
+        const targetRootKeys = V2_TREATMENT_IDS.map((id) => normalizeRootForComparison(targets[id].targetRoot));
+        if (new Set(targetRootKeys).size !== targetRootKeys.length) {
+            fail({ code: "treatment-target-creation-failed", message: "Treatment target roots are not distinct.", treatmentId: null });
+        }
+        events.push("treatment-targets-created");
+        // 2. Pre-mutation equivalence gates all indexing and mutation; stale-index is only the comparison reference.
+        const preStates = {};
+        for (const treatmentId of V2_TREATMENT_IDS)
+            preStates[treatmentId] = await captureState(targets[treatmentId]);
+        events.push("pre-mutation-source-state-captured");
+        const preMutationEquivalence = compareAgainstReference(preStates["stale-index"], preStates, "pre-mutation-not-equivalent", "pre-mutation");
+        events.push("pre-mutation-equivalence-proven");
+        // 3. Baselines: every treatment bootstraps incrementally into a brand-new index directory.
+        const baselines = {};
+        const bootstraps = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            const { evidence, build } = await prepareIndex(targets[treatmentId], "baseline", baselineDirs[treatmentId], BOOTSTRAP_MODE);
+            fail(evaluateBaselineBootstrapEvidence(build, treatmentId));
+            bootstraps[treatmentId] = build.incrementalRefresh;
+            baselines[treatmentId] = withRefreshEvidence(evidence, build.mode, build.incrementalRefresh);
+            events.push(`${treatmentId}:baseline-bootstrap-verified`);
+        }
+        const baselineTools = evaluateToolIdentity(V2_TREATMENT_IDS.map((id) => baselines[id]));
+        fail(baselineTools.failure);
+        events.push("baseline-tool-identity-verified");
+        // 4. Preserve each partial treatment's immutable baseline; the refresh runs in place against a byte-for-byte clone.
+        for (const treatmentId of ["changed-files-refresh", "affected-neighborhood-refresh"]) {
+            try {
+                await cloneIndexDirectory(runOwnedRoot, baselineDirs[treatmentId], refreshedDirs[treatmentId]);
+            }
+            catch (error) {
+                fail({ code: "index-clone-failed", message: `${treatmentId} baseline index clone failed: ${error.message}`, treatmentId });
+            }
+            events.push(`${treatmentId}:baseline-index-cloned`);
+        }
+        // 5. Barrier: all four baselines are index + snapshot + graph READY and clones exist. Only now may mutation begin.
+        events.push("baseline-barrier-ready");
+        const receipts = {};
+        for (const treatmentId of V2_TREATMENT_IDS)
+            receipts[treatmentId] = await mutate(targets[treatmentId]);
+        // 6. Post-mutation equivalence.
+        const postStates = {};
+        for (const treatmentId of V2_TREATMENT_IDS)
+            postStates[treatmentId] = await captureState(targets[treatmentId]);
+        events.push("post-mutation-source-state-captured");
+        const postMutationEquivalence = compareAgainstReference(postStates["stale-index"], postStates, "post-mutation-not-equivalent", "post-mutation");
+        events.push("post-mutation-equivalence-proven");
+        // 7. Baseline (change-authority) freshness against each mutated target, symmetric with the reference.
+        const baselineFreshness = {};
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            baselineFreshness[treatmentId] = await assess(baselines[treatmentId], targets[treatmentId]);
+            fail(evaluateBaselineStaleFreshness(baselineFreshness[treatmentId], controlledChangedPaths, treatmentId));
+            events.push(`${treatmentId}:baseline-freshness-stale`);
+        }
+        for (const treatmentId of V2_TREATMENT_IDS) {
+            if (treatmentId === "stale-index")
+                continue;
+            fail(evaluateChangedPathSymmetry(baselineFreshness["stale-index"], baselineFreshness[treatmentId], { reference: "stale-index", other: treatmentId }));
+        }
+        events.push("baseline-changed-paths-symmetric");
+        // 8. stale-index: no rebuild; baseline stays the active retrieval index.
+        events.push("stale-index:baseline-retained-as-active");
+        // 9. Partial treatments: refresh the cloned working index in place through the shared build owner.
+        const refreshed = {};
+        const refreshedFreshness = {};
+        const realizations = {};
+        for (const treatmentId of ["changed-files-refresh", "affected-neighborhood-refresh"]) {
+            const scope = PARTIAL_REFRESH_SCOPES[treatmentId];
+            const { evidence, build } = await prepareIndex(targets[treatmentId], "refreshed", refreshedDirs[treatmentId], { kind: "incremental", refreshScope: scope }, true);
+            const realization = evaluatePartialRefreshRealization(build, scope, treatmentId);
+            fail(realization.failure);
+            realizations[treatmentId] = realization.realization;
+            events.push(`${treatmentId}:refresh-realization-${realization.realization === "APPLIED_PARTIAL" ? "applied-partial" : "fallback-full"}`);
+            refreshed[treatmentId] = withRefreshEvidence(evidence, build.mode, build.incrementalRefresh);
+            refreshedFreshness[treatmentId] = await assess(evidence, targets[treatmentId]);
+            fail(evaluateRefreshedFreshness(refreshedFreshness[treatmentId], treatmentId));
+            events.push(`${treatmentId}:refreshed-freshness-fresh`);
+        }
+        // 10. full-refresh: a NEW complete post-mutation index in a separate directory (baseline is not cloned).
+        {
+            const { evidence, build } = await prepareIndex(targets["full-refresh"], "refreshed", refreshedDirs["full-refresh"], undefined);
+            refreshed["full-refresh"] = withRefreshEvidence(evidence, build.mode, build.incrementalRefresh);
+            refreshedFreshness["full-refresh"] = await assess(evidence, targets["full-refresh"]);
+            fail(evaluateRefreshedFreshness(refreshedFreshness["full-refresh"], "full-refresh"));
+            events.push("full-refresh:refreshed-freshness-fresh");
+        }
+        // 11. Scenario-level proofs.
+        const allTools = evaluateToolIdentity([...V2_TREATMENT_IDS.map((id) => baselines[id]), ...V2_TREATMENT_IDS.flatMap((id) => (refreshed[id] ? [refreshed[id]] : []))]);
+        fail(allTools.failure);
+        events.push("tool-identity-consistent");
+        fail(evaluateV2InvocationCounts(indexInvocationCounts, freshnessAssessmentCounts));
+        events.push("invocation-counts-verified");
+        events.push("lifecycle-ready");
+        const common = (treatmentId) => ({
+            treatmentIntent: INCREMENTAL_CHANGE_STALENESS_V2_TREATMENT_INTENTS[treatmentId],
+            target: targets[treatmentId],
+            preMutationSourceState: preStates[treatmentId],
+            postMutationSourceState: postStates[treatmentId],
+            mutationReceipt: receipts[treatmentId],
+            changeAuthority: Object.freeze({
+                baselineIndex: baselines[treatmentId],
+                baselineBootstrap: bootstraps[treatmentId],
+                postMutationBaselineFreshness: baselineFreshness[treatmentId]
+            }),
+            indexInvocationCount: indexInvocationCounts[treatmentId],
+            freshnessAssessmentCount: freshnessAssessmentCounts[treatmentId],
+            lifecycleStatus: "ready",
+            warnings: Object.freeze([])
+        });
+        const partialSession = (treatmentId) => Object.freeze({
+            ...common(treatmentId),
+            treatmentId,
+            activeRetrieval: Object.freeze({ role: "refreshed", index: refreshed[treatmentId] }),
+            postMutationIndexBuilt: true,
+            refreshedIndex: refreshed[treatmentId],
+            refreshedFreshness: refreshedFreshness[treatmentId],
+            refreshRealization: realizations[treatmentId]
+        });
+        const staleSession = Object.freeze({
+            ...common("stale-index"),
+            treatmentId: "stale-index",
+            activeRetrieval: Object.freeze({ role: "baseline", index: baselines["stale-index"] }),
+            postMutationIndexBuilt: false,
+            refreshedIndex: null,
+            refreshedFreshness: null,
+            refreshRealization: null
+        });
+        const fullSession = Object.freeze({
+            ...common("full-refresh"),
+            treatmentId: "full-refresh",
+            activeRetrieval: Object.freeze({ role: "refreshed", index: refreshed["full-refresh"] }),
+            postMutationIndexBuilt: true,
+            refreshedIndex: refreshed["full-refresh"],
+            refreshedFreshness: refreshedFreshness["full-refresh"],
+            refreshRealization: null
+        });
+        const session = Object.freeze({
+            schemaVersion: INCREMENTAL_CHANGE_STALENESS_LIFECYCLE_SESSION_V2_SCHEMA_VERSION,
+            scenarioId: scenario.id,
+            scenario,
+            baseCase,
+            runOwnedRoot,
+            kitCommand,
+            toolIdentity: allTools.tool,
+            controlledChangedPaths: Object.freeze(controlledChangedPaths),
+            preMutationEquivalence: Object.freeze(preMutationEquivalence),
+            postMutationEquivalence: Object.freeze(postMutationEquivalence),
+            treatments: Object.freeze({
+                "stale-index": staleSession,
+                "changed-files-refresh": partialSession("changed-files-refresh"),
+                "affected-neighborhood-refresh": partialSession("affected-neighborhood-refresh"),
+                "full-refresh": fullSession
+            }),
+            totalIndexInvocationCount: V2_TREATMENT_IDS.reduce((sum, id) => sum + indexInvocationCounts[id], 0),
+            totalFreshnessAssessmentCount: V2_TREATMENT_IDS.reduce((sum, id) => sum + freshnessAssessmentCounts[id], 0),
+            lifecycleEvents: Object.freeze([...events]),
+            status: "ready"
+        });
+        return { status: "ready", session };
+    }
+    catch (error) {
+        const failure = error instanceof LifecycleFailure
+            ? error.failure
+            : { code: "lifecycle-error", message: `Lifecycle failed unexpectedly: ${error instanceof Error ? error.message : String(error)}`, treatmentId: null };
+        return {
+            status: "failed",
+            scenarioId: scenario.id,
+            failure,
+            lifecycleEvents: Object.freeze([...events]),
+            indexInvocationCounts: Object.freeze({ ...indexInvocationCounts })
+        };
+    }
+}

package/dist/src/experiments/plugins/incrementalChangeStaleness/mutationExecution.js

@@ -0,0 +1,144 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinDisposableTarget } from "./disposableTarget.js";
+import { applyMutationOperations, isPathCoveredBySourceRoots, sha256Hex } from "./scenarioMutation.js";
+export const INCREMENTAL_CHANGE_STALENESS_MUTATION_RECEIPT_SCHEMA_VERSION = "1.0.0";
+function canonicalBenchmarkProjectsRoot(repoRoot) {
+    return path.resolve(repoRoot, "benchmarks/projects");
+}
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+/**
+ * Executes one scenario's already-validated mutation plan against ONE
+ * disposable treatment copy. Re-validates every guard at execution time
+ * (path containment/coverage, pre-hash, ordered exact-preimage replacement,
+ * post-hash) rather than trusting that Batch 1 catalog validation still
+ * holds, because a disposable copy can drift between creation and mutation.
+ *
+ * Two-phase: every file is fully validated and its post-mutation bytes
+ * computed in memory BEFORE any filesystem write begins. Writes only start
+ * once the complete plan is internally valid. If a later write/verification
+ * fails, files already written and verified remain recorded as such; the
+ * overall receipt status is "rejected" and no file is misreported as
+ * successfully mutated.
+ */
+export async function executeIncrementalChangeStalenessMutation(scenario, target, caseSourceRoots, repoRoot) {
+    const base = () => ({
+        schemaVersion: INCREMENTAL_CHANGE_STALENESS_MUTATION_RECEIPT_SCHEMA_VERSION,
+        scenarioId: scenario.id,
+        treatmentId: target.treatmentId,
+        benchmarkProjectId: target.benchmarkProjectId
+    });
+    const canonicalRoot = canonicalBenchmarkProjectsRoot(repoRoot);
+    if (isWithin(canonicalRoot, path.resolve(target.targetRoot)) || path.resolve(target.targetRoot) === canonicalRoot) {
+        return {
+            ...base(),
+            status: "rejected",
+            files: [],
+            errors: [`Refusing to mutate a canonical benchmark target directly: ${target.targetRoot}.`]
+        };
+    }
+    const fileReceipts = [];
+    const plannedWrites = [];
+    const errors = [];
+    // Phase 1: validate every file and compute post-mutation bytes in memory. No writes yet.
+    for (const fileDeclaration of scenario.mutation.files) {
+        const label = `${scenario.id}/${target.treatmentId}: ${fileDeclaration.path}`;
+        const receipt = {
+            path: fileDeclaration.path,
+            expectedPreSha256: fileDeclaration.expectedPreSha256,
+            observedPreSha256: null,
+            operationCount: fileDeclaration.operations.length,
+            expectedPostSha256: fileDeclaration.expectedPostSha256,
+            observedPostSha256: null,
+            written: false
+        };
+        if (!isPathCoveredBySourceRoots(fileDeclaration.path, caseSourceRoots)) {
+            receipt.error = `${label}: path is not covered by the referenced case's indexed source roots.`;
+            errors.push(receipt.error);
+            fileReceipts.push(receipt);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        let absolutePath;
+        try {
+            absolutePath = await resolveWithinDisposableTarget(target, fileDeclaration.path);
+        }
+        catch (error) {
+            receipt.error = `${label}: ${error.message}`;
+            errors.push(receipt.error);
+            fileReceipts.push(receipt);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        let buffer;
+        try {
+            buffer = await readFile(absolutePath);
+        }
+        catch (error) {
+            receipt.error = `${label}: unable to read disposable file: ${error.message}`;
+            errors.push(receipt.error);
+            fileReceipts.push(receipt);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        const observedPreSha256 = sha256Hex(buffer);
+        receipt.observedPreSha256 = observedPreSha256;
+        if (observedPreSha256 !== fileDeclaration.expectedPreSha256) {
+            receipt.error = `${label}: expectedPreSha256 ${fileDeclaration.expectedPreSha256} does not match observed ${observedPreSha256}.`;
+            errors.push(receipt.error);
+            fileReceipts.push(receipt);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        let mutatedText;
+        try {
+            mutatedText = applyMutationOperations(buffer.toString("utf8"), fileDeclaration.operations);
+        }
+        catch (error) {
+            receipt.error = `${label}: ${error.message}`;
+            errors.push(receipt.error);
+            fileReceipts.push(receipt);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        const mutatedBuffer = Buffer.from(mutatedText, "utf8");
+        const computedPostSha256 = sha256Hex(mutatedBuffer);
+        if (computedPostSha256 !== fileDeclaration.expectedPostSha256) {
+            receipt.error = `${label}: expectedPostSha256 ${fileDeclaration.expectedPostSha256} does not match computed in-memory post-mutation SHA-256 ${computedPostSha256}.`;
+            errors.push(receipt.error);
+            fileReceipts.push(receipt);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        fileReceipts.push(receipt);
+        plannedWrites.push({ fileDeclaration, absolutePath, mutatedBuffer });
+    }
+    // Phase 2: every file validated. Write, then re-read/re-hash to verify the actual on-disk result.
+    for (const [index, planned] of plannedWrites.entries()) {
+        const receipt = fileReceipts[index];
+        const label = `${scenario.id}/${target.treatmentId}: ${planned.fileDeclaration.path}`;
+        try {
+            await writeFile(planned.absolutePath, planned.mutatedBuffer);
+        }
+        catch (error) {
+            receipt.error = `${label}: write failed: ${error.message}`;
+            errors.push(receipt.error);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        let rereadBuffer;
+        try {
+            rereadBuffer = await readFile(planned.absolutePath);
+        }
+        catch (error) {
+            receipt.error = `${label}: post-write re-read failed: ${error.message}`;
+            errors.push(receipt.error);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        const observedPostSha256 = sha256Hex(rereadBuffer);
+        receipt.observedPostSha256 = observedPostSha256;
+        if (observedPostSha256 !== planned.fileDeclaration.expectedPostSha256) {
+            receipt.error = `${label}: post-write SHA-256 ${observedPostSha256} does not match expected ${planned.fileDeclaration.expectedPostSha256}.`;
+            errors.push(receipt.error);
+            return { ...base(), status: "rejected", files: fileReceipts, errors };
+        }
+        receipt.written = true;
+    }
+    return { ...base(), status: "applied", files: fileReceipts, errors: [] };
+}