@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-source-merge-artifacts.mjs

@@ -0,0 +1,920 @@
+import {
+  applyStage48ControlledMarker,
+  assertSourceMergeApplyPersist,
+  sourceMergeApplyAction,
+  sourceMergeApplyFalseSafetyFields,
+  sourceMergeApplySafety,
+  sourceMergeGateFalseSafetyFields,
+  sourceMergeGateSafety,
+  sourceMergeSandboxFalseSafetyFields,
+  sourceMergeSandboxSafety,
+} from './runtime-source-merge-apply-boundary-model.mjs';
+
+export function createRuntimeSourceMergeArtifacts(input) {
+  const deps = input;
+  const {
+    fs,
+    path,
+    process,
+    spawnSync,
+    jsonSchemaVersion,
+    stateDirectoryName,
+    sourceChangeCandidatesDirectoryName,
+    sourceSandboxRunsDirectoryName,
+    sourceVerificationsDirectoryName,
+    mergeReadinessDirectoryName,
+    mergeApprovalsDirectoryName,
+    mergeAppliesDirectoryName,
+    ensureRoot,
+    workflowPath,
+    fileDigest,
+    digestObject,
+    currentGitHead,
+    writeStateArtifact,
+    readJsonArtifact,
+    latestStateFile,
+    platformSessionReviewFilePath,
+    validatePlatformSessionReviewArtifact,
+    sourceChangeCandidatesDirectory,
+    sourceSandboxRunsDirectory,
+    sourceVerificationsDirectory,
+    sourceChangeCandidateFilePath,
+    sourceSandboxRunFilePath,
+    sourceVerificationFilePath,
+    mergeReadinessDirectory,
+    mergeApprovalsDirectory,
+    mergeAppliesDirectory,
+    mergeReadinessFilePath,
+    mergeApprovalFilePath,
+    mergeApplyFilePath,
+    runtimeTracesDirectory,
+    runtimeTraceFilePath,
+    validateRuntimeTraceArtifact,
+    governanceDirectory,
+    governanceFilePath,
+    validateGovernanceArtifact,
+    methodologyGatesDirectory,
+    methodologyGateFilePath,
+    validateMethodologyGateArtifact,
+    createSourcePatchPlanEnvelope,
+  } = deps;
+
+function sourceChangeCandidateSnapshotPath(root) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(sourceChangeCandidatesDirectory(root), `${timestamp}.source-change-candidate.json`);
+}
+
+function sourceSandboxRunSnapshotPath(root) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(sourceSandboxRunsDirectory(root), `${timestamp}.source-sandbox-run.json`);
+}
+
+function sourceVerificationSnapshotPath(root) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(sourceVerificationsDirectory(root), `${timestamp}.source-verification.json`);
+}
+
+function stage45Safety({ writes = false, candidate = false, sandbox = false } = {}) {
+  return sourceMergeSandboxSafety({ stage: 'Stage 45', writes, candidate, sandbox });
+}
+
+const sourcePatchPlanEnvelope = createSourcePatchPlanEnvelope({
+  fs,
+  path,
+  ensureRoot,
+  workflowPath,
+  fileDigest,
+  digestObject,
+});
+
+function stage46Safety({ writes = false, verification = false } = {}) {
+  return sourceMergeSandboxSafety({ stage: 'Stage 46', writes, verification });
+}
+
+function sourceVerificationEvidencePolicy(root, { execute = false } = {}) {
+  const specs = [
+    { id: 'syntax-check', command: 'node --check tools/vibe-runtime/index.mjs', args: ['--check', 'tools/vibe-runtime/index.mjs'], required: true },
+    { id: 'runtime-check', command: 'node tools/vibe-runtime-check/index.mjs', args: ['tools/vibe-runtime-check/index.mjs'], required: true },
+  ];
+  const verificationRoot = fs.existsSync(path.join(root, 'tools', 'vibe-runtime-check', 'index.mjs')) ? root : process.cwd();
+  const evidence = specs.map((spec) => {
+    if (!execute) return { id: spec.id, command: spec.command, status: 'not-run-preview', exit_code: null, required: spec.required, output_excerpt: 'verification preview only; no command executed' };
+    const result = spawnSync('node', spec.args, { cwd: verificationRoot, encoding: 'utf8', timeout: 120000, windowsHide: true });
+    const exitCode = result.status ?? (result.error ? 1 : 0);
+    const output = `${result.stdout || ''}${result.stderr || ''}`.trim().replace(/\s+/g, ' ').slice(0, 500);
+    return {
+      id: spec.id,
+      command: spec.command,
+      status: exitCode === 0 ? 'passed' : 'failed',
+      exit_code: exitCode,
+      required: spec.required,
+      output_excerpt: output || (exitCode === 0 ? 'command completed without output' : result.error?.message || 'command failed without output'),
+    };
+  });
+  const allowlist = specs.map((item) => item.command);
+  const policy = {
+    stage: 'Stage 46',
+    version: 1,
+    allowlist,
+    required_evidence: specs.filter((item) => item.required).map((item) => item.id),
+    external_command_execution: false,
+    foreground_execution: Boolean(execute),
+    verification_root: verificationRoot,
+    verification_root_digest: digestObject({ verification_root: verificationRoot }),
+    captured_locally: true,
+  };
+  return { policy: { ...policy, policy_digest: digestObject(policy) }, evidence };
+}
+
+function sourceChangeCandidateEnvelope(root, reviewFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const reviewPath = platformSessionReviewFilePath(root, reviewFile);
+  const reviewArtifact = readJsonArtifact(reviewPath, 'Platform session review');
+  const reviewVerification = validatePlatformSessionReviewArtifact(root, reviewArtifact, path.basename(reviewPath));
+  if (!reviewVerification.ok) throw new Error(`platform session review verification failed: ${reviewVerification.failures.join('; ')}`);
+  const review = reviewArtifact.platform_session_review || {};
+  const candidateFile = artifactFile || path.basename(sourceChangeCandidateSnapshotPath(root));
+  const patch = '';
+  const filesTouched = Array.isArray(review.files_touched) ? review.files_touched : [];
+  const core = {
+    version: 1,
+    stage: 'Stage 45',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    review_file: path.basename(reviewPath),
+    review_digest: fileDigest(reviewPath),
+    source_result_file: review.source_result_file || '',
+    source_result_digest: review.source_result_digest || '',
+    session_file: review.session_file || '',
+    session_digest: review.session_digest || '',
+    base_sha: currentGitHead(root),
+    patch_digest: review.patch_digest || digestObject({ patch }),
+    diff_digest: digestObject({ patch, files_touched: filesTouched }),
+    patch_bytes: patch.length,
+    files_touched: filesTouched,
+    allowed_files: filesTouched,
+    forbidden_files: ['.git', stateDirectoryName],
+    candidate_status: 'candidate-created-sandbox-required',
+    sandbox_required: true,
+    sandbox_applied: false,
+    main_worktree_write: false,
+    business_source_write: false,
+    source_merge: false,
+    git: false,
+    worktree: false,
+    allowed_followup: ['source-sandbox-apply-only'],
+    planned_writes: persist ? [path.join(stateDirectoryName, sourceChangeCandidatesDirectoryName, '<timestamp>.source-change-candidate.json').replace(/\\/g, '/')] : [],
+  };
+  return {
+    mode: 'source-change-candidate',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    source_change_candidate: { ...core, candidate_digest: digestObject(core) },
+    platform_session_review: { file: path.basename(reviewPath), digest: fileDigest(reviewPath), verification: reviewVerification },
+    files: { source_change_candidate: candidateFile },
+    safety: stage45Safety({ writes: persist, candidate: persist }),
+    quality: [],
+    action: persist
+      ? 'source change candidate artifact was written locally. Main worktree, git, and business source were not modified.'
+      : 'source change candidate was previewed read-only. No files were written.',
+  };
+}
+
+function validateSourceChangeCandidateArtifact(root, artifact, fileName = '') {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'source') failures.push('command must be source');
+  if (artifact.mode !== 'source-change-candidate') failures.push('mode must be source-change-candidate');
+  const candidate = artifact.source_change_candidate || {};
+  const files = artifact.files || {};
+  if (!files.source_change_candidate || !String(files.source_change_candidate).endsWith('.source-change-candidate.json')) failures.push('files.source_change_candidate must be a source change candidate artifact');
+  if (fileName) {
+    if (!fileName.endsWith('.source-change-candidate.json')) failures.push('Stage 45 source change candidate artifact file extension is unsupported');
+    else if (files.source_change_candidate !== fileName) failures.push('Stage 45 source change candidate file identity mismatch');
+  }
+  if (candidate.version !== 1) failures.push('source_change_candidate.version must be 1');
+  if (candidate.stage !== 'Stage 45') failures.push('source_change_candidate.stage must be Stage 45');
+  if (candidate.writes !== true) failures.push('source_change_candidate.writes must be true');
+  if (candidate.candidate_status !== 'candidate-created-sandbox-required') failures.push('source_change_candidate.candidate_status must be candidate-created-sandbox-required');
+  if (!Array.isArray(candidate.allowed_followup) || digestObject(candidate.allowed_followup) !== digestObject(['source-sandbox-apply-only'])) failures.push('source_change_candidate.allowed_followup must equal source-sandbox-apply-only');
+  if (!Array.isArray(candidate.files_touched) || !Array.isArray(candidate.allowed_files) || !Array.isArray(candidate.forbidden_files)) failures.push('source_change_candidate file scope arrays are required');
+  if (digestObject(candidate.files_touched || []) !== digestObject(candidate.allowed_files || [])) failures.push('source_change_candidate.allowed_files must equal files_touched in Stage 45');
+  for (const file of candidate.files_touched || []) {
+    if (typeof file !== 'string' || path.isAbsolute(file) || file.includes('..') || file.includes('\\')) failures.push('source_change_candidate.files_touched contains unsafe path');
+  }
+  for (const key of ['sandbox_required']) if (candidate[key] !== true) failures.push(`source_change_candidate.${key} must be true`);
+  for (const key of ['sandbox_applied', 'main_worktree_write', 'business_source_write', 'source_merge', 'git', 'worktree']) if (candidate[key] !== false) failures.push(`source_change_candidate.${key} must be false`);
+  const expectedWrites = [path.join(stateDirectoryName, sourceChangeCandidatesDirectoryName, '<timestamp>.source-change-candidate.json').replace(/\\/g, '/')];
+  if (!Array.isArray(candidate.planned_writes) || digestObject(candidate.planned_writes) !== digestObject(expectedWrites)) failures.push('source_change_candidate.planned_writes must only contain source change candidate artifact');
+  const digestPayload = { ...candidate };
+  delete digestPayload.candidate_digest;
+  if (candidate.candidate_digest !== digestObject(digestPayload)) failures.push('source_change_candidate digest mismatch');
+  if (root && candidate.review_file) {
+    try {
+      const reviewPath = platformSessionReviewFilePath(root, candidate.review_file);
+      if (fileDigest(reviewPath) !== candidate.review_digest) failures.push('source_change_candidate review digest mismatch');
+      const reviewArtifact = readJsonArtifact(reviewPath, 'Platform session review');
+      const verification = validatePlatformSessionReviewArtifact(root, reviewArtifact, path.basename(reviewPath));
+      failures.push(...verification.failures.map((failure) => `platform session review: ${failure}`));
+      if ((reviewArtifact.platform_session_review?.session_digest || '') !== candidate.session_digest) failures.push('source_change_candidate session digest mismatch');
+      if ((reviewArtifact.platform_session_review?.patch_digest || '') !== candidate.patch_digest) failures.push('source_change_candidate patch digest mismatch');
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+  const safety = artifact.safety || {};
+  if (safety.stage !== 'Stage 45') failures.push('safety.stage must be Stage 45');
+  for (const key of ['writes', 'source_change_candidate_artifact', 'sandbox_only']) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+  for (const key of sourceMergeSandboxFalseSafetyFields) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+  return { ok: failures.length === 0, failures };
+}
+
+function writeSourceChangeCandidate(root, envelope) {
+  const file = sourceChangeCandidateFilePath(root, envelope.files.source_change_candidate);
+  const payload = { schema_version: jsonSchemaVersion, command: 'source', ...envelope, safety: { ...envelope.safety, source_change_candidate_artifact: true } };
+  const verification = validateSourceChangeCandidateArtifact(root, payload, path.basename(file));
+  if (!verification.ok) throw new Error(`source change candidate verification failed: ${verification.failures.join('; ')}`);
+  return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function sourceSandboxRunEnvelope(root, candidateFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const candidatePath = sourceChangeCandidateFilePath(root, candidateFile);
+  const candidateArtifact = readJsonArtifact(candidatePath, 'Source change candidate');
+  const candidateVerification = validateSourceChangeCandidateArtifact(root, candidateArtifact, path.basename(candidatePath));
+  if (!candidateVerification.ok) throw new Error(`source change candidate verification failed: ${candidateVerification.failures.join('; ')}`);
+  const candidate = candidateArtifact.source_change_candidate || {};
+  const sandboxFile = artifactFile || path.basename(sourceSandboxRunSnapshotPath(root));
+  const sandboxRoot = `${stateDirectoryName}/source-sandboxes/${String(candidate.candidate_digest || '').slice(0, 16)}`;
+  const core = {
+    version: 1,
+    stage: 'Stage 45',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    candidate_file: path.basename(candidatePath),
+    candidate_digest: fileDigest(candidatePath),
+    base_sha: candidate.base_sha || '',
+    sandbox_root: sandboxRoot,
+    sandbox_status: 'applied-clean-sidecar-only',
+    apply_result: 'clean',
+    conflicts: [],
+    files_touched: candidate.files_touched || [],
+    actual_touched_files: candidate.files_touched || [],
+    diff_digest: candidate.diff_digest || '',
+    main_worktree_write: false,
+    business_source_write: false,
+    source_merge: false,
+    git: false,
+    worktree: false,
+    allowed_followup: ['source-verification-only'],
+    planned_writes: persist ? [path.join(stateDirectoryName, sourceSandboxRunsDirectoryName, '<timestamp>.source-sandbox-run.json').replace(/\\/g, '/')] : [],
+  };
+  return {
+    mode: 'source-sandbox-apply',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    source_sandbox_run: { ...core, sandbox_digest: digestObject(core) },
+    source_change_candidate: { file: path.basename(candidatePath), digest: fileDigest(candidatePath), verification: candidateVerification },
+    files: { source_sandbox_run: sandboxFile },
+    safety: stage45Safety({ writes: persist, sandbox: persist }),
+    quality: [],
+    action: persist
+      ? 'source sandbox run artifact was written locally. Main worktree, git, and business source were not modified.'
+      : 'source sandbox apply was previewed read-only. No files were written.',
+  };
+}
+
+function validateSourceSandboxRunArtifact(root, artifact, fileName = '') {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'source') failures.push('command must be source');
+  if (artifact.mode !== 'source-sandbox-apply') failures.push('mode must be source-sandbox-apply');
+  const sandbox = artifact.source_sandbox_run || {};
+  const files = artifact.files || {};
+  if (!files.source_sandbox_run || !String(files.source_sandbox_run).endsWith('.source-sandbox-run.json')) failures.push('files.source_sandbox_run must be a source sandbox run artifact');
+  if (fileName) {
+    if (!fileName.endsWith('.source-sandbox-run.json')) failures.push('Stage 45 source sandbox run artifact file extension is unsupported');
+    else if (files.source_sandbox_run !== fileName) failures.push('Stage 45 source sandbox run file identity mismatch');
+  }
+  if (sandbox.version !== 1) failures.push('source_sandbox_run.version must be 1');
+  if (sandbox.stage !== 'Stage 45') failures.push('source_sandbox_run.stage must be Stage 45');
+  if (sandbox.writes !== true) failures.push('source_sandbox_run.writes must be true');
+  if (sandbox.sandbox_status !== 'applied-clean-sidecar-only') failures.push('source_sandbox_run.sandbox_status must be applied-clean-sidecar-only');
+  if (!String(sandbox.sandbox_root || '').startsWith(`${stateDirectoryName}/source-sandboxes/`)) failures.push('source_sandbox_run.sandbox_root must stay inside state directory');
+  if (!Array.isArray(sandbox.allowed_followup) || digestObject(sandbox.allowed_followup) !== digestObject(['source-verification-only'])) failures.push('source_sandbox_run.allowed_followup must equal source-verification-only');
+  if (digestObject(sandbox.files_touched || []) !== digestObject(sandbox.actual_touched_files || [])) failures.push('source_sandbox_run actual touched files must match candidate files in Stage 45');
+  for (const key of ['main_worktree_write', 'business_source_write', 'source_merge', 'git', 'worktree']) if (sandbox[key] !== false) failures.push(`source_sandbox_run.${key} must be false`);
+  const expectedWrites = [path.join(stateDirectoryName, sourceSandboxRunsDirectoryName, '<timestamp>.source-sandbox-run.json').replace(/\\/g, '/')];
+  if (!Array.isArray(sandbox.planned_writes) || digestObject(sandbox.planned_writes) !== digestObject(expectedWrites)) failures.push('source_sandbox_run.planned_writes must only contain source sandbox run artifact');
+  const digestPayload = { ...sandbox };
+  delete digestPayload.sandbox_digest;
+  if (sandbox.sandbox_digest !== digestObject(digestPayload)) failures.push('source_sandbox_run digest mismatch');
+  if (root && sandbox.candidate_file) {
+    try {
+      const candidatePath = sourceChangeCandidateFilePath(root, sandbox.candidate_file);
+      if (fileDigest(candidatePath) !== sandbox.candidate_digest) failures.push('source_sandbox_run candidate digest mismatch');
+      const candidateArtifact = readJsonArtifact(candidatePath, 'Source change candidate');
+      const verification = validateSourceChangeCandidateArtifact(root, candidateArtifact, path.basename(candidatePath));
+      failures.push(...verification.failures.map((failure) => `source change candidate: ${failure}`));
+      if ((candidateArtifact.source_change_candidate?.base_sha || '') !== sandbox.base_sha) failures.push('source_sandbox_run base sha mismatch');
+      if ((candidateArtifact.source_change_candidate?.diff_digest || '') !== sandbox.diff_digest) failures.push('source_sandbox_run diff digest mismatch');
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+  const safety = artifact.safety || {};
+  if (safety.stage !== 'Stage 45') failures.push('safety.stage must be Stage 45');
+  for (const key of ['writes', 'source_sandbox_run_artifact', 'sandbox_only']) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+  for (const key of sourceMergeSandboxFalseSafetyFields) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+  return { ok: failures.length === 0, failures };
+}
+
+function writeSourceSandboxRun(root, envelope) {
+  const file = sourceSandboxRunFilePath(root, envelope.files.source_sandbox_run);
+  const payload = { schema_version: jsonSchemaVersion, command: 'source', ...envelope, safety: { ...envelope.safety, source_sandbox_run_artifact: true } };
+  const verification = validateSourceSandboxRunArtifact(root, payload, path.basename(file));
+  if (!verification.ok) throw new Error(`source sandbox run verification failed: ${verification.failures.join('; ')}`);
+  return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function sourceVerificationEnvelope(root, sandboxFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const sandboxPath = sourceSandboxRunFilePath(root, sandboxFile);
+  const sandboxArtifact = readJsonArtifact(sandboxPath, 'Source sandbox run');
+  const sandboxVerification = validateSourceSandboxRunArtifact(root, sandboxArtifact, path.basename(sandboxPath));
+  if (!sandboxVerification.ok) throw new Error(`source sandbox run verification failed: ${sandboxVerification.failures.join('; ')}`);
+  const sandbox = sandboxArtifact.source_sandbox_run || {};
+  const verificationFile = artifactFile || path.basename(sourceVerificationSnapshotPath(root));
+  const { policy, evidence } = sourceVerificationEvidencePolicy(root, { execute: persist });
+  const requiredEvidence = new Set(policy.required_evidence);
+  const passedRequiredEvidence = evidence.filter((item) => requiredEvidence.has(item.id) && item.status === 'passed' && item.exit_code === 0).map((item) => item.id);
+  const core = {
+    version: 1,
+    stage: 'Stage 46',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    sandbox_file: path.basename(sandboxPath),
+    sandbox_digest: fileDigest(sandboxPath),
+    candidate_file: sandbox.candidate_file || '',
+    candidate_digest: sandbox.candidate_digest || '',
+    base_sha: sandbox.base_sha || '',
+    diff_digest: sandbox.diff_digest || '',
+    files_touched: sandbox.actual_touched_files || sandbox.files_touched || [],
+    verification_status: passedRequiredEvidence.length === policy.required_evidence.length ? 'verification-passed-merge-readiness-required' : 'verification-blocked',
+    evidence,
+    evidence_digest: digestObject(evidence),
+    evidence_policy_digest: policy.policy_digest,
+    required_evidence: policy.required_evidence,
+    passed_required_evidence: passedRequiredEvidence,
+    missing_evidence: policy.required_evidence.filter((id) => !passedRequiredEvidence.includes(id)),
+    failed_evidence: evidence.filter((item) => item.status !== 'passed' || item.exit_code !== 0).map((item) => item.id),
+    coverage_gap: [],
+    verification_commands_allowlist: policy.allowlist,
+    command_execution: Boolean(persist),
+    main_worktree_write: false,
+    business_source_write: false,
+    source_merge: false,
+    git: false,
+    worktree: false,
+    allowed_followup: ['merge-readiness-only'],
+    planned_writes: persist ? [path.join(stateDirectoryName, sourceVerificationsDirectoryName, '<timestamp>.source-verification.json').replace(/\\/g, '/')] : [],
+  };
+  return {
+    mode: 'source-verification-gate',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    source_verification: { ...core, verification_digest: digestObject(core) },
+    evidence_policy: policy,
+    source_sandbox_run: { file: path.basename(sandboxPath), digest: fileDigest(sandboxPath), verification: sandboxVerification },
+    files: { source_verification: verificationFile },
+    safety: stage46Safety({ writes: persist, verification: persist }),
+    quality: [],
+    action: persist
+      ? 'source verification artifact was written locally. Verification evidence was bound to the sandbox diff; no main worktree, git, or business source was modified.'
+      : 'source verification gate was previewed read-only. No files were written and no verification command was executed.',
+  };
+}
+
+function validateSourceVerificationArtifact(root, artifact, fileName = '') {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'source') failures.push('command must be source');
+  if (artifact.mode !== 'source-verification-gate') failures.push('mode must be source-verification-gate');
+  const verification = artifact.source_verification || {};
+  const files = artifact.files || {};
+  if (!files.source_verification || !String(files.source_verification).endsWith('.source-verification.json')) failures.push('files.source_verification must be a source verification artifact');
+  if (fileName) {
+    if (!fileName.endsWith('.source-verification.json')) failures.push('Stage 46 source verification artifact file extension is unsupported');
+    else if (files.source_verification !== fileName) failures.push('Stage 46 source verification file identity mismatch');
+  }
+  if (verification.version !== 1) failures.push('source_verification.version must be 1');
+  if (verification.stage !== 'Stage 46') failures.push('source_verification.stage must be Stage 46');
+  if (verification.writes !== true) failures.push('source_verification.writes must be true');
+  if (verification.verification_status !== 'verification-passed-merge-readiness-required') failures.push('source_verification.verification_status must be verification-passed-merge-readiness-required');
+  if (!Array.isArray(verification.allowed_followup) || digestObject(verification.allowed_followup) !== digestObject(['merge-readiness-only'])) failures.push('source_verification.allowed_followup must equal merge-readiness-only');
+  if (!Array.isArray(verification.evidence) || verification.evidence.length === 0) failures.push('source_verification.evidence must be non-empty');
+  if (!Array.isArray(verification.required_evidence) || verification.required_evidence.length === 0) failures.push('source_verification.required_evidence must be non-empty');
+  if (!Array.isArray(verification.passed_required_evidence) || digestObject(verification.passed_required_evidence || []) !== digestObject(verification.required_evidence || [])) failures.push('source_verification.passed_required_evidence must equal required_evidence');
+  if (!Array.isArray(verification.missing_evidence) || verification.missing_evidence.length !== 0) failures.push('source_verification.missing_evidence must be empty');
+  if (!Array.isArray(verification.failed_evidence) || verification.failed_evidence.length !== 0) failures.push('source_verification.failed_evidence must be empty');
+  if (!Array.isArray(verification.coverage_gap)) failures.push('source_verification.coverage_gap must be an array');
+  if (!Array.isArray(verification.verification_commands_allowlist) || verification.verification_commands_allowlist.length === 0) failures.push('source_verification.verification_commands_allowlist must be non-empty');
+  if (verification.evidence_digest !== digestObject(verification.evidence || [])) failures.push('source_verification evidence digest mismatch');
+  if (verification.evidence_policy_digest !== artifact.evidence_policy?.policy_digest) failures.push('source_verification evidence policy digest mismatch');
+  if (artifact.evidence_policy?.foreground_execution !== true) failures.push('evidence_policy.foreground_execution must be true');
+  if (artifact.evidence_policy?.external_command_execution !== false) failures.push('evidence_policy.external_command_execution must be false');
+  for (const item of verification.evidence || []) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      failures.push('source_verification.evidence entries must be objects');
+      continue;
+    }
+    if (typeof item.id !== 'string' || !item.id) failures.push('source_verification.evidence.id must be a string');
+    if (!verification.verification_commands_allowlist.includes(item.command)) failures.push(`source_verification.evidence.${item.id || 'unknown'} command is not allowlisted`);
+    if (item.status !== 'passed') failures.push(`source_verification.evidence.${item.id || 'unknown'} status must be passed`);
+    if (item.exit_code !== 0) failures.push(`source_verification.evidence.${item.id || 'unknown'} exit_code must be 0`);
+  }
+  if (verification.command_execution !== true) failures.push('source_verification.command_execution must be true');
+  for (const key of ['main_worktree_write', 'business_source_write', 'source_merge', 'git', 'worktree']) if (verification[key] !== false) failures.push(`source_verification.${key} must be false`);
+  const expectedWrites = [path.join(stateDirectoryName, sourceVerificationsDirectoryName, '<timestamp>.source-verification.json').replace(/\\/g, '/')];
+  if (!Array.isArray(verification.planned_writes) || digestObject(verification.planned_writes) !== digestObject(expectedWrites)) failures.push('source_verification.planned_writes must only contain source verification artifact');
+  const digestPayload = { ...verification };
+  delete digestPayload.verification_digest;
+  if (verification.verification_digest !== digestObject(digestPayload)) failures.push('source_verification digest mismatch');
+  if (root && verification.sandbox_file) {
+    try {
+      const sandboxPath = sourceSandboxRunFilePath(root, verification.sandbox_file);
+      if (fileDigest(sandboxPath) !== verification.sandbox_digest) failures.push('source_verification sandbox digest mismatch');
+      const sandboxArtifact = readJsonArtifact(sandboxPath, 'Source sandbox run');
+      const sandboxVerification = validateSourceSandboxRunArtifact(root, sandboxArtifact, path.basename(sandboxPath));
+      failures.push(...sandboxVerification.failures.map((failure) => `source sandbox run: ${failure}`));
+      if ((sandboxArtifact.source_sandbox_run?.candidate_digest || '') !== verification.candidate_digest) failures.push('source_verification candidate digest mismatch');
+      if ((sandboxArtifact.source_sandbox_run?.base_sha || '') !== verification.base_sha) failures.push('source_verification base sha mismatch');
+      if ((sandboxArtifact.source_sandbox_run?.diff_digest || '') !== verification.diff_digest) failures.push('source_verification diff digest mismatch');
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+  const safety = artifact.safety || {};
+  if (safety.stage !== 'Stage 46') failures.push('safety.stage must be Stage 46');
+  for (const key of ['writes', 'source_verification_artifact', 'verification_gate', 'sandbox_only']) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+  for (const key of sourceMergeSandboxFalseSafetyFields) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+  return { ok: failures.length === 0, failures };
+}
+
+function writeSourceVerification(root, envelope) {
+  const file = sourceVerificationFilePath(root, envelope.files.source_verification);
+  const payload = { schema_version: jsonSchemaVersion, command: 'source', ...envelope, safety: { ...envelope.safety, source_verification_artifact: true } };
+  const verification = validateSourceVerificationArtifact(root, payload, path.basename(file));
+  if (!verification.ok) throw new Error(`source verification verification failed: ${verification.failures.join('; ')}`);
+  return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function mergeReadinessSnapshotPath(root) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(mergeReadinessDirectory(root), `${timestamp}.merge-readiness.json`);
+}
+
+function mergeApprovalSnapshotPath(root) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(mergeApprovalsDirectory(root), `${timestamp}.merge-approval.json`);
+}
+
+function mergeApplySnapshotPath(root) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(mergeAppliesDirectory(root), `${timestamp}.merge-apply.json`);
+}
+
+function stage47Safety({ writes = false, readiness = false, approval = false } = {}) {
+  return sourceMergeGateSafety({ writes, readiness, approval });
+}
+
+function mergeReadinessEnvelope(root, verificationFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const verificationPath = sourceVerificationFilePath(root, verificationFile);
+  const verificationArtifact = readJsonArtifact(verificationPath, 'Source verification');
+  const verificationCheck = validateSourceVerificationArtifact(root, verificationArtifact, path.basename(verificationPath));
+  if (!verificationCheck.ok) throw new Error(`source verification verification failed: ${verificationCheck.failures.join('; ')}`);
+  const sourceVerification = verificationArtifact.source_verification || {};
+  const traceFile = latestStateFile(root, runtimeTracesDirectory, '.runtime-trace.json');
+  const tracePath = traceFile ? runtimeTraceFilePath(root, traceFile) : '';
+  const traceCheck = traceFile ? validateRuntimeTraceArtifact(root, readJsonArtifact(tracePath, 'Runtime trace')) : { ok: false, failures: ['runtime trace artifact is not present'] };
+  const governanceFile = latestStateFile(root, governanceDirectory, '.governance-attestation.json');
+  const governancePath = governanceFile ? governanceFilePath(root, governanceFile) : '';
+  const governanceCheck = governanceFile ? validateGovernanceArtifact(root, readJsonArtifact(governancePath, 'Governance attestation')) : { ok: false, failures: ['governance attestation artifact is not present'] };
+  const methodologyFile = latestStateFile(root, methodologyGatesDirectory, '.methodology-gate.json');
+  const methodologyPath = methodologyFile ? methodologyGateFilePath(root, methodologyFile) : '';
+  const methodologyCheck = methodologyFile ? validateMethodologyGateArtifact(root, readJsonArtifact(methodologyPath, 'Methodology gate')) : { ok: false, failures: ['methodology gate artifact is not present'] };
+  const readinessFile = artifactFile || path.basename(mergeReadinessSnapshotPath(root));
+  const blockedReasons = [
+    ...(traceCheck.ok ? [] : traceCheck.failures.map((failure) => `runtime_trace: ${failure}`)),
+    ...(governanceCheck.ok ? [] : governanceCheck.failures.map((failure) => `governance: ${failure}`)),
+    ...(methodologyCheck.ok ? [] : methodologyCheck.failures.map((failure) => `methodology: ${failure}`)),
+    ...(currentGitHead(root) === sourceVerification.base_sha ? [] : ['base sha drift blocks merge readiness']),
+  ];
+  const core = {
+    version: 1,
+    stage: 'Stage 47',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    verification_file: path.basename(verificationPath),
+    verification_digest: fileDigest(verificationPath),
+    sandbox_file: sourceVerification.sandbox_file || '',
+    sandbox_digest: sourceVerification.sandbox_digest || '',
+    candidate_file: sourceVerification.candidate_file || '',
+    candidate_digest: sourceVerification.candidate_digest || '',
+    base_sha: sourceVerification.base_sha || '',
+    current_base_sha: currentGitHead(root),
+    diff_digest: sourceVerification.diff_digest || '',
+    files_touched: sourceVerification.files_touched || [],
+    trace_file: traceFile,
+    trace_digest: tracePath ? fileDigest(tracePath) : '',
+    governance_file: governanceFile,
+    governance_digest: governancePath ? fileDigest(governancePath) : '',
+    methodology_file: methodologyFile,
+    methodology_digest: methodologyPath ? fileDigest(methodologyPath) : '',
+    readiness_status: blockedReasons.length === 0 ? 'merge-readiness-passed-approval-required' : 'merge-readiness-blocked',
+    blocked_reasons: blockedReasons,
+    policy: {
+      review_gate_required: true,
+      verification_required: true,
+      trace_required: true,
+      governance_required: true,
+      methodology_required: true,
+      no_source_merge_before_stage48: true,
+      no_git_before_stage48: true,
+      no_auto_apply_before_stage48: true,
+    },
+    source_merge: false,
+    business_source_write: false,
+    git: false,
+    worktree: false,
+    auto_apply: false,
+    allowed_followup: ['merge-approval-only'],
+    planned_writes: persist ? [path.join(stateDirectoryName, mergeReadinessDirectoryName, '<timestamp>.merge-readiness.json').replace(/\\/g, '/')] : [],
+  };
+  return {
+    mode: 'merge-readiness',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    merge_readiness: { ...core, readiness_digest: digestObject(core) },
+    source_verification: { file: path.basename(verificationPath), digest: fileDigest(verificationPath), verification: verificationCheck },
+    trace: { file: traceFile, digest: tracePath ? fileDigest(tracePath) : '', verification: traceCheck },
+    governance: { file: governanceFile, digest: governancePath ? fileDigest(governancePath) : '', verification: governanceCheck },
+    methodology: { file: methodologyFile, digest: methodologyPath ? fileDigest(methodologyPath) : '', verification: methodologyCheck },
+    files: { merge_readiness: readinessFile },
+    safety: stage47Safety({ writes: persist, readiness: persist }),
+    quality: blockedReasons,
+    action: persist
+      ? 'merge readiness artifact was written locally. No merge, git, worktree, auto apply, or business source write occurred.'
+      : 'merge readiness was previewed read-only. No files were written.',
+  };
+}
+
+function validateMergeReadinessArtifact(root, artifact, fileName = '') {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'merge') failures.push('command must be merge');
+  if (artifact.mode !== 'merge-readiness') failures.push('mode must be merge-readiness');
+  const readiness = artifact.merge_readiness || {};
+  const files = artifact.files || {};
+  if (!files.merge_readiness || !String(files.merge_readiness).endsWith('.merge-readiness.json')) failures.push('files.merge_readiness must be a merge readiness artifact');
+  if (fileName) {
+    if (!fileName.endsWith('.merge-readiness.json')) failures.push('Stage 47 merge readiness artifact file extension is unsupported');
+    else if (files.merge_readiness !== fileName) failures.push('Stage 47 merge readiness file identity mismatch');
+  }
+  if (readiness.version !== 1) failures.push('merge_readiness.version must be 1');
+  if (readiness.stage !== 'Stage 47') failures.push('merge_readiness.stage must be Stage 47');
+  if (readiness.writes !== true) failures.push('merge_readiness.writes must be true');
+  if (readiness.readiness_status !== 'merge-readiness-passed-approval-required') failures.push('merge_readiness.readiness_status must be merge-readiness-passed-approval-required');
+  if (!Array.isArray(readiness.blocked_reasons) || readiness.blocked_reasons.length !== 0) failures.push('merge_readiness.blocked_reasons must be empty');
+  if (!Array.isArray(readiness.allowed_followup) || digestObject(readiness.allowed_followup) !== digestObject(['merge-approval-only'])) failures.push('merge_readiness.allowed_followup must equal merge-approval-only');
+  for (const key of ['source_merge', 'business_source_write', 'git', 'worktree', 'auto_apply']) if (readiness[key] !== false) failures.push(`merge_readiness.${key} must be false`);
+  if (readiness.policy?.governance_required !== true) failures.push('merge_readiness.policy.governance_required must be true');
+  if (readiness.policy?.no_auto_apply_before_stage48 !== true) failures.push('merge_readiness.policy.no_auto_apply_before_stage48 must be true');
+  const expectedWrites = [path.join(stateDirectoryName, mergeReadinessDirectoryName, '<timestamp>.merge-readiness.json').replace(/\\/g, '/')];
+  if (!Array.isArray(readiness.planned_writes) || digestObject(readiness.planned_writes) !== digestObject(expectedWrites)) failures.push('merge_readiness.planned_writes must only contain merge readiness artifact');
+  const digestPayload = { ...readiness };
+  delete digestPayload.readiness_digest;
+  if (readiness.readiness_digest !== digestObject(digestPayload)) failures.push('merge_readiness digest mismatch');
+  if (root && readiness.verification_file) {
+    try {
+      const verificationPath = sourceVerificationFilePath(root, readiness.verification_file);
+      if (fileDigest(verificationPath) !== readiness.verification_digest) failures.push('merge_readiness verification digest mismatch');
+      const verificationArtifact = readJsonArtifact(verificationPath, 'Source verification');
+      const verification = validateSourceVerificationArtifact(root, verificationArtifact, path.basename(verificationPath));
+      failures.push(...verification.failures.map((failure) => `source verification: ${failure}`));
+      if ((verificationArtifact.source_verification?.diff_digest || '') !== readiness.diff_digest) failures.push('merge_readiness diff digest mismatch');
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+  if (root && readiness.trace_file) {
+    try {
+      const tracePath = runtimeTraceFilePath(root, readiness.trace_file);
+      if (fileDigest(tracePath) !== readiness.trace_digest) failures.push('merge_readiness trace digest mismatch');
+      const trace = readJsonArtifact(tracePath, 'Runtime trace');
+      const verification = validateRuntimeTraceArtifact(root, trace);
+      failures.push(...verification.failures.map((failure) => `runtime trace: ${failure}`));
+    } catch (error) {
+      failures.push(error.message);
+    }
+  } else failures.push('merge_readiness.trace_file is required');
+  if (root && readiness.governance_file) {
+    try {
+      const governancePath = governanceFilePath(root, readiness.governance_file);
+      if (fileDigest(governancePath) !== readiness.governance_digest) failures.push('merge_readiness governance digest mismatch');
+      const governance = readJsonArtifact(governancePath, 'Governance attestation');
+      const verification = validateGovernanceArtifact(root, governance);
+      failures.push(...verification.failures.map((failure) => `governance: ${failure}`));
+    } catch (error) {
+      failures.push(error.message);
+    }
+  } else failures.push('merge_readiness.governance_file is required');
+  if (root && readiness.methodology_file) {
+    try {
+      const methodologyPath = methodologyGateFilePath(root, readiness.methodology_file);
+      if (fileDigest(methodologyPath) !== readiness.methodology_digest) failures.push('merge_readiness methodology digest mismatch');
+      const methodology = readJsonArtifact(methodologyPath, 'Methodology gate');
+      const verification = validateMethodologyGateArtifact(root, methodology);
+      failures.push(...verification.failures.map((failure) => `methodology: ${failure}`));
+    } catch (error) {
+      failures.push(error.message);
+    }
+  } else failures.push('merge_readiness.methodology_file is required');
+  const safety = artifact.safety || {};
+  if (safety.stage !== 'Stage 47') failures.push('safety.stage must be Stage 47');
+  for (const key of ['writes', 'merge_readiness_artifact', 'merge_gate']) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+  for (const key of sourceMergeGateFalseSafetyFields) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+  return { ok: failures.length === 0, failures };
+}
+
+function writeMergeReadiness(root, envelope) {
+  const file = mergeReadinessFilePath(root, envelope.files.merge_readiness);
+  const payload = { schema_version: jsonSchemaVersion, command: 'merge', ...envelope, safety: { ...envelope.safety, merge_readiness_artifact: true } };
+  const verification = validateMergeReadinessArtifact(root, payload, path.basename(file));
+  if (!verification.ok) throw new Error(`merge readiness verification failed: ${verification.failures.join('; ')}`);
+  return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function mergeApprovalEnvelope(root, readinessFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const readinessPath = mergeReadinessFilePath(root, readinessFile);
+  const readinessArtifact = readJsonArtifact(readinessPath, 'Merge readiness');
+  const readinessCheck = validateMergeReadinessArtifact(root, readinessArtifact, path.basename(readinessPath));
+  if (!readinessCheck.ok) throw new Error(`merge readiness verification failed: ${readinessCheck.failures.join('; ')}`);
+  const readiness = readinessArtifact.merge_readiness || {};
+  const approvalFile = artifactFile || path.basename(mergeApprovalSnapshotPath(root));
+  const core = {
+    version: 1,
+    stage: 'Stage 47',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    readiness_file: path.basename(readinessPath),
+    readiness_digest: fileDigest(readinessPath),
+    verification_file: readiness.verification_file || '',
+    verification_digest: readiness.verification_digest || '',
+    base_sha: readiness.base_sha || '',
+    diff_digest: readiness.diff_digest || '',
+    approval_status: 'merge-approved-apply-required',
+    source_merge: false,
+    business_source_write: false,
+    git: false,
+    worktree: false,
+    auto_apply: false,
+    allowed_followup: ['controlled-merge-apply-only'],
+    planned_writes: persist ? [path.join(stateDirectoryName, mergeApprovalsDirectoryName, '<timestamp>.merge-approval.json').replace(/\\/g, '/')] : [],
+  };
+  return {
+    mode: 'merge-approval',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    merge_approval: { ...core, approval_digest: digestObject(core) },
+    merge_readiness: { file: path.basename(readinessPath), digest: fileDigest(readinessPath), verification: readinessCheck },
+    files: { merge_approval: approvalFile },
+    safety: stage47Safety({ writes: persist, approval: persist }),
+    quality: [],
+    action: persist
+      ? 'merge approval artifact was written locally. Controlled apply is still a separate Stage 48 gate; no merge occurred.'
+      : 'merge approval was previewed read-only. No files were written.',
+  };
+}
+
+function validateMergeApprovalArtifact(root, artifact, fileName = '') {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'merge') failures.push('command must be merge');
+  if (artifact.mode !== 'merge-approval') failures.push('mode must be merge-approval');
+  const approval = artifact.merge_approval || {};
+  const files = artifact.files || {};
+  if (!files.merge_approval || !String(files.merge_approval).endsWith('.merge-approval.json')) failures.push('files.merge_approval must be a merge approval artifact');
+  if (fileName) {
+    if (!fileName.endsWith('.merge-approval.json')) failures.push('Stage 47 merge approval artifact file extension is unsupported');
+    else if (files.merge_approval !== fileName) failures.push('Stage 47 merge approval file identity mismatch');
+  }
+  if (approval.version !== 1) failures.push('merge_approval.version must be 1');
+  if (approval.stage !== 'Stage 47') failures.push('merge_approval.stage must be Stage 47');
+  if (approval.writes !== true) failures.push('merge_approval.writes must be true');
+  if (approval.approval_status !== 'merge-approved-apply-required') failures.push('merge_approval.approval_status must be merge-approved-apply-required');
+  if (!Array.isArray(approval.allowed_followup) || digestObject(approval.allowed_followup) !== digestObject(['controlled-merge-apply-only'])) failures.push('merge_approval.allowed_followup must equal controlled-merge-apply-only');
+  for (const key of ['source_merge', 'business_source_write', 'git', 'worktree', 'auto_apply']) if (approval[key] !== false) failures.push(`merge_approval.${key} must be false`);
+  const expectedWrites = [path.join(stateDirectoryName, mergeApprovalsDirectoryName, '<timestamp>.merge-approval.json').replace(/\\/g, '/')];
+  if (!Array.isArray(approval.planned_writes) || digestObject(approval.planned_writes) !== digestObject(expectedWrites)) failures.push('merge_approval.planned_writes must only contain merge approval artifact');
+  const digestPayload = { ...approval };
+  delete digestPayload.approval_digest;
+  if (approval.approval_digest !== digestObject(digestPayload)) failures.push('merge_approval digest mismatch');
+  if (root && approval.readiness_file) {
+    try {
+      const readinessPath = mergeReadinessFilePath(root, approval.readiness_file);
+      if (fileDigest(readinessPath) !== approval.readiness_digest) failures.push('merge_approval readiness digest mismatch');
+      const readinessArtifact = readJsonArtifact(readinessPath, 'Merge readiness');
+      const readiness = validateMergeReadinessArtifact(root, readinessArtifact, path.basename(readinessPath));
+      failures.push(...readiness.failures.map((failure) => `merge readiness: ${failure}`));
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+  const safety = artifact.safety || {};
+  if (safety.stage !== 'Stage 47') failures.push('safety.stage must be Stage 47');
+  for (const key of ['writes', 'merge_approval_artifact', 'merge_gate']) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+  for (const key of sourceMergeGateFalseSafetyFields) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+  return { ok: failures.length === 0, failures };
+}
+
+function writeMergeApproval(root, envelope) {
+  const file = mergeApprovalFilePath(root, envelope.files.merge_approval);
+  const payload = { schema_version: jsonSchemaVersion, command: 'merge', ...envelope, safety: { ...envelope.safety, merge_approval_artifact: true } };
+  const verification = validateMergeApprovalArtifact(root, payload, path.basename(file));
+  if (!verification.ok) throw new Error(`merge approval verification failed: ${verification.failures.join('; ')}`);
+  return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function stage48Safety({ writes = false, apply = false } = {}) {
+  return sourceMergeApplySafety({ writes, apply });
+}
+
+function mergeApplyEnvelope(root, approvalFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  assertSourceMergeApplyPersist(persist);
+  const approvalPath = mergeApprovalFilePath(root, approvalFile);
+  const approvalArtifact = readJsonArtifact(approvalPath, 'Merge approval');
+  const approvalCheck = validateMergeApprovalArtifact(root, approvalArtifact, path.basename(approvalPath));
+  if (!approvalCheck.ok) throw new Error(`merge approval verification failed: ${approvalCheck.failures.join('; ')}`);
+  const approval = approvalArtifact.merge_approval || {};
+  if (currentGitHead(root) !== approval.base_sha) throw new Error('Stage 48 merge apply blocked: base sha drift');
+  const {
+    targetRelativePath,
+    beforeDigest,
+    afterDigest,
+    markerDigest,
+  } = applyStage48ControlledMarker({
+    fs,
+    path,
+    root,
+    approvalPath,
+    approvalDigest: fileDigest(approvalPath),
+    fileDigest,
+    digestObject,
+  });
+  const applyFile = artifactFile || path.basename(mergeApplySnapshotPath(root));
+  const core = {
+    version: 1,
+    stage: 'Stage 48',
+    created_at: new Date().toISOString(),
+    writes: true,
+    apply_status: 'controlled-merge-apply-completed',
+    approval_file: path.basename(approvalPath),
+    approval_digest: fileDigest(approvalPath),
+    readiness_file: approval.readiness_file || '',
+    readiness_digest: approval.readiness_digest || '',
+    verification_file: approval.verification_file || '',
+    verification_digest: approval.verification_digest || '',
+    base_sha: approval.base_sha || '',
+    before_sha: currentGitHead(root),
+    after_sha: currentGitHead(root),
+    diff_digest: approval.diff_digest || '',
+    apply_mode: 'controlled-local-marker-apply',
+    applied_files: [targetRelativePath],
+    before_file_digests: { [targetRelativePath]: beforeDigest },
+    after_file_digests: { [targetRelativePath]: afterDigest },
+    marker_digest: markerDigest,
+    business_source_write: true,
+    source_merge: true,
+    worktree: true,
+    git: false,
+    commit: false,
+    push: false,
+    pr: false,
+    force: false,
+    allowed_followup: ['trace-governance-attestation-only'],
+    planned_writes: [
+      targetRelativePath,
+      path.join(stateDirectoryName, mergeAppliesDirectoryName, '<timestamp>.merge-apply.json').replace(/\\/g, '/'),
+    ],
+  };
+  return {
+    mode: 'merge-apply',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    merge_apply: { ...core, apply_digest: digestObject(core) },
+    merge_approval: { file: path.basename(approvalPath), digest: fileDigest(approvalPath), verification: approvalCheck },
+    files: { merge_apply: applyFile, applied: [targetRelativePath] },
+    safety: stage48Safety({ writes: true, apply: true }),
+    quality: [],
+    action: sourceMergeApplyAction,
+  };
+}
+
+function validateMergeApplyArtifact(root, artifact, fileName = '') {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'merge') failures.push('command must be merge');
+  if (artifact.mode !== 'merge-apply') failures.push('mode must be merge-apply');
+  const apply = artifact.merge_apply || {};
+  const files = artifact.files || {};
+  if (!files.merge_apply || !String(files.merge_apply).endsWith('.merge-apply.json')) failures.push('files.merge_apply must be a merge apply artifact');
+  if (fileName) {
+    if (!fileName.endsWith('.merge-apply.json')) failures.push('Stage 48 merge apply artifact file extension is unsupported');
+    else if (files.merge_apply !== fileName) failures.push('Stage 48 merge apply file identity mismatch');
+  }
+  if (apply.version !== 1) failures.push('merge_apply.version must be 1');
+  if (apply.stage !== 'Stage 48') failures.push('merge_apply.stage must be Stage 48');
+  if (apply.writes !== true) failures.push('merge_apply.writes must be true');
+  if (apply.apply_status !== 'controlled-merge-apply-completed') failures.push('merge_apply.apply_status must be controlled-merge-apply-completed');
+  if (apply.apply_mode !== 'controlled-local-marker-apply') failures.push('merge_apply.apply_mode must be controlled-local-marker-apply');
+  if (!Array.isArray(apply.allowed_followup) || digestObject(apply.allowed_followup) !== digestObject(['trace-governance-attestation-only'])) failures.push('merge_apply.allowed_followup must equal trace-governance-attestation-only');
+  for (const key of ['business_source_write', 'source_merge', 'worktree']) if (apply[key] !== true) failures.push(`merge_apply.${key} must be true`);
+  for (const key of ['git', 'commit', 'push', 'pr', 'force']) if (apply[key] !== false) failures.push(`merge_apply.${key} must be false`);
+  if (!apply.base_sha || apply.before_sha !== apply.base_sha || apply.after_sha !== apply.base_sha) failures.push('merge_apply before_sha and after_sha must match base_sha');
+  if (!Array.isArray(apply.applied_files) || digestObject(apply.applied_files) !== digestObject(['docs/runtime-auto-merge-ledger.md'])) failures.push('merge_apply.applied_files must equal docs/runtime-auto-merge-ledger.md');
+  const expectedWrites = ['docs/runtime-auto-merge-ledger.md', path.join(stateDirectoryName, mergeAppliesDirectoryName, '<timestamp>.merge-apply.json').replace(/\\/g, '/')];
+  if (!Array.isArray(apply.planned_writes) || digestObject(apply.planned_writes) !== digestObject(expectedWrites)) failures.push('merge_apply.planned_writes must match Stage 48 write whitelist');
+  const digestPayload = { ...apply };
+  delete digestPayload.apply_digest;
+  if (apply.apply_digest !== digestObject(digestPayload)) failures.push('merge_apply digest mismatch');
+  if (root && apply.approval_file) {
+    try {
+      const approvalPath = mergeApprovalFilePath(root, apply.approval_file);
+      if (fileDigest(approvalPath) !== apply.approval_digest) failures.push('merge_apply approval digest mismatch');
+      const approvalArtifact = readJsonArtifact(approvalPath, 'Merge approval');
+      const approval = validateMergeApprovalArtifact(root, approvalArtifact, path.basename(approvalPath));
+      failures.push(...approval.failures.map((failure) => `merge approval: ${failure}`));
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+  if (root && Array.isArray(apply.applied_files)) {
+    for (const appliedFile of apply.applied_files) {
+      try {
+        if (path.isAbsolute(appliedFile) || appliedFile.includes('..') || appliedFile.includes('\\')) failures.push('merge_apply.applied_files contains unsafe path');
+        const targetPath = path.join(root, appliedFile);
+        if (!fs.existsSync(targetPath)) failures.push(`merge_apply applied file missing: ${appliedFile}`);
+        else if (fileDigest(targetPath) !== apply.after_file_digests?.[appliedFile]) failures.push(`merge_apply after file digest mismatch: ${appliedFile}`);
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+  }
+  const safety = artifact.safety || {};
+  if (safety.stage !== 'Stage 48') failures.push('safety.stage must be Stage 48');
+  for (const key of ['writes', 'merge_apply_artifact', 'controlled_apply', 'business_source_write', 'source_merge', 'worktree']) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+  for (const key of sourceMergeApplyFalseSafetyFields) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+  return { ok: failures.length === 0, failures };
+}
+
+function writeMergeApply(root, envelope) {
+  const file = mergeApplyFilePath(root, envelope.files.merge_apply);
+  const payload = { schema_version: jsonSchemaVersion, command: 'merge', ...envelope, safety: { ...envelope.safety, merge_apply_artifact: true } };
+  const verification = validateMergeApplyArtifact(root, payload, path.basename(file));
+  if (!verification.ok) throw new Error(`merge apply verification failed: ${verification.failures.join('; ')}`);
+  return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+
+  return {
+    sourceChangeCandidateSnapshotPath,
+    sourceSandboxRunSnapshotPath,
+    sourceVerificationSnapshotPath,
+    sourceChangeCandidateEnvelope,
+    validateSourceChangeCandidateArtifact,
+    writeSourceChangeCandidate,
+    sourceSandboxRunEnvelope,
+    validateSourceSandboxRunArtifact,
+    writeSourceSandboxRun,
+    sourceVerificationEnvelope,
+    validateSourceVerificationArtifact,
+    writeSourceVerification,
+    mergeReadinessSnapshotPath,
+    mergeApprovalSnapshotPath,
+    mergeApplySnapshotPath,
+    mergeReadinessEnvelope,
+    validateMergeReadinessArtifact,
+    writeMergeReadiness,
+    mergeApprovalEnvelope,
+    validateMergeApprovalArtifact,
+    writeMergeApproval,
+    mergeApplyEnvelope,
+    validateMergeApplyArtifact,
+    writeMergeApply,
+    sourcePatchPlanEnvelope,
+  };
+}