codex-workflow-v2 2.0.0-alpha.4 → 2.0.0-alpha.7

package/dist/src/alpha6/milestone.js

@@ -0,0 +1,1103 @@
+import { existsSync, lstatSync, readFileSync, realpathSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { WorkflowError } from '../errors.js';
+import { createEntityId } from '../ulid.js';
+import { createJournalSnapshotFromContent, captureJournalTargetSnapshot, listMilestoneTransactionJournals, readJournalSnapshotContent, removeMilestoneTransactionJournal, resolveMilestoneTransactionTargetPath, updateMilestoneTransactionJournalPhase, writeMilestoneTransactionJournal, } from './journal.js';
+import { assertHash64, assertNoSymlinkPathComponents, canonicalJsonStringify, computeSidecarEventHash, prepareSidecarAppend, sha256Hex, } from './store-sidecars.js';
+const SCOPE_CHANGE_SIDECAR = 'scope-change-events.jsonl';
+const MILESTONE_TARGETS = ['state.json', 'plan.json', SCOPE_CHANGE_SIDECAR];
+const SCOPE_CHANGE_ALLOWED_STATUSES = new Set([
+    'planning',
+    'awaiting_execution_authorization',
+    'active',
+    'blocked',
+]);
+export function normalizeMilestonePlan(plan) {
+    return {
+        outcome: plan.outcome.trim(),
+        successSignal: plan.successSignal.trim(),
+        acceptance: [...plan.acceptance],
+        memberships: plan.memberships.map((membership) => ({
+            ...membership,
+            reason: membership.reason.trim(),
+        })),
+        checks: [...plan.checks],
+        taskIds: plan.memberships.map((membership) => membership.taskId),
+    };
+}
+export function readMilestoneWithIntegrity(store, projectId, milestoneId, readTask, listTasks) {
+    recoverMilestoneScopeChangeTransactions(store, projectId, milestoneId, readTask);
+    const milestone = store.readMilestone(projectId, milestoneId);
+    assertMilestonePlanAgreement(store, milestone);
+    assertMilestoneMembershipIntegrity(milestone, readTask, {}, listTasks);
+    return milestone;
+}
+export function readMilestoneForScopeChange(store, projectId, milestoneId, readTask, listTasks) {
+    recoverMilestoneScopeChangeTransactions(store, projectId, milestoneId, readTask);
+    const milestone = store.readMilestone(projectId, milestoneId);
+    assertMilestonePlanAgreement(store, milestone);
+    assertMilestoneMembershipIntegrity(milestone, readTask, { allowRepairableRequiredCancelled: true, allowRepairableReverseOrphans: true }, listTasks);
+    return milestone;
+}
+export function listMilestonesWithIntegrity(store, projectId, readTask, listTasks) {
+    const milestonesRoot = path.join(store.projectRoot(projectId), 'milestones');
+    if (!existsSync(milestonesRoot))
+        return [];
+    return readdirSync(milestonesRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => readMilestoneWithIntegrity(store, projectId, entry.name, readTask, listTasks))
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
+}
+export function assertMilestoneMembershipIntegrity(milestone, readTask, options = {}, listTasks) {
+    if (!Number.isInteger(milestone.membershipRevision) || milestone.membershipRevision < 0) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} has invalid membershipRevision.`, {
+            membershipRevision: milestone.membershipRevision,
+        });
+    }
+    const membershipTaskIds = milestone.memberships.map((membership) => membership.taskId);
+    const uniqueMembershipTaskIds = new Set(membershipTaskIds);
+    const uniqueTaskIds = new Set(milestone.taskIds);
+    if (uniqueMembershipTaskIds.size !== membershipTaskIds.length) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} memberships contain duplicate Task IDs.`, {
+            taskIds: membershipTaskIds,
+        });
+    }
+    if (uniqueTaskIds.size !== milestone.taskIds.length) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} taskIds contain duplicates.`, {
+            taskIds: milestone.taskIds,
+        });
+    }
+    if (membershipTaskIds.length !== milestone.taskIds.length
+        || membershipTaskIds.some((taskId) => !uniqueTaskIds.has(taskId))
+        || milestone.taskIds.some((taskId) => !uniqueMembershipTaskIds.has(taskId))) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} taskIds and memberships diverged.`, {
+            taskIds: milestone.taskIds,
+            membershipTaskIds,
+        });
+    }
+    for (const membership of milestone.memberships) {
+        const task = readTask(membership.taskId);
+        if (task.milestoneId !== milestone.id) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} is no longer linked to Milestone ${milestone.id}.`, {
+                milestoneId: milestone.id,
+                taskId: task.id,
+                taskMilestoneId: task.milestoneId,
+            });
+        }
+        if (membership.disposition === 'required' && task.status === 'cancelled' && !options.allowRepairableRequiredCancelled) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Required Milestone Task ${task.id} is cancelled.`, {
+                milestoneId: milestone.id,
+                taskId: task.id,
+                taskStatus: task.status,
+            });
+        }
+        if (membership.disposition === 'cancelled' && task.status !== 'cancelled') {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Cancelled Milestone membership requires Task ${task.id} to be cancelled.`, {
+                milestoneId: milestone.id,
+                taskId: task.id,
+                disposition: membership.disposition,
+                taskStatus: task.status,
+            });
+        }
+    }
+    if (listTasks && !options.allowRepairableReverseOrphans) {
+        const reverseOrphans = listTasks()
+            .filter((task) => task.milestoneId === milestone.id)
+            .filter((task) => task.status !== 'cancelled')
+            .filter((task) => !uniqueMembershipTaskIds.has(task.id));
+        if (reverseOrphans.length > 0) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestone.id} has linked Tasks that are missing from its classified membership.`, {
+                diagnosticCode: 'MILESTONE_SCOPE_INCOMPLETE',
+                milestoneId: milestone.id,
+                orphanTaskIds: reverseOrphans.map((task) => task.id),
+                requiredAction: 'Add every linked Task as required, waived, or cancelled through a scope change.',
+            });
+        }
+    }
+}
+export function assertMilestoneScopeChangeStatusAllowed(milestone) {
+    if (!SCOPE_CHANGE_ALLOWED_STATUSES.has(milestone.status)) {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestone.id} cannot change scope while ${milestone.status}.`, {
+            milestoneId: milestone.id,
+            status: milestone.status,
+        });
+    }
+}
+export function prepareMilestoneScopeChangeCandidate(options) {
+    const { milestone, plan, readTask, actor } = options;
+    const trimmedActor = actor.trim();
+    if (!trimmedActor) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Milestone scope change requires an explicit actor.');
+    }
+    if (trimmedActor.startsWith('agent:') && !options.autonomyContractEventHash) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope change is human-only and rejects delegated agent actors.', {
+            actor: trimmedActor,
+        });
+    }
+    if (options.autonomyContractEventHash) {
+        assertHash64(options.autonomyContractEventHash, 'Milestone autonomy contract event hash');
+    }
+    const authorizationMode = options.autonomyContractEventHash ? 'milestone-autonomy' : 'human';
+    const autonomyContractEventHash = options.autonomyContractEventHash ?? null;
+    const normalizedPlan = normalizeMilestonePlan(plan);
+    const before = milestoneScopeSnapshotFromState(milestone);
+    const after = milestoneScopeSnapshotFromPlan(normalizedPlan);
+    if (canonicalJsonStringify(before) === canonicalJsonStringify(after)) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope change is a no-op.', {
+            milestoneId: milestone.id,
+            revision: milestone.revision,
+        });
+    }
+    const taskIds = normalizedPlan.taskIds;
+    if (new Set(taskIds).size !== taskIds.length) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Milestone memberships must have unique Task IDs.');
+    }
+    const repairableCancelledRequired = new Set(milestone.memberships
+        .filter((membership) => membership.disposition === 'required')
+        .map((membership) => membership.taskId)
+        .filter((taskId) => readTask(taskId).status === 'cancelled'));
+    for (const membership of normalizedPlan.memberships) {
+        const task = readTask(membership.taskId);
+        if (task.milestoneId !== milestone.id) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} is not linked to Milestone ${milestone.id}.`);
+        }
+        if (repairableCancelledRequired.has(task.id) && membership.disposition !== 'cancelled') {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone scope change must repair cancelled required Task ${task.id} by marking its membership cancelled.`, {
+                milestoneId: milestone.id,
+                taskId: task.id,
+                currentDisposition: 'required',
+                candidateDisposition: membership.disposition,
+            });
+        }
+    }
+    const nextIds = new Set(taskIds);
+    for (const existing of milestone.memberships) {
+        if (nextIds.has(existing.taskId))
+            continue;
+        const task = readTask(existing.taskId);
+        if (taskHasStarted(task)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Started Task ${task.id} cannot be removed from a Milestone.`);
+        }
+    }
+    const authorizations = milestone.authorizations.map((authorization) => authorization.kind === 'execution' && authorization.decision === 'approved'
+        ? { ...authorization, decision: 'superseded' }
+        : authorization);
+    const candidatePlanHash = sha256Hex(renderMilestonePlanArtifact(normalizedPlan));
+    const candidateMembershipRevision = milestone.membershipRevision + 1;
+    const confirmationCodeBindingHash = computeMilestoneScopeChangeBindingHash({
+        milestoneId: milestone.id,
+        expectedRevision: milestone.revision,
+        previousPlanHash: milestone.planHash,
+        previousMembershipRevision: milestone.membershipRevision,
+        candidatePlanHash,
+        candidateMembershipRevision,
+        actor: trimmedActor,
+        after,
+        authorizationMode,
+        autonomyContractEventHash,
+    });
+    return {
+        milestoneId: milestone.id,
+        expectedRevision: milestone.revision,
+        actor: trimmedActor,
+        normalizedPlan,
+        authorizations,
+        candidatePlanHash,
+        candidateMembershipRevision,
+        after,
+        confirmationCodeBindingHash,
+        confirmationCode: milestoneScopeChangeConfirmationCode(confirmationCodeBindingHash),
+        authorizationMode,
+        autonomyContractEventHash,
+    };
+}
+export function applyMilestoneScopeChangeTransaction(options) {
+    const { store, milestone, expectedRevision, prepared, now, readTask } = options;
+    const milestoneRoot = store.milestoneRoot(milestone.projectId, milestone.id);
+    const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, milestone.projectId, milestone.id);
+    const planText = renderMilestonePlanArtifact(prepared.normalizedPlan);
+    const stagedPlan = store.stageArtifact(milestoneRoot, 'plan.json', planText);
+    if (stagedPlan.hash !== prepared.candidatePlanHash) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope change candidate drifted before apply.', {
+            expectedPlanHash: prepared.candidatePlanHash,
+            actualPlanHash: stagedPlan.hash,
+        });
+    }
+    const currentEvents = readMilestoneScopeChangeEvents(store, milestone.projectId, milestone.id);
+    const preparedSidecar = prepareSidecarAppend(currentEvents, createMilestoneScopeChangeEvent({
+        milestone,
+        normalizedPlan: prepared.normalizedPlan,
+        actor: prepared.actor,
+        now,
+        previousEventHash: currentEvents.at(-1)?.eventHash ?? null,
+        candidatePlanHash: stagedPlan.hash,
+        candidateMembershipRevision: prepared.candidateMembershipRevision,
+        confirmationCodeBindingHash: prepared.confirmationCodeBindingHash,
+        authorizationMode: prepared.authorizationMode,
+        autonomyContractEventHash: prepared.autonomyContractEventHash,
+    }), { validateEvent: (candidate) => validateMilestoneScopeChangeEvent(candidate, milestone.id) });
+    if (preparedSidecar.event.actor !== prepared.actor) {
+        throw new WorkflowError('STATE_CORRUPT', 'Prepared Milestone scope-change actor drifted before journal apply.', {
+            expectedActor: prepared.actor,
+            actualActor: preparedSidecar.event.actor,
+        });
+    }
+    if (preparedSidecar.event.confirmationCodeBindingHash !== prepared.confirmationCodeBindingHash) {
+        throw new WorkflowError('STATE_CORRUPT', 'Prepared Milestone scope-change binding drifted before journal apply.', {
+            expectedBindingHash: prepared.confirmationCodeBindingHash,
+            actualBindingHash: preparedSidecar.event.confirmationCodeBindingHash,
+        });
+    }
+    const stagedSidecar = store.stageArtifact(milestoneRoot, SCOPE_CHANGE_SIDECAR, preparedSidecar.content);
+    const candidateState = {
+        ...milestone,
+        revision: milestone.revision + 1,
+        updatedAt: now.toISOString(),
+        status: 'awaiting_execution_authorization',
+        outcome: prepared.normalizedPlan.outcome,
+        successSignal: prepared.normalizedPlan.successSignal,
+        acceptance: prepared.normalizedPlan.acceptance,
+        taskIds: prepared.normalizedPlan.taskIds,
+        memberships: prepared.normalizedPlan.memberships,
+        checks: prepared.normalizedPlan.checks,
+        membershipRevision: prepared.candidateMembershipRevision,
+        authorizations: prepared.authorizations,
+        planHash: stagedPlan.hash,
+        resultHash: null,
+        evidenceHash: null,
+        acceptedHead: null,
+        cancellationReason: null,
+    };
+    assertMilestoneMembershipIntegrity(candidateState, readTask);
+    const stagedState = store.stageArtifact(milestoneRoot, 'state.json', `${JSON.stringify(candidateState, null, 2)}\n`);
+    const transactionId = `tx-${createEntityId('MS', now.getTime())}`;
+    const journal = {
+        transactionId,
+        milestoneId: milestone.id,
+        expectedMilestoneRevision: milestone.revision,
+        actor: prepared.actor,
+        confirmationCodeBindingHash: prepared.confirmationCodeBindingHash,
+        phase: 'prepared',
+        targetFiles: [
+            {
+                path: 'state.json',
+                preimage: captureJournalTargetSnapshot(alpha6MilestoneRoot, 'state.json'),
+                staged: createJournalSnapshotFromContent(alpha6MilestoneRoot, readFileSync(stagedState.stagedFile), { mode: 'inline' }),
+            },
+            {
+                path: 'plan.json',
+                preimage: captureJournalTargetSnapshot(alpha6MilestoneRoot, 'plan.json'),
+                staged: createJournalSnapshotFromContent(alpha6MilestoneRoot, readFileSync(stagedPlan.stagedFile), { mode: 'inline' }),
+            },
+            {
+                path: SCOPE_CHANGE_SIDECAR,
+                preimage: captureJournalTargetSnapshot(alpha6MilestoneRoot, SCOPE_CHANGE_SIDECAR),
+                staged: createJournalSnapshotFromContent(alpha6MilestoneRoot, readFileSync(stagedSidecar.stagedFile), { mode: 'inline' }),
+            },
+        ],
+        preparedAt: now.toISOString(),
+        updatedAt: now.toISOString(),
+    };
+    if (journal.actor !== preparedSidecar.event.actor) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone transaction journal actor does not match latest staged scope-change event.', {
+            journalActor: journal.actor,
+            eventActor: preparedSidecar.event.actor,
+        });
+    }
+    if (journal.confirmationCodeBindingHash !== preparedSidecar.event.confirmationCodeBindingHash) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone transaction journal binding does not match latest staged scope-change event.', {
+            journalBindingHash: journal.confirmationCodeBindingHash,
+            eventBindingHash: preparedSidecar.event.confirmationCodeBindingHash,
+        });
+    }
+    writeMilestoneTransactionJournal(alpha6MilestoneRoot, journal);
+    try {
+        updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, transactionId, 'applying', now.toISOString(), {
+            expectedMilestoneId: milestone.id,
+        });
+        store.publishArtifact(stagedPlan);
+        store.publishArtifact({ ...stagedSidecar, hash: preparedSidecar.contentHash });
+        store.publishArtifact(stagedState);
+    }
+    catch (error) {
+        rollbackMilestoneTransaction(store, milestone.projectId, milestone.id, journal, readTask);
+        throw error;
+    }
+    return finalizeCompletedMilestoneTransaction(store, milestone.projectId, milestone.id, journal, readTask, {
+        expectedRevisionAfterApply: expectedRevision + 1,
+    });
+}
+function recoverMilestoneScopeChangeTransactions(store, projectId, milestoneId, readTask) {
+    const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+    const transactionDir = path.join(alpha6MilestoneRoot, '.transactions');
+    if (!existsSync(transactionDir))
+        return;
+    const journals = listMilestoneTransactionJournals(alpha6MilestoneRoot, { expectedMilestoneId: milestoneId });
+    for (const journal of journals) {
+        validateMilestoneTransactionTargets(journal);
+        try {
+            if (shouldCompleteMilestoneTransaction(store, projectId, milestoneId, journal, readTask)) {
+                completeMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+                continue;
+            }
+        }
+        catch {
+            rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+            continue;
+        }
+        rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+    }
+}
+function assertMilestonePlanAgreement(store, milestone) {
+    if (milestone.planHash === null)
+        return;
+    const milestoneRoot = store.milestoneRoot(milestone.projectId, milestone.id);
+    const currentPlanHash = store.hashArtifact(milestoneRoot, 'plan.json');
+    if (currentPlanHash !== milestone.planHash) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} planHash does not match plan.json.`, {
+            expectedPlanHash: milestone.planHash,
+            actualPlanHash: currentPlanHash,
+        });
+    }
+    const plan = parseMilestonePlanArtifact(readFileSync(path.join(milestoneRoot, 'plan.json'), 'utf8'), milestone.id);
+    const expectedScope = milestoneScopeSnapshotFromState(milestone);
+    const actualScope = milestoneScopeSnapshotFromPlan(plan);
+    if (canonicalJsonStringify(expectedScope) !== canonicalJsonStringify(actualScope)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} state.json and plan.json diverged.`, {
+            milestoneId: milestone.id,
+            stateScope: expectedScope,
+            planScope: actualScope,
+        });
+    }
+    const scopeEvents = readMilestoneScopeChangeEvents(store, milestone.projectId, milestone.id);
+    if (scopeEvents.length === 0)
+        return;
+    const latest = scopeEvents.at(-1);
+    if (latest.candidatePlanHash !== milestone.planHash
+        || latest.candidateMembershipRevision !== milestone.membershipRevision
+        || canonicalJsonStringify(latest.after) !== canonicalJsonStringify(expectedScope)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} scope-change sidecar diverged from current state.`, {
+            milestoneId: milestone.id,
+            latestEventId: latest.eventId,
+            latestCandidatePlanHash: latest.candidatePlanHash,
+            milestonePlanHash: milestone.planHash,
+            latestCandidateMembershipRevision: latest.candidateMembershipRevision,
+            milestoneMembershipRevision: milestone.membershipRevision,
+        });
+    }
+}
+function readMilestoneScopeChangeEvents(store, projectId, milestoneId) {
+    const sidecarPath = path.join(resolveAlpha6MilestoneRoot(store, projectId, milestoneId), SCOPE_CHANGE_SIDECAR);
+    assertNoSymlinkPathComponents(sidecarPath, { label: 'Milestone scope-change sidecar path', requireLeaf: true });
+    if (!existsSync(sidecarPath))
+        return [];
+    return parseMilestoneScopeChangeEvents(readFileSync(sidecarPath, 'utf8'), milestoneId);
+}
+function validateMilestoneScopeChangeEvent(event, expectedMilestoneId) {
+    if (event.milestoneId !== expectedMilestoneId) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change sidecar milestone mismatch.', {
+            expectedMilestoneId,
+            actualMilestoneId: event.milestoneId,
+            eventId: event.eventId,
+        });
+    }
+    if (!Number.isInteger(event.previousMilestoneRevision) || event.previousMilestoneRevision < 1) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change previousMilestoneRevision is invalid.', {
+            eventId: event.eventId,
+            previousMilestoneRevision: event.previousMilestoneRevision,
+        });
+    }
+    if (!Number.isInteger(event.previousMembershipRevision) || event.previousMembershipRevision < 0) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change previousMembershipRevision is invalid.', {
+            eventId: event.eventId,
+            previousMembershipRevision: event.previousMembershipRevision,
+        });
+    }
+    if (!Number.isInteger(event.candidateMembershipRevision) || event.candidateMembershipRevision < 1) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change candidateMembershipRevision is invalid.', {
+            eventId: event.eventId,
+            candidateMembershipRevision: event.candidateMembershipRevision,
+        });
+    }
+    if (event.candidateMembershipRevision !== event.previousMembershipRevision + 1) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change membershipRevision must advance by exactly one.', {
+            eventId: event.eventId,
+            previousMembershipRevision: event.previousMembershipRevision,
+            candidateMembershipRevision: event.candidateMembershipRevision,
+        });
+    }
+    if (!event.actor.trim()) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change actor is required.', { eventId: event.eventId });
+    }
+    if (event.actor.startsWith('agent:') && event.authorizationMode !== 'milestone-autonomy') {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change actor must be human-only.', {
+            eventId: event.eventId,
+            actor: event.actor,
+        });
+    }
+    if (event.authorizationMode === 'milestone-autonomy') {
+        if (!event.actor.startsWith('agent:') || !event.autonomyContractEventHash) {
+            throw new WorkflowError('STATE_CORRUPT', 'Autonomous Milestone scope change requires an agent actor and contract evidence.', {
+                eventId: event.eventId,
+            });
+        }
+        assertHash64(event.autonomyContractEventHash, 'Milestone scope-change autonomyContractEventHash');
+    }
+    else if (event.autonomyContractEventHash !== undefined && event.autonomyContractEventHash !== null) {
+        throw new WorkflowError('STATE_CORRUPT', 'Human Milestone scope change cannot carry autonomy contract evidence.');
+    }
+    if (!event.confirmationCodeBindingHash.trim()) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change confirmationCodeBindingHash is required.', {
+            eventId: event.eventId,
+        });
+    }
+    assertHash64(event.confirmationCodeBindingHash, 'Milestone scope-change confirmationCodeBindingHash');
+    const expectedBindingHash = computeMilestoneScopeChangeBindingHash({
+        milestoneId: event.milestoneId,
+        expectedRevision: event.previousMilestoneRevision,
+        previousPlanHash: event.previousPlanHash,
+        previousMembershipRevision: event.previousMembershipRevision,
+        candidatePlanHash: event.candidatePlanHash,
+        candidateMembershipRevision: event.candidateMembershipRevision,
+        actor: event.actor,
+        after: event.after,
+        ...(event.authorizationMode === undefined ? {} : { authorizationMode: event.authorizationMode }),
+        ...(event.autonomyContractEventHash === undefined
+            ? {}
+            : { autonomyContractEventHash: event.autonomyContractEventHash }),
+    });
+    if (event.confirmationCodeBindingHash !== expectedBindingHash) {
+        throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change confirmationCodeBindingHash is inconsistent.', {
+            eventId: event.eventId,
+            expectedBindingHash,
+            actualBindingHash: event.confirmationCodeBindingHash,
+        });
+    }
+}
+function validateMilestoneTransactionTargets(journal) {
+    const paths = journal.targetFiles.map((target) => target.path);
+    const unique = new Set(paths);
+    if (unique.size !== MILESTONE_TARGETS.length || paths.length !== MILESTONE_TARGETS.length) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} target set is invalid.`, {
+            paths,
+        });
+    }
+    for (const target of MILESTONE_TARGETS) {
+        if (!unique.has(target)) {
+            throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} is missing ${target}.`);
+        }
+    }
+}
+function shouldCompleteMilestoneTransaction(store, projectId, milestoneId, journal, readTask) {
+    const staged = readStagedMilestoneTransactionBundle(store, projectId, milestoneId, journal);
+    const currentStates = journal.targetFiles.map((target) => {
+        const current = captureJournalTargetSnapshot(resolveAlpha6MilestoneRoot(store, projectId, milestoneId), target.path);
+        const matchesPreimage = canonicalJsonStringify(current) === canonicalJsonStringify(target.preimage);
+        const matchesStaged = canonicalJsonStringify(current) === canonicalJsonStringify(target.staged);
+        return { target: target.path, matchesPreimage, matchesStaged };
+    });
+    if (currentStates.some((state) => !state.matchesPreimage && !state.matchesStaged))
+        return false;
+    if (staged.state.id !== journal.milestoneId || staged.state.revision !== journal.expectedMilestoneRevision + 1) {
+        return false;
+    }
+    assertMilestoneMembershipIntegrity(staged.state, readTask);
+    return true;
+}
+function completeMilestoneTransaction(store, projectId, milestoneId, journal, readTask) {
+    const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+    try {
+        updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, journal.transactionId, 'applying', new Date().toISOString(), {
+            expectedMilestoneId: milestoneId,
+        });
+        for (const target of journal.targetFiles) {
+            const content = readJournalSnapshotContent(alpha6MilestoneRoot, target.staged, {
+                expectedMilestoneId: milestoneId,
+                transactionId: journal.transactionId,
+            });
+            if (content === null) {
+                rmSync(resolveMilestoneTransactionTargetPath(alpha6MilestoneRoot, target.path), { force: true });
+                continue;
+            }
+            const staged = store.stageArtifact(store.milestoneRoot(projectId, milestoneId), target.path, content.toString('utf8'));
+            store.publishArtifact(staged);
+        }
+    }
+    catch (error) {
+        rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+        throw error;
+    }
+    finalizeCompletedMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+}
+function rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask) {
+    const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+    for (const target of journal.targetFiles) {
+        const content = readJournalSnapshotContent(alpha6MilestoneRoot, target.preimage, {
+            expectedMilestoneId: milestoneId,
+            transactionId: journal.transactionId,
+        });
+        if (content === null) {
+            rmSync(resolveMilestoneTransactionTargetPath(alpha6MilestoneRoot, target.path), { force: true });
+            continue;
+        }
+        const staged = store.stageArtifact(store.milestoneRoot(projectId, milestoneId), target.path, content.toString('utf8'));
+        store.publishArtifact(staged);
+    }
+    try {
+        const restored = store.readMilestone(projectId, milestoneId);
+        if (restored.revision !== journal.expectedMilestoneRevision) {
+            throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} rollback restored an unexpected revision.`, {
+                expectedRevision: journal.expectedMilestoneRevision,
+                actualRevision: restored.revision,
+            });
+        }
+        assertMilestonePlanAgreement(store, restored);
+        assertMilestoneMembershipIntegrity(restored, readTask, { allowRepairableRequiredCancelled: true });
+    }
+    catch (error) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} rollback validation failed.`, {
+            transactionId: journal.transactionId,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, journal.transactionId, 'rolled_back', new Date().toISOString(), {
+        expectedMilestoneId: milestoneId,
+    });
+    removeMilestoneTransactionJournal(alpha6MilestoneRoot, journal.transactionId);
+}
+function finalizeCompletedMilestoneTransaction(store, projectId, milestoneId, journal, readTask, options = {}) {
+    const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+    let saved;
+    try {
+        saved = store.readMilestone(projectId, milestoneId);
+        if (options.expectedRevisionAfterApply !== undefined && saved.revision !== options.expectedRevisionAfterApply) {
+            throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope change wrote an unexpected revision.`, {
+                expectedRevision: options.expectedRevisionAfterApply,
+                actualRevision: saved.revision,
+            });
+        }
+        assertMilestonePlanAgreement(store, saved);
+        assertMilestoneMembershipIntegrity(saved, readTask);
+    }
+    catch (error) {
+        rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+        throw error;
+    }
+    updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, journal.transactionId, 'applied', new Date().toISOString(), {
+        expectedMilestoneId: milestoneId,
+    });
+    removeMilestoneTransactionJournal(alpha6MilestoneRoot, journal.transactionId);
+    return saved;
+}
+function readStagedMilestoneTransactionBundle(store, projectId, milestoneId, journal) {
+    const stateSnapshot = journal.targetFiles.find((target) => target.path === 'state.json')?.staged;
+    const planSnapshot = journal.targetFiles.find((target) => target.path === 'plan.json')?.staged;
+    const sidecarSnapshot = journal.targetFiles.find((target) => target.path === SCOPE_CHANGE_SIDECAR)?.staged;
+    if (!stateSnapshot || !planSnapshot || !sidecarSnapshot) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} is missing a staged bundle.`);
+    }
+    const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+    const stateBuffer = readJournalSnapshotContent(alpha6MilestoneRoot, stateSnapshot, {
+        expectedMilestoneId: milestoneId,
+        transactionId: journal.transactionId,
+    });
+    const planBuffer = readJournalSnapshotContent(alpha6MilestoneRoot, planSnapshot, {
+        expectedMilestoneId: milestoneId,
+        transactionId: journal.transactionId,
+    });
+    const sidecarBuffer = readJournalSnapshotContent(alpha6MilestoneRoot, sidecarSnapshot, {
+        expectedMilestoneId: milestoneId,
+        transactionId: journal.transactionId,
+    });
+    if (!stateBuffer || !planBuffer || !sidecarBuffer) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} has an incomplete staged bundle.`);
+    }
+    const state = parseStagedMilestoneStateArtifact(stateBuffer.toString('utf8'), projectId, journal.milestoneId, journal.transactionId);
+    const plan = parseMilestonePlanArtifact(planBuffer.toString('utf8'), journal.milestoneId);
+    const events = parseMilestoneScopeChangeEvents(sidecarBuffer.toString('utf8'), journal.milestoneId);
+    const latestEvent = events.at(-1);
+    if (!latestEvent) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} has no staged scope-change event.`);
+    }
+    if (latestEvent.candidatePlanHash !== state.planHash
+        || latestEvent.candidateMembershipRevision !== state.membershipRevision
+        || canonicalJsonStringify(latestEvent.after) !== canonicalJsonStringify(milestoneScopeSnapshotFromState(state))
+        || canonicalJsonStringify(milestoneScopeSnapshotFromPlan(plan)) !== canonicalJsonStringify(milestoneScopeSnapshotFromState(state))
+        || latestEvent.actor !== journal.actor
+        || latestEvent.confirmationCodeBindingHash !== journal.confirmationCodeBindingHash) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} staged bundle is inconsistent.`);
+    }
+    if (state.revision !== journal.expectedMilestoneRevision + 1) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} staged state revision is inconsistent.`, {
+            expectedRevision: journal.expectedMilestoneRevision + 1,
+            actualRevision: state.revision,
+        });
+    }
+    if (latestEvent.previousMilestoneRevision !== journal.expectedMilestoneRevision) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} latest event revision does not match journal precondition.`, {
+            expectedPreviousMilestoneRevision: journal.expectedMilestoneRevision,
+            actualPreviousMilestoneRevision: latestEvent.previousMilestoneRevision,
+        });
+    }
+    return { state, plan, events };
+}
+function parseMilestonePlanArtifact(content, milestoneId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json is not valid JSON.`, {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json must be an object.`);
+    }
+    const record = parsed;
+    const allowedKeys = new Set(['outcome', 'successSignal', 'acceptance', 'memberships', 'checks']);
+    const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+    if (extraKeys.length > 0) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json contains unexpected fields.`, {
+            extraKeys,
+        });
+    }
+    if (typeof record.outcome !== 'string' || !record.outcome.trim()) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json outcome must be a non-empty string.`);
+    }
+    if (typeof record.successSignal !== 'string' || !record.successSignal.trim()) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json successSignal must be a non-empty string.`);
+    }
+    const acceptance = parseStringArray(record.acceptance, `Milestone ${milestoneId} plan.json acceptance`);
+    const checks = parseStringArray(record.checks, `Milestone ${milestoneId} plan.json checks`);
+    const memberships = parseMilestoneMembershipArray(record.memberships, milestoneId);
+    return normalizeMilestonePlan({
+        outcome: record.outcome,
+        successSignal: record.successSignal,
+        acceptance,
+        memberships,
+        checks,
+    });
+}
+function parseMilestoneScopeChangeEvents(content, milestoneId) {
+    if (content.length === 0) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar must not be empty.`);
+    }
+    const rawLines = content.split('\n');
+    if (rawLines.at(-1) === '')
+        rawLines.pop();
+    if (rawLines.some((line) => line.length === 0)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar contains a blank line.`);
+    }
+    const events = [];
+    const eventIds = new Set();
+    let previousEventHash = null;
+    for (const [index, rawLine] of rawLines.entries()) {
+        let parsed;
+        try {
+            parsed = JSON.parse(rawLine);
+        }
+        catch (error) {
+            throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar has invalid JSONL.`, {
+                line: index + 1,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const event = parseMilestoneScopeChangeEventRecord(parsed, milestoneId, index + 1);
+        validateMilestoneScopeChangeEvent(event, milestoneId);
+        if (eventIds.has(event.eventId)) {
+            throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar contains duplicate event id.`, {
+                line: index + 1,
+                eventId: event.eventId,
+            });
+        }
+        eventIds.add(event.eventId);
+        if (event.previousEventHash !== previousEventHash) {
+            throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar chain is broken.`, {
+                line: index + 1,
+                expectedPreviousEventHash: previousEventHash,
+                actualPreviousEventHash: event.previousEventHash,
+            });
+        }
+        const expectedEventHash = computeSidecarEventHash(event);
+        if (event.eventHash !== expectedEventHash) {
+            throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change eventHash mismatch.`, {
+                line: index + 1,
+                expectedEventHash,
+                actualEventHash: event.eventHash,
+            });
+        }
+        previousEventHash = event.eventHash;
+        const previous = events.at(-1);
+        if (previous) {
+            if (event.previousMilestoneRevision <= previous.previousMilestoneRevision
+                || event.previousPlanHash !== previous.candidatePlanHash
+                || event.previousMembershipRevision !== previous.candidateMembershipRevision
+                || canonicalJsonStringify(event.before) !== canonicalJsonStringify(previous.after)) {
+                throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change semantic continuity is broken.`, {
+                    line: index + 1,
+                    previousEventId: previous.eventId,
+                    eventId: event.eventId,
+                });
+            }
+        }
+        events.push(event);
+    }
+    return events;
+}
+function createMilestoneScopeChangeEvent(options) {
+    const { milestone, normalizedPlan, actor, now, previousEventHash, candidatePlanHash, candidateMembershipRevision, confirmationCodeBindingHash, authorizationMode, autonomyContractEventHash, } = options;
+    return {
+        eventId: createEntityId('MS', now.getTime()),
+        previousEventHash,
+        recordedAt: now.toISOString(),
+        milestoneId: milestone.id,
+        previousMilestoneRevision: milestone.revision,
+        previousPlanHash: milestone.planHash,
+        previousMembershipRevision: milestone.membershipRevision,
+        candidatePlanHash,
+        candidateMembershipRevision,
+        before: milestoneScopeSnapshotFromState(milestone),
+        after: milestoneScopeSnapshotFromPlan(normalizedPlan),
+        actor: actor.trim(),
+        confirmationCodeBindingHash,
+        ...(authorizationMode === 'milestone-autonomy'
+            ? { authorizationMode, autonomyContractEventHash }
+            : {}),
+    };
+}
+function milestoneScopeSnapshotFromState(milestone) {
+    return {
+        outcome: milestone.outcome,
+        successSignal: milestone.successSignal,
+        acceptance: milestone.acceptance,
+        checks: milestone.checks,
+        taskIds: milestone.taskIds,
+        memberships: milestone.memberships,
+    };
+}
+function parseMilestoneScopeChangeEventRecord(parsed, milestoneId, line) {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change event must be an object.`, { line });
+    }
+    const record = parsed;
+    const allowedKeys = new Set([
+        'eventId',
+        'recordedAt',
+        'previousEventHash',
+        'milestoneId',
+        'previousMilestoneRevision',
+        'previousPlanHash',
+        'previousMembershipRevision',
+        'candidatePlanHash',
+        'candidateMembershipRevision',
+        'before',
+        'after',
+        'actor',
+        'confirmationCodeBindingHash',
+        'authorizationMode',
+        'autonomyContractEventHash',
+        'eventHash',
+    ]);
+    const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+    if (extraKeys.length > 0) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change event contains unexpected fields.`, {
+            line,
+            extraKeys,
+        });
+    }
+    const eventId = requireNonEmptyString(record.eventId, `Milestone ${milestoneId} scope-change eventId`, { line });
+    const recordedAt = requireIsoTimestamp(record.recordedAt, `Milestone ${milestoneId} scope-change recordedAt`, { line });
+    const previousEventHash = requireNullableHash64(record.previousEventHash, `Milestone ${milestoneId} scope-change previousEventHash`, { line });
+    const actualMilestoneId = requireNonEmptyString(record.milestoneId, `Milestone ${milestoneId} scope-change milestoneId`, { line });
+    const previousMilestoneRevision = requireInteger(record.previousMilestoneRevision, `Milestone ${milestoneId} scope-change previousMilestoneRevision`, { line });
+    const previousPlanHash = requireNullableHash64(record.previousPlanHash, `Milestone ${milestoneId} scope-change previousPlanHash`, { line });
+    const previousMembershipRevision = requireInteger(record.previousMembershipRevision, `Milestone ${milestoneId} scope-change previousMembershipRevision`, { line });
+    const candidatePlanHash = requireHash64(record.candidatePlanHash, `Milestone ${milestoneId} scope-change candidatePlanHash`, { line });
+    const candidateMembershipRevision = requireInteger(record.candidateMembershipRevision, `Milestone ${milestoneId} scope-change candidateMembershipRevision`, { line });
+    const before = parseMilestoneScopeSnapshot(record.before, milestoneId, line, 'before');
+    const after = parseMilestoneScopeSnapshot(record.after, milestoneId, line, 'after');
+    const actor = requireNonEmptyString(record.actor, `Milestone ${milestoneId} scope-change actor`, { line });
+    const confirmationCodeBindingHash = requireHash64(record.confirmationCodeBindingHash, `Milestone ${milestoneId} scope-change confirmationCodeBindingHash`, { line });
+    const authorizationMode = record.authorizationMode === undefined
+        ? undefined
+        : requireMilestoneScopeChangeAuthorizationMode(record.authorizationMode, milestoneId, line);
+    const autonomyContractEventHash = record.autonomyContractEventHash === undefined
+        ? undefined
+        : requireNullableHash64(record.autonomyContractEventHash, `Milestone ${milestoneId} scope-change autonomyContractEventHash`, { line });
+    const eventHash = requireHash64(record.eventHash, `Milestone ${milestoneId} scope-change eventHash`, { line });
+    return {
+        eventId,
+        recordedAt,
+        previousEventHash,
+        milestoneId: actualMilestoneId,
+        previousMilestoneRevision,
+        previousPlanHash,
+        previousMembershipRevision,
+        candidatePlanHash,
+        candidateMembershipRevision,
+        before,
+        after,
+        actor,
+        confirmationCodeBindingHash,
+        ...(authorizationMode === undefined ? {} : { authorizationMode }),
+        ...(autonomyContractEventHash === undefined ? {} : { autonomyContractEventHash }),
+        eventHash,
+    };
+}
+function requireMilestoneScopeChangeAuthorizationMode(value, milestoneId, line) {
+    if (value !== 'human' && value !== 'milestone-autonomy') {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change authorizationMode is invalid.`, {
+            line,
+            value,
+        });
+    }
+    return value;
+}
+function parseMilestoneScopeSnapshot(value, milestoneId, line, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change ${label} snapshot must be an object.`, { line });
+    }
+    const record = value;
+    const allowedKeys = new Set(['outcome', 'successSignal', 'acceptance', 'checks', 'taskIds', 'memberships']);
+    const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+    if (extraKeys.length > 0) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change ${label} snapshot contains unexpected fields.`, {
+            line,
+            extraKeys,
+        });
+    }
+    const snapshot = {
+        outcome: requireNonEmptyString(record.outcome, `Milestone ${milestoneId} scope-change ${label}.outcome`, { line }),
+        successSignal: requireNonEmptyString(record.successSignal, `Milestone ${milestoneId} scope-change ${label}.successSignal`, { line }),
+        acceptance: parseStringArray(record.acceptance, `Milestone ${milestoneId} scope-change ${label}.acceptance`, { line }),
+        checks: parseStringArray(record.checks, `Milestone ${milestoneId} scope-change ${label}.checks`, { line }),
+        taskIds: parseTaskIdArray(record.taskIds, `Milestone ${milestoneId} scope-change ${label}.taskIds`, { line }),
+        memberships: parseMilestoneMembershipArray(record.memberships, milestoneId, { line, label }),
+    };
+    assertSnapshotTaskIdsMatchMemberships(snapshot, milestoneId, { line, label });
+    return snapshot;
+}
+function parseMilestoneMembershipArray(value, milestoneId, options = {}) {
+    const label = options.label ? `${options.label}.memberships` : 'memberships';
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} ${label} must be a non-empty array.`, options.line !== undefined ? { line: options.line } : {});
+    }
+    const memberships = value.map((entry, index) => parseMilestoneMembership(entry, milestoneId, index, options.line));
+    const taskIds = memberships.map((membership) => membership.taskId);
+    if (new Set(taskIds).size !== taskIds.length) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} ${label} contains duplicate taskIds.`, options.line !== undefined ? { line: options.line, taskIds } : { taskIds });
+    }
+    return memberships;
+}
+function parseMilestoneMembership(value, milestoneId, index, line) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership at index ${index} must be an object.`, line !== undefined ? { line, index } : { index });
+    }
+    const record = value;
+    const allowedKeys = new Set(['taskId', 'disposition', 'reason']);
+    const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+    if (extraKeys.length > 0) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership contains unexpected fields.`, line !== undefined ? { line, index, extraKeys } : { index, extraKeys });
+    }
+    const taskId = requireNonEmptyString(record.taskId, `Milestone ${milestoneId} membership.taskId`, line !== undefined ? { line, index } : { index });
+    const dispositionValue = requireNonEmptyString(record.disposition, `Milestone ${milestoneId} membership.disposition`, line !== undefined ? { line, index } : { index });
+    if (!['required', 'waived', 'cancelled'].includes(dispositionValue)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership disposition is invalid.`, line !== undefined ? { line, index, disposition: dispositionValue } : { index, disposition: dispositionValue });
+    }
+    const disposition = dispositionValue;
+    const reason = typeof record.reason === 'string' ? record.reason.trim() : '';
+    if (disposition !== 'required' && reason.length === 0) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership ${disposition} requires a reason.`, line !== undefined ? { line, index } : { index });
+    }
+    return { taskId, disposition, reason };
+}
+function parseStringArray(value, label, details = {}) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must be a non-empty array.`, details);
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== 'string' || !entry.trim()) {
+            throw new WorkflowError('STATE_CORRUPT', `${label}[${index}] must be a non-empty string.`, { ...details, index });
+        }
+        return entry;
+    });
+}
+function parseTaskIdArray(value, label, details = {}) {
+    const taskIds = parseStringArray(value, label, details);
+    if (new Set(taskIds).size !== taskIds.length) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} contains duplicate taskIds.`, { ...details, taskIds });
+    }
+    return taskIds;
+}
+function requireNonEmptyString(value, label, details = {}) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must be a non-empty string.`, details);
+    }
+    return value;
+}
+function requireInteger(value, label, details = {}) {
+    if (!Number.isInteger(value)) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must be an integer.`, details);
+    }
+    return value;
+}
+function requireHash64(value, label, details = {}) {
+    if (typeof value !== 'string') {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must be a sha256 hex digest.`, details);
+    }
+    assertHash64(value, label);
+    return value;
+}
+function requireNullableHash64(value, label, details = {}) {
+    if (value === null)
+        return null;
+    return requireHash64(value, label, details);
+}
+function requireIsoTimestamp(value, label, details = {}) {
+    if (typeof value !== 'string' || !value.trim() || Number.isNaN(Date.parse(value))) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must be an ISO timestamp string.`, details);
+    }
+    return value;
+}
+function milestoneScopeSnapshotFromPlan(plan) {
+    return {
+        outcome: plan.outcome,
+        successSignal: plan.successSignal,
+        acceptance: plan.acceptance,
+        checks: plan.checks,
+        taskIds: plan.taskIds,
+        memberships: plan.memberships,
+    };
+}
+function renderMilestonePlanArtifact(plan) {
+    return `${JSON.stringify({
+        outcome: plan.outcome,
+        successSignal: plan.successSignal,
+        acceptance: plan.acceptance,
+        memberships: plan.memberships,
+        checks: plan.checks,
+    }, null, 2)}\n`;
+}
+function milestoneScopeChangeConfirmationCode(bindingHash) {
+    return `MSC-${bindingHash.slice(0, 24).toUpperCase()}`;
+}
+function computeMilestoneScopeChangeBindingHash(input) {
+    return sha256Hex(canonicalJsonStringify({
+        kind: 'milestone-scope-change-v1',
+        milestoneId: input.milestoneId,
+        expectedRevision: input.expectedRevision,
+        previousPlanHash: input.previousPlanHash,
+        previousMembershipRevision: input.previousMembershipRevision,
+        candidatePlanHash: input.candidatePlanHash,
+        candidateMembershipRevision: input.candidateMembershipRevision,
+        actor: input.actor,
+        after: input.after,
+        ...(input.authorizationMode === 'milestone-autonomy'
+            ? {
+                authorizationMode: input.authorizationMode,
+                autonomyContractEventHash: input.autonomyContractEventHash,
+            }
+            : {}),
+    }));
+}
+function assertSnapshotTaskIdsMatchMemberships(snapshot, milestoneId, details = {}) {
+    const membershipTaskIds = snapshot.memberships.map((membership) => membership.taskId);
+    const taskIds = [...snapshot.taskIds];
+    if (membershipTaskIds.length !== taskIds.length
+        || membershipTaskIds.some((taskId) => !taskIds.includes(taskId))
+        || taskIds.some((taskId) => !membershipTaskIds.includes(taskId))) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope snapshot taskIds and memberships diverged.`, {
+            ...details,
+            taskIds,
+            membershipTaskIds,
+        });
+    }
+}
+function parseStagedMilestoneStateArtifact(content, expectedProjectId, milestoneId, transactionId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state.json is not valid JSON.`, {
+            milestoneId,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state.json must be an object.`, {
+            milestoneId,
+        });
+    }
+    const record = parsed;
+    if (record.kind !== 'milestone') {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state kind is invalid.`, {
+            milestoneId,
+            kind: record.kind,
+        });
+    }
+    if (record.id !== milestoneId || record.projectId !== expectedProjectId) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state identity is invalid.`, {
+            milestoneId,
+            expectedProjectId,
+            id: record.id,
+            projectId: record.projectId,
+        });
+    }
+    if (!Number.isInteger(record.revision)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state revision is invalid.`, {
+            milestoneId,
+            revision: record.revision,
+        });
+    }
+    if (typeof record.status !== 'string'
+        || !['planning', 'awaiting_execution_authorization', 'active', 'validating', 'accepted', 'blocked', 'cancelled'].includes(record.status)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state status is invalid.`, {
+            milestoneId,
+            status: record.status,
+        });
+    }
+    if (!Array.isArray(record.taskIds) || !Array.isArray(record.memberships) || !Array.isArray(record.authorizations)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state arrays are invalid.`, {
+            milestoneId,
+        });
+    }
+    return parsed;
+}
+function resolveAlpha6MilestoneRoot(store, projectId, milestoneId) {
+    const projectRootLogical = store.projectRoot(projectId);
+    const trustedProjectRoot = existsSync(projectRootLogical) ? realpathSync(projectRootLogical) : path.resolve(projectRootLogical);
+    const milestonesDirLogical = path.join(projectRootLogical, 'milestones');
+    const trustedMilestonesDir = existsSync(milestonesDirLogical)
+        ? realpathSync(milestonesDirLogical)
+        : path.join(trustedProjectRoot, 'milestones');
+    const milestoneRootLogical = store.milestoneRoot(projectId, milestoneId);
+    assertNoSymlinkPathComponents(trustedMilestonesDir, { label: 'Trusted milestones directory', requireLeaf: true });
+    if (existsSync(milestoneRootLogical) && lstatSync(milestoneRootLogical).isSymbolicLink()) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone root must not be a symlink: ${milestoneRootLogical}`);
+    }
+    const resolvedMilestoneRoot = existsSync(milestoneRootLogical)
+        ? realpathSync(milestoneRootLogical)
+        : path.resolve(trustedMilestonesDir, milestoneId);
+    if (resolvedMilestoneRoot !== trustedMilestonesDir
+        && !resolvedMilestoneRoot.startsWith(`${trustedMilestonesDir}${path.sep}`)) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone root escaped the trusted milestones directory: ${milestoneRootLogical}`, {
+            trustedMilestonesDir,
+            resolvedMilestoneRoot,
+        });
+    }
+    return resolvedMilestoneRoot;
+}
+function taskHasStarted(task) {
+    return task.workspaceOwner !== null || [
+        'in_progress',
+        'validating',
+        'needs_fix',
+        'awaiting_final_acceptance',
+        'merging',
+        'ready_to_merge',
+        'merged',
+    ].includes(task.status);
+}
+//# sourceMappingURL=milestone.js.map