@juangcarmona/lighthouse-sdlc 0.17.1 → 0.18.0

package/src/epic-dispatch.mjs

@@ -0,0 +1,59 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readActionsJson } from './actions-artifact.mjs';
+import { issueComments, readDispatchReceipt } from './stage-dispatch.mjs';
+import { epicJournalKey } from './epic-github.mjs';
+import { authenticateEpicChild } from './epic-native.mjs';
+
+const positive = value => /^[1-9][0-9]*$/.test(String(value));
+export async function verifyEpicTriageOrigin(api, { repository, owner, child, parent, runId }, { readArtifact = readActionsJson, authenticate = authenticateEpicChild } = {}) {
+  if (![child, parent, runId].every(positive)) throw Error('Invalid epic triage origin');
+  const run = await api(`actions/runs/${runId}`), repo = await api('');
+  if (String(run.id) !== String(runId) || run.path !== '.github/workflows/lighthouse-sdlc-epic.yml' || run.event !== 'workflow_dispatch' || run.status !== 'completed' || run.conclusion !== 'success' || run.run_attempt !== 1 || run.actor?.login !== owner || run.triggering_actor?.login !== owner || run.repository?.full_name !== repository || run.head_branch !== repo.default_branch || run.head_sha !== (await api(`commits/${encodeURIComponent(repo.default_branch)}`)).sha) throw Error('Epic triage origin is not an authenticated current owner execution');
+  const journal = await readArtifact(api, repository, run.id, `lighthouse-epic-journal-${parent}-${run.run_attempt}`, 'journal.json');
+  if (journal?.schemaVersion !== 1 || journal.repository !== repository || journal.parent !== Number(parent) || journal.revision !== run.head_sha || String(journal.runId) !== String(run.id) || journal.attempt !== run.run_attempt || !journal.entries || typeof journal.entries !== 'object') throw Error('Epic triage journal is invalid');
+  const current = await authenticate({ api, repository, owner, child: Number(child), readArtifact });
+  if (current.parent !== Number(parent)) throw Error('Epic triage parent changed');
+  const matches = Object.values(journal.entries).filter(entry => entry?.receipt?.state === 'linked' && entry.receipt.correlation?.kind === 'child' && entry.receipt.correlation.parent === Number(parent) && entry.receipt.correlation.slice === current.slice && entry.receipt.correlation.planDigest === current.planDigest && entry.receipt.resource?.number === Number(child));
+  if (matches.length !== 1 || journal.entries[epicJournalKey(matches[0].receipt.correlation)] !== matches[0]) throw Error('Epic triage is not in the retained parent execution');
+  return { run, journal, current };
+}
+
+export async function dispatchEpicTriage(api, { repository, owner, runId }, { readArtifact = readActionsJson, authenticate = authenticateEpicChild } = {}) {
+  if (!positive(runId)) throw Error('Invalid epic execution');
+  const run = await api(`actions/runs/${runId}`), inventory = await api(`actions/runs/${runId}/artifacts?per_page=100`);
+  if (!Array.isArray(inventory.artifacts) || inventory.total_count !== inventory.artifacts.length || inventory.total_count > 100) throw Error('Epic artifact inventory is incomplete');
+  const names = inventory.artifacts.filter(item => !item.expired).map(item => item.name).filter(name => /^lighthouse-epic-journal-[1-9][0-9]*-1$/.test(name));
+  if (names.length !== 1) throw Error('Epic execution journal is missing or ambiguous');
+  const parent = Number(names[0].match(/^lighthouse-epic-journal-([1-9][0-9]*)-1$/)[1]);
+  const journal = await readArtifact(api, repository, runId, names[0], 'journal.json');
+  const entries = Object.values(journal?.entries ?? {}).filter(entry => entry?.receipt?.state === 'linked' && entry.receipt.correlation?.kind === 'child');
+  const sent = [];
+  for (const entry of entries) {
+    const child = entry.receipt.resource?.number;
+    const verified = await verifyEpicTriageOrigin(api, { repository, owner, child, parent, runId }, { readArtifact, authenticate });
+    const issue = await api(`issues/${child}`);
+    if (issue.state !== 'open' || issue.labels.some(label => ['future', 'human-working', 'agent-working', 'needs-info', 'waiting-review', 'triaged', 'ready'].includes(label.name))) continue;
+    const comments = await issueComments(api, child);
+    const prior = comments.filter(comment => comment.user?.login === 'github-actions[bot]' && comment.user.type === 'Bot' && comment.body?.includes('<!-- lighthouse-dispatch:')).map(comment => readDispatchReceipt(comment, repository, child));
+    if (prior.some(receipt => receipt.stage === 'triage')) continue;
+    await api('actions/workflows/lighthouse-sdlc-router.yml/dispatches', 'POST', { ref: verified.run.head_branch, inputs: { issue: String(child), stage: 'triage', workflow: 'stage', epic_parent: String(parent), epic_run: String(runId) } });
+    sent.push(child);
+  }
+  return { status: 'dispatched', parent, children: sent };
+}
+
+async function main() {
+  const env = process.env, repository = env.GITHUB_REPOSITORY, owner = env.GITHUB_REPOSITORY_OWNER;
+  const event = JSON.parse(await readFile(env.GITHUB_EVENT_PATH, 'utf8'));
+  if (env.GITHUB_EVENT_NAME !== 'workflow_run' || event.action !== 'completed' || !positive(event.workflow_run?.id)) throw Error('Epic triage requires a completed workflow event');
+  const api = async (path, method = 'GET', body, optional = false) => {
+    const response = await fetch(`https://api.github.com/repos/${repository}${path ? `/${path}` : ''}`, { method, headers: { authorization: `Bearer ${env.GH_TOKEN}`, accept: 'application/vnd.github+json', 'content-type': 'application/json' }, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(30000) });
+    if (optional && response.status === 404) return null;
+    if (!response.ok) throw Error(`GitHub ${method} ${path}: ${response.status}`);
+    return response.status === 204 ? null : response.json();
+  };
+  console.log(JSON.stringify(await dispatchEpicTriage(api, { repository, owner, runId: event.workflow_run.id })));
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/src/epic-github.mjs

@@ -0,0 +1,111 @@
+import { isDeepStrictEqual } from 'node:util';
+import { epicPlanDigest } from './epic.mjs';
+import { buildDecompositionPlan } from './decompose.mjs';
+
+const positive = value => Number.isSafeInteger(value) && value > 0;
+const prefix = '<!-- lighthouse-epic:';
+
+export function epicCorrelation({ repository, parent, slice, planDigest, base, dependencies, kind = 'child' }) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repository ?? '') || !positive(parent) || typeof slice !== 'string' || !slice.trim() || !/^[a-f0-9]{64}$/.test(planDigest ?? '') || base !== `lighthouse/epic-${parent}` || !Array.isArray(dependencies) || dependencies.some(id => typeof id !== 'string' || !id.trim()) || !['child', 'pull-request', 'aggregate'].includes(kind)) throw Error('Invalid epic correlation');
+  return { schemaVersion: 1, kind, repository, parent, slice, planDigest, base, dependencies: [...new Set(dependencies)].sort() };
+}
+
+export function epicMarker(correlation) {
+  const checked = epicCorrelation(correlation);
+  if (!isDeepStrictEqual(correlation, checked)) throw Error('Non-canonical epic correlation');
+  return `${prefix}${JSON.stringify(checked).replaceAll('<', '\\u003c').replaceAll('>', '\\u003e')} -->`;
+}
+
+export const epicJournalKey = correlation => JSON.stringify([correlation.repository, correlation.parent, correlation.planDigest, correlation.kind, correlation.slice]);
+
+export function readEpicMarker(body) {
+  if (typeof body !== 'string' || body.split(prefix).length !== 2) return null;
+  const match = body.match(/<!-- lighthouse-epic:([^\n]*?) -->/);
+  if (!match) return null;
+  try {
+    const value = JSON.parse(match[1]);
+    if (value.schemaVersion !== 1 || !isDeepStrictEqual(value, epicCorrelation(value))) return null;
+    return value;
+  } catch { return null; }
+}
+
+export function epicChildBody(parent, slice, correlation) {
+  return `Parent issue: #${parent}${slice.scope.length ? `\n\nScope:\n${slice.scope.map(item => `- ${item}`).join('\n')}` : ''}\n\nAcceptance evidence:\n${slice.acceptance.map(item => `- ${item}`).join('\n')}\n\n${epicMarker(correlation)}`;
+}
+
+// The credentialed host supplies a durable journal, serialized parent lease,
+// current authorization check and receipt authentication. This adapter grants none.
+export async function reconcileEpicChildren(plan, context, host) {
+  plan = buildDecompositionPlan(plan);
+  const digest = epicPlanDigest(plan);
+  const { repository, parent, base } = context;
+  for (const name of ['withLease', 'readReceipt', 'writeReceipt', 'findCandidates', 'authenticate', 'beforeWrite', 'api']) if (typeof host?.[name] !== 'function') throw Error(`Trusted host must provide ${name}`);
+  const idNumber = plan.parent.id.match(/^(?:GH-)?([1-9]\d*)$/)?.[1];
+  if (plan.parent.number !== undefined && (!positive(plan.parent.number) || idNumber && String(plan.parent.number) !== idNumber) || String(parent) !== String(plan.parent.number ?? idNumber)) throw Error('Parent identity mismatch');
+  const expected = new Map(plan.slices.map(slice => [slice.id, epicCorrelation({ repository, parent, slice: slice.id, planDigest: digest, base, dependencies: slice.dependencies })]));
+  return host.withLease(`${repository}:${parent}`, async () => {
+    const outcomes = [];
+    for (const id of plan.order) {
+      const correlation = expected.get(id), slice = plan.slices.find(item => item.id === id);
+      const key = epicJournalKey(correlation);
+      try {
+        const unmet = slice.dependencies.filter(dependency => outcomes.find(item => item.id === dependency)?.state !== 'linked');
+        if (unmet.length) {
+          outcomes.push({ id, state: 'blocked', reason: `Dependencies are not reconciled: ${unmet.join(', ')}` });
+          return { schemaVersion: 1, status: 'blocked', children: outcomes, parent: 'open' };
+        }
+        let receipt = await host.readReceipt(key);
+        if (receipt != null && (receipt.schemaVersion !== 1 || !['intent', 'created', 'linked', 'cancelled'].includes(receipt.state))) throw Error('Unsupported or malformed durable receipt');
+        const candidates = await host.findCandidates(correlation);
+        if (!Array.isArray(candidates) || candidates.length > 1) throw Error('Duplicate or invalid candidate observations');
+        let resource = candidates[0];
+        if (receipt && !isDeepStrictEqual(receipt.correlation, correlation)) throw Error('Receipt correlation changed');
+        if (resource && (!receipt || !positive(resource.id) || !positive(resource.number) || resource.pull_request || !isDeepStrictEqual(readEpicMarker(resource.body), correlation) || await host.authenticate(resource, receipt) !== true)) throw Error('Candidate lacks matching authenticated receipt');
+        if (receipt?.state === 'cancelled') { outcomes.push({ id, state: 'cancelled' }); continue; }
+        if (!resource && receipt) throw Error('Prior write is missing or uncertain; reconcile before recreating');
+        if (resource && (receipt.resource?.id !== resource.id || receipt.resource?.number !== resource.number)) throw Error('Receipt resource identity mismatch');
+        if (!resource) {
+          const intent = { schemaVersion: 1, state: 'intent', correlation };
+          await host.beforeWrite(correlation);
+          await host.writeReceipt(key, intent);
+          // Persist intent before POST. A lost response must never trigger another POST.
+          await host.beforeWrite(correlation);
+          resource = await host.api('issues', 'POST', { title: slice.title, body: epicChildBody(parent, slice, correlation) });
+          if (!positive(resource?.id) || !positive(resource?.number)) throw Error('Create response lacks native resource identity');
+          receipt = { ...intent, state: 'created', resource: { id: resource.id, number: resource.number } };
+          await host.writeReceipt(key, receipt);
+        }
+        const relation = await host.api(`issues/${resource.number}/parent`);
+        if (relation && relation.number !== parent) throw Error('Child belongs to another parent');
+        if (!relation) {
+          await host.beforeWrite(correlation);
+          await host.api(`issues/${parent}/sub_issues`, 'POST', { sub_issue_id: resource.id });
+        }
+        for (const dependency of slice.dependencies) {
+          const prerequisite = outcomes.find(item => item.id === dependency);
+          if (prerequisite?.state !== 'linked') throw Error(`Dependency ${dependency} is not reconciled`);
+          const links = [];
+          for (let page = 1; page <= 10; page++) {
+            const batch = await host.api(`issues/${resource.number}/dependencies/blocked_by?per_page=100&page=${page}`);
+            if (!Array.isArray(batch)) throw Error('Dependency observations unavailable');
+            links.push(...batch);
+            if (batch.length < 100) break;
+            if (page === 10) throw Error('Dependency inventory exceeds reconciliation bounds');
+          }
+          if (!links.some(item => item.id === prerequisite.resource.id)) {
+            await host.beforeWrite(correlation);
+            await host.api(`issues/${resource.number}/dependencies/blocked_by`, 'POST', { issue_id: prerequisite.resource.id });
+          }
+        }
+        receipt = { ...receipt, state: 'linked' };
+        await host.writeReceipt(key, receipt);
+        outcomes.push({ id, state: 'linked', resource: receipt.resource });
+      } catch (error) {
+        outcomes.push({ id, state: 'uncertain', reason: error.message });
+        // A partial failure is a checkpoint, not permission to create downstream work.
+        return { schemaVersion: 1, status: 'blocked', children: outcomes, parent: 'open' };
+      }
+    }
+    return { schemaVersion: 1, status: 'reconciled', children: outcomes, parent: 'open' };
+  });
+}

package/src/epic-journal.mjs

@@ -0,0 +1,104 @@
+import { writeFile } from 'node:fs/promises';
+import { isDeepStrictEqual } from 'node:util';
+import { issueComments } from './stage-dispatch.mjs';
+import { readActionsJson } from './actions-artifact.mjs';
+import { epicCorrelation, epicJournalKey } from './epic-github.mjs';
+
+const marker = '<!-- lighthouse-epic-journal:';
+const positive = value => Number.isSafeInteger(Number(value)) && /^[1-9][0-9]*$/.test(String(value));
+const sha = value => /^[a-f0-9]{40}$/.test(value ?? '');
+const keyFor = epicJournalKey;
+const artifactName = (parent, attempt) => `lighthouse-epic-journal-${parent}-${attempt}`;
+
+function checkedReceipt(key, receipt, repository, parent) {
+  if (!receipt || receipt.schemaVersion !== 1 || !['intent', 'created', 'linked', 'cancelled', 'merging', 'accepted'].includes(receipt.state) || !isDeepStrictEqual(receipt.correlation, epicCorrelation(receipt.correlation)) || receipt.correlation.repository !== repository || receipt.correlation.parent !== parent || keyFor(receipt.correlation) !== key) throw Error('Invalid epic journal receipt');
+  const resource = receipt.resource;
+  if (receipt.state === 'intent' && resource !== undefined || ['created', 'linked', 'merging', 'accepted'].includes(receipt.state) && !resource || resource !== undefined && (!positive(resource.id) || !positive(resource.number) || Object.keys(resource).sort().join(',') !== 'id,number')) throw Error('Epic receipt resource is invalid');
+  const publication = receipt.publication;
+  const needsPublication = receipt.correlation.kind === 'pull-request' && (['created', 'linked', 'merging', 'accepted'].includes(receipt.state) || receipt.state === 'cancelled' && !!resource);
+  if (needsPublication && (!publication || !positive(publication.run) || !Number.isSafeInteger(publication.attempt) || publication.attempt < 1 || !sha(publication.head) || Object.keys(publication).sort().join(',') !== 'attempt,head,run') || !needsPublication && publication !== undefined) throw Error('Epic publication receipt is invalid');
+  const merge = receipt.merge, merging = ['merging', 'accepted'].includes(receipt.state);
+  if (merging && (receipt.correlation.kind !== 'pull-request' || !merge || !sha(merge.head) || merge.head !== publication.head || !sha(merge.base) || !sha(merge.candidate) || !Number.isSafeInteger(merge.review) || merge.review < 1 || receipt.state === 'accepted' && !sha(merge.commit) || Object.keys(merge).sort().join(',') !== (receipt.state === 'accepted' ? 'base,candidate,commit,head,review' : 'base,candidate,head,review')) || !merging && merge !== undefined) throw Error('Epic merge receipt is invalid');
+  const expected = ['correlation', ...(merge ? ['merge'] : []), ...(publication ? ['publication'] : []), ...(resource ? ['resource'] : []), 'schemaVersion', 'state'].sort().join(',');
+  if (Object.keys(receipt).sort().join(',') !== expected) throw Error('Epic receipt has unexpected fields');
+  return receipt;
+}
+
+function parseEntry(comment, repository, parent) {
+  if (comment.user?.login !== 'github-actions[bot]' || comment.user.type !== 'Bot' || comment.issue_url !== `https://api.github.com/repos/${repository}/issues/${parent}` || !positive(comment.id)) throw Error('Untrusted epic journal comment');
+  const matches = [...(comment.body ?? '').matchAll(/<!-- lighthouse-epic-journal:(\{[^\n]*\}) -->/g)];
+  if (matches.length !== 1) throw Error('Missing or ambiguous epic journal marker');
+  const value = JSON.parse(matches[0][1]);
+  if (Object.keys(value).sort().join(',') !== 'attempt,key,parent,receipt,repository,revision,runId,schemaVersion' || value.schemaVersion !== 1 || value.repository !== repository || value.parent !== parent || !positive(value.runId) || !Number.isSafeInteger(value.attempt) || value.attempt < 1 || !sha(value.revision) || typeof value.key !== 'string') throw Error('Invalid epic journal identity');
+  checkedReceipt(value.key, value.receipt, repository, parent);
+  return value;
+}
+
+// The marker identifies a candidate; only the owner-triggered run and its retained artifact authenticate it.
+export async function readEpicResourceReceipt({ api, repository, owner, correlation, sourceRevision, defaultBranch, resource, allowedStates = ['linked'], readArtifact = readActionsJson }) {
+  if (!isDeepStrictEqual(correlation, epicCorrelation(correlation)) || correlation.repository !== repository || !sha(sourceRevision) || !defaultBranch || resource && (!positive(resource.id) || !positive(resource.number)) || !Array.isArray(allowedStates) || !allowedStates.length || allowedStates.some(state => !['linked', 'accepted'].includes(state))) throw Error('Invalid epic resource admission');
+  const parent = correlation.parent, key = keyFor(correlation);
+  const comments = await issueComments(api, parent);
+  const candidates = comments.filter(c => c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot' && c.body?.includes(marker)).map(c => ({ comment: c, entry: parseEntry(c, repository, parent) })).filter(item => item.entry.key === key);
+  if (candidates.length !== 1) throw Error('Epic resource journal is missing or ambiguous');
+  const { comment, entry } = candidates[0], receipt = entry.receipt;
+  if (entry.revision !== sourceRevision || !allowedStates.includes(receipt.state) || !isDeepStrictEqual(receipt.correlation, correlation) || resource && !isDeepStrictEqual(receipt.resource, resource)) throw Error('Epic resource receipt does not match the current identity');
+  const origin = await api(`actions/runs/${entry.runId}/attempts/${entry.attempt}`);
+  if (String(origin.id) !== String(entry.runId) || origin.run_attempt !== entry.attempt || origin.path !== '.github/workflows/lighthouse-sdlc-epic.yml' || origin.event !== 'workflow_dispatch' || origin.status !== 'completed' || origin.actor?.login !== owner || origin.triggering_actor?.login !== owner || origin.head_sha !== sourceRevision || origin.head_branch !== defaultBranch || origin.repository?.full_name !== repository) throw Error('Epic resource journal origin is not trusted');
+  const stored = await readArtifact(api, repository, entry.runId, artifactName(parent, entry.attempt), 'journal.json');
+  if (!stored || stored.schemaVersion !== 1 || stored.repository !== repository || stored.parent !== parent || stored.revision !== sourceRevision || String(stored.runId) !== String(entry.runId) || stored.attempt !== entry.attempt || !isDeepStrictEqual(stored.entries?.[key], { commentId: comment.id, receipt })) throw Error('Epic resource journal artifact is missing or differs from its comment');
+  return receipt;
+}
+
+export async function readEpicChildReceipt(input) {
+  if (input.correlation?.kind !== 'child' || !input.resource) throw Error('Invalid epic child admission');
+  return readEpicResourceReceipt(input);
+}
+
+export async function createEpicJournal({ api, repository, owner, parent, sourceRevision, defaultBranch, run, path, authorize, readArtifact = readActionsJson }) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repository ?? '') || typeof owner !== 'string' || !positive(parent) || !sha(sourceRevision) || !defaultBranch || !positive(run?.id) || !Number.isSafeInteger(run?.run_attempt) || run.run_attempt < 1 || run.status !== 'in_progress' || run.path !== '.github/workflows/lighthouse-sdlc-epic.yml' || run.event !== 'workflow_dispatch' || run.actor?.login !== owner || run.triggering_actor?.login !== owner || run.head_sha !== sourceRevision || run.head_branch !== defaultBranch || run.repository?.full_name !== repository || typeof authorize !== 'function' || typeof path !== 'string') throw Error('Epic journal requires an authenticated owner workflow');
+  parent = Number(parent);
+  const journal = { schemaVersion: 1, repository, parent, revision: sourceRevision, runId: String(run.id), attempt: run.run_attempt, entries: {} };
+  const loaded = new Map();
+  const save = () => writeFile(path, JSON.stringify(journal));
+  await save();
+  async function readReceipt(key) {
+    const comments = await issueComments(api, parent);
+    const candidates = comments.filter(c => c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot' && c.body?.includes(marker)).map(c => ({ comment: c, entry: parseEntry(c, repository, parent) })).filter(item => item.entry.key === key);
+    if (candidates.length > 1) throw Error('Duplicate epic journal receipts');
+    if (!candidates.length) { loaded.set(key, null); return null; }
+    const { comment, entry } = candidates[0];
+    if (entry.revision !== sourceRevision) throw Error('Epic journal source changed');
+    let stored;
+    if (entry.runId === String(run.id) && entry.attempt === run.run_attempt) stored = journal;
+    else {
+      const origin = await api(`actions/runs/${entry.runId}/attempts/${entry.attempt}`);
+      if (String(origin.id) !== String(entry.runId) || origin.run_attempt !== entry.attempt || origin.path !== run.path || origin.event !== 'workflow_dispatch' || origin.status !== 'completed' || origin.actor?.login !== owner || origin.triggering_actor?.login !== owner || origin.head_sha !== sourceRevision || origin.head_branch !== defaultBranch || origin.repository?.full_name !== repository) throw Error('Epic journal origin is not trusted');
+      stored = await readArtifact(api, repository, entry.runId, artifactName(parent, entry.attempt), 'journal.json');
+    }
+    if (!stored || stored.schemaVersion !== 1 || stored.repository !== repository || stored.parent !== parent || stored.revision !== sourceRevision || String(stored.runId) !== String(entry.runId) || stored.attempt !== entry.attempt || !isDeepStrictEqual(stored.entries?.[key], { commentId: comment.id, receipt: entry.receipt })) throw Error('Epic journal artifact is missing or differs from its comment');
+    loaded.set(key, { comment, receipt: entry.receipt });
+    return entry.receipt;
+  }
+  async function writeReceipt(key, receipt) {
+    checkedReceipt(key, receipt, repository, parent);
+    if (!loaded.has(key)) throw Error('Epic journal must be read before writing');
+    const previous = loaded.get(key);
+    if (previous && (!isDeepStrictEqual(previous.receipt.correlation, receipt.correlation) || previous.receipt.resource && !isDeepStrictEqual(previous.receipt.resource, receipt.resource) || !({ intent: ['created', 'cancelled'], created: ['created', 'linked', 'cancelled'], linked: ['linked', 'merging', 'cancelled'], merging: ['merging', 'accepted'], accepted: ['accepted'], cancelled: ['cancelled'] })[previous.receipt.state].includes(receipt.state))) throw Error('Epic journal transition is invalid');
+    if (previous?.receipt.merge) {
+      const { commit: ignored, ...identity } = receipt.merge ?? {};
+      const { commit: previousCommit, ...prior } = previous.receipt.merge;
+      if (!isDeepStrictEqual(identity, prior) || previousCommit && previousCommit !== receipt.merge?.commit || !isDeepStrictEqual(previous.receipt.publication, receipt.publication)) throw Error('Epic merge identity changed');
+    }
+    if (!previous && receipt.state !== 'intent') throw Error('Epic journal must start with intent');
+    if (await authorize() !== true) throw Error('Epic journal authorization changed');
+    const entry = { schemaVersion: 1, repository, parent, revision: sourceRevision, runId: String(run.id), attempt: run.run_attempt, key, receipt };
+    const body = `${marker}${JSON.stringify(entry).replaceAll('<', '\\u003c').replaceAll('>', '\\u003e')} -->`;
+    const comment = previous ? await api(`issues/comments/${previous.comment.id}`, 'PATCH', { body }) : await api(`issues/${parent}/comments`, 'POST', { body });
+    if (!isDeepStrictEqual(parseEntry(comment, repository, parent), entry)) throw Error('Epic journal write could not be confirmed');
+    journal.entries[key] = { commentId: comment.id, receipt };
+    await save();
+    loaded.set(key, { comment, receipt });
+  }
+  return { readReceipt, writeReceipt };
+}

package/src/epic-merge.mjs

@@ -0,0 +1,91 @@
+import { checkImplementationPullRequest } from './proposal-review.mjs';
+import { checkCommit, list, loadProfile, requiredPolicy } from './completion.mjs';
+import { isDeepStrictEqual } from 'node:util';
+import { epicCorrelation, epicJournalKey } from './epic-github.mjs';
+
+const sha = value => /^[a-f0-9]{40}$/.test(value ?? '');
+
+// The caller authenticates the owner's decision and holds the parent lease.
+export async function observeEpicMerge(api, { repository, owner, child, epic, decision }, { authenticateChild, authenticatePullRequest, authorizeDecision, loadPolicy = async () => {
+  const profile = await loadProfile(api, repository, epic.sourceRevision);
+  return requiredPolicy(api, epic.base, profile);
+} }) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repository ?? '') || typeof owner !== 'string' || !owner || !Number.isSafeInteger(child) || child < 1 || !Number.isSafeInteger(epic?.parent) || epic.parent < 1 || epic.parent === child || epic.base !== `lighthouse/epic-${epic.parent}` || typeof epic.slice !== 'string' || !epic.slice.trim() || !/^[a-f0-9]{64}$/.test(epic.planDigest ?? '') || !sha(epic.sourceRevision) || !Number.isSafeInteger(decision?.pr) || decision.pr < 1 || !Number.isSafeInteger(decision.review) || decision.review < 1 || !sha(decision.head) || !sha(decision.base) || typeof authenticateChild !== 'function' || typeof authenticatePullRequest !== 'function' || typeof authorizeDecision !== 'function') throw Error('Invalid epic merge decision');
+  if (await authorizeDecision(decision) !== true) throw Error('Epic merge decision is not authorized');
+  const current = await authenticateChild();
+  if (current.parent !== epic.parent || current.slice !== epic.slice || current.planDigest !== epic.planDigest || current.base !== epic.base || current.sourceRevision !== epic.sourceRevision) throw Error('Epic child authority changed');
+  const branch = await api(`git/ref/heads/${epic.base}`);
+  if (branch.ref !== `refs/heads/${epic.base}` || branch.object?.sha !== decision.base) throw Error('Epic base changed before merge');
+  const pr = await api(`pulls/${decision.pr}`);
+  const target = checkImplementationPullRequest(pr, repository);
+  if (target.issue !== child || target.base !== epic.base || target.head !== decision.head || pr.draft || pr.mergeable !== true || !sha(pr.merge_commit_sha)) throw Error('Epic child PR is not eligible for the approved head and base');
+  if (await authenticatePullRequest(pr, target) !== true) throw Error('Epic child PR lacks an authenticated receipt');
+  const merge = await api(`git/commits/${pr.merge_commit_sha}`);
+  if (!Array.isArray(merge.parents) || merge.parents.length !== 2 || merge.parents[0].sha !== decision.base || merge.parents[1].sha !== decision.head) throw Error('GitHub test merge does not bind the approved head and current base');
+  const reviews = await list(api, `pulls/${decision.pr}/reviews`);
+  const latest = reviews.filter(review => review.user?.login === owner && review.user.type === 'User' && ['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED'].includes(review.state)).sort((a, b) => b.id - a.id)[0];
+  if (latest?.id !== decision.review || latest.state !== 'APPROVED' || latest.commit_id !== decision.head) throw Error('Current owner review does not approve this child head');
+  const policy = await loadPolicy();
+  if (!Array.isArray(policy?.checks) || !policy.checks.length) throw Error('Epic merge has no enforced checks');
+  const checks = await checkCommit(api, pr.merge_commit_sha, policy.checks);
+  if (checks.some(check => check.status !== 'passed')) throw Error('Epic merge checks are missing, pending or failed');
+  if (await authorizeDecision(decision) !== true) throw Error('Epic merge decision was revoked');
+  const childAgain = await authenticateChild();
+  if (childAgain.parent !== current.parent || childAgain.slice !== current.slice || childAgain.planDigest !== current.planDigest || childAgain.base !== current.base || childAgain.sourceRevision !== current.sourceRevision) throw Error('Epic child authority changed');
+  const fresh = await api(`pulls/${decision.pr}`), freshBranch = await api(`git/ref/heads/${epic.base}`);
+  const freshTarget = checkImplementationPullRequest(fresh, repository, target);
+  const freshReviews = await list(api, `pulls/${decision.pr}/reviews`);
+  const freshReview = freshReviews.filter(review => review.user?.login === owner && review.user.type === 'User' && ['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED'].includes(review.state)).sort((a, b) => b.id - a.id)[0];
+  if (await authenticatePullRequest(fresh, freshTarget) !== true || fresh.mergeable !== true || fresh.merge_commit_sha !== pr.merge_commit_sha || fresh.draft || freshBranch.object?.sha !== decision.base || freshReview?.id !== decision.review || freshReview.state !== 'APPROVED' || freshReview.commit_id !== decision.head) throw Error('Epic merge evidence changed while checking');
+  return { child, parent: epic.parent, slice: epic.slice, planDigest: epic.planDigest, pr: target.number, head: decision.head, base: decision.base, mergeCandidate: pr.merge_commit_sha, review: latest.id, checks };
+}
+
+// The caller supplies an authenticated journal, owner decision and the parent lease.
+export async function mergeEpicChild(api, { correlation, resource }, { journal, observe, authorize, verifyChecks }) {
+  if (correlation?.kind !== 'pull-request' || !isDeepStrictEqual(correlation, epicCorrelation(correlation)) || !Number.isSafeInteger(resource?.id) || resource.id < 1 || !Number.isSafeInteger(resource.number) || resource.number < 1 || typeof journal?.readReceipt !== 'function' || typeof journal?.writeReceipt !== 'function' || typeof observe !== 'function' || typeof authorize !== 'function' || typeof verifyChecks !== 'function') throw Error('Invalid epic merge context');
+  const key = epicJournalKey(correlation), receipt = await journal.readReceipt(key);
+  if (!receipt || !isDeepStrictEqual(receipt.correlation, correlation) || receipt.resource?.id !== resource.id || receipt.resource?.number !== resource.number || !['linked', 'merging', 'accepted'].includes(receipt.state)) throw Error('Epic PR receipt is missing or changed');
+  const confirm = async binding => {
+    const pr = await api(`pulls/${resource.number}`);
+    if (pr.id !== resource.id || pr.number !== resource.number || !pr.merged || pr.head?.sha !== binding.head || pr.base?.ref !== correlation.base || pr.head.repo?.full_name !== correlation.repository || pr.base.repo?.full_name !== correlation.repository || !sha(pr.merge_commit_sha) || pr.merged_by?.login !== 'github-actions[bot]' || pr.merged_by.type !== 'Bot') throw Error('Epic merge outcome is unconfirmed');
+    const actual = await api(`git/commits/${pr.merge_commit_sha}`), candidate = await api(`git/commits/${binding.candidate}`);
+    if (!Array.isArray(actual.parents) || actual.parents.length !== 1 || actual.parents[0].sha !== binding.base || !sha(actual.tree?.sha) || actual.tree.sha !== candidate.tree?.sha) throw Error('Epic merge commit does not match the approved base and candidate');
+    return pr.merge_commit_sha;
+  };
+  if (receipt.state === 'accepted') {
+    if (await authorize() !== true || await verifyChecks(receipt.merge) !== true) throw Error('Accepted epic merge authority or checks changed');
+    if (await confirm(receipt.merge) !== receipt.merge.commit) throw Error('Accepted epic merge changed');
+    return { status: 'accepted', commit: receipt.merge.commit, recovered: true };
+  }
+  if (receipt.state === 'merging') {
+    if (await authorize() !== true) throw Error('Epic merge reconciliation is not authorized');
+    const commit = await confirm(receipt.merge);
+    if (await verifyChecks(receipt.merge) !== true || await authorize() !== true) throw Error('Epic merge authority or checks are no longer valid');
+    await journal.writeReceipt(key, { ...receipt, state: 'accepted', merge: { ...receipt.merge, commit } });
+    return { status: 'accepted', commit, recovered: true };
+  }
+  const initial = await observe();
+  if (initial.parent !== correlation.parent || initial.slice !== correlation.slice || initial.planDigest !== correlation.planDigest || initial.pr !== resource.number || !sha(initial.head) || initial.head !== receipt.publication?.head || !sha(initial.base) || !sha(initial.mergeCandidate) || !Number.isSafeInteger(initial.review) || initial.review < 1) throw Error('Epic merge observation does not match the receipt');
+  const merge = { head: initial.head, base: initial.base, candidate: initial.mergeCandidate, review: initial.review };
+  const intent = { ...receipt, state: 'merging', merge };
+  if (await authorize() !== true) throw Error('Epic merge is not authorized');
+  await journal.writeReceipt(key, intent);
+  const fresh = await observe();
+  if (!isDeepStrictEqual(fresh, initial)) throw Error('Epic merge evidence changed before publication');
+  if (await authorize() !== true) throw Error('Epic merge authorization changed');
+  let response;
+  try { response = await api(`pulls/${resource.number}/merge`, 'PUT', { sha: merge.head, merge_method: 'squash' }); }
+  catch (error) {
+    const commit = await confirm(merge).catch(() => null);
+    if (!commit) throw error;
+    if (await verifyChecks(merge) !== true || await authorize() !== true) throw Error('Epic merge authority or checks are no longer valid');
+    await journal.writeReceipt(key, { ...intent, state: 'accepted', merge: { ...merge, commit } });
+    return { status: 'accepted', commit, recovered: true };
+  }
+  if (!response?.merged || !sha(response.sha)) throw Error('Epic merge response is unconfirmed');
+  const commit = await confirm(merge);
+  if (commit !== response.sha) throw Error('Epic merge response does not match GitHub state');
+  if (await verifyChecks(merge) !== true || await authorize() !== true) throw Error('Epic merge authority or checks are no longer valid');
+  await journal.writeReceipt(key, { ...intent, state: 'accepted', merge: { ...merge, commit } });
+  return { status: 'accepted', commit, recovered: false };
+}