@aviaratech/ai-delivery 0.1.0

package/dist/pr.js

@@ -0,0 +1,972 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+import { loadDeliveryConfig } from './config/deliveryConfig.js';
+import { assertPrivateFile } from './delivery/common.js';
+import { digestValue, loadSelectedRepositoryPolicy, validateRepositoryPolicyBoundary, } from './delivery/index.js';
+import { DeliveryError } from './errors.js';
+import { coordinate, defaultBaseRef, git, gitCommonDir, gitExitCode, gitRoot } from './git.js';
+import { withAuthorGitToken } from './github/client.js';
+import { getConfiguredNativeIssueMetadata, nativeIssueSettingsFromDeliveryConfig, } from './github/nativeIssueMetadata.js';
+import { getNativeBlockerRelationships } from './github/relationships.js';
+import { getIssueProjectStatus, projectSettingsFromDeliveryConfig, syncIssueProjectStatus, } from './github/projectDelivery.js';
+import { loadPrepublicationArtifact, loadSubmittedReview, reviewArtifactApproval, assertSubmittedReviewCurrent, parseReviewArtifact, submitReview, } from './review.js';
+import { getIssueWorktreeStrict, listWorktreesStrict, updateIssueWorktreeDelivery, } from './services/worktreeRegistry.js';
+import { getDeliveryRecords, recordMergedDelivery } from './services/deliveryRecordService.js';
+import { createIssuePhaseEvidence, loadRemovedMergedRun, loadVerifiedRun } from './verification.js';
+import { writePrivateJsonFileAtomically } from './utils/atomicJson.js';
+import { cleanupMergedIssueWorktree, preparePrWorktree } from './worktree.js';
+const Digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const Sha = z.string().regex(/^[a-f0-9]{40}$/u);
+const PublicationSchema = z
+    .object({
+    baseSha: Sha,
+    evidenceId: Digest,
+    headSha: Sha,
+    issueNumber: z.number().int().positive(),
+    prNumber: z.number().int().positive(),
+    publicationId: Digest,
+    schemaVersion: z.literal('ai-delivery.publication@1'),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const { publicationId, ...content } = value;
+    if (publicationId !== digestValue(content))
+        ctx.addIssue({ code: 'custom', message: 'Publication identity is invalid.' });
+});
+const MergeStrategy = z.enum(['merge', 'squash', 'rebase']);
+const MergeIntentShape = z
+    .object({
+    baseBranch: z.string().regex(/^[A-Za-z0-9._/-]+$/u),
+    baseSha: Sha,
+    evidenceId: Digest,
+    exactBaseHeadLease: z.boolean(),
+    headBranch: z.string().regex(/^[A-Za-z0-9._/-]+$/u),
+    headSha: Sha,
+    headTree: Sha,
+    intentId: Digest,
+    issueNumber: z.number().int().positive(),
+    prNumber: z.number().int().positive(),
+    reviewReceiptId: Digest,
+    schemaVersion: z.literal('ai-delivery.merge-intent@2'),
+    strategy: MergeStrategy,
+})
+    .strict();
+const MergeIntentSchema = MergeIntentShape.superRefine((value, ctx) => {
+    const { intentId, ...content } = value;
+    if (intentId !== digestValue(content))
+        ctx.addIssue({ code: 'custom', message: 'Merge intent identity is invalid.' });
+});
+const MergeAttemptSchema = z
+    .object({
+    actor: z.string().min(1),
+    actorLogin: z.string().min(1),
+    attemptId: Digest,
+    authSource: z.enum(['app', 'personal']),
+    credentialIdentity: z.string().min(1),
+    intentId: Digest,
+    operation: z.enum(['pulls.merge', 'updateRefs']),
+    schemaVersion: z.literal('ai-delivery.merge-attempt@1'),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const { attemptId, ...content } = value;
+    if (attemptId !== digestValue(content))
+        ctx.addIssue({ code: 'custom', message: 'Merge attempt identity is invalid.' });
+});
+const MergeResultSchema = z
+    .object({
+    attemptId: Digest,
+    mergeSha: Sha,
+    resultId: Digest,
+    schemaVersion: z.literal('ai-delivery.merge-result@1'),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const { resultId, ...content } = value;
+    if (resultId !== digestValue(content))
+        ctx.addIssue({ code: 'custom', message: 'Merge result identity is invalid.' });
+});
+const MergeSchema = MergeIntentShape.omit({ intentId: true, schemaVersion: true })
+    .extend({
+    intentId: Digest,
+    mergeId: Digest,
+    mergeSha: Sha,
+    mergeTree: Sha,
+    schemaVersion: z.literal('ai-delivery.merge@3'),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const { mergeId, ...content } = value;
+    if (mergeId !== digestValue(content))
+        ctx.addIssue({ code: 'custom', message: 'Merge identity is invalid.' });
+});
+function publicationPath(root, issueNumber, headSha) {
+    return join(gitCommonDir(root), 'ai-delivery', 'publications', String(issueNumber), `${headSha}.json`);
+}
+function mergePath(root, issueNumber, headSha) {
+    return join(gitCommonDir(root), 'ai-delivery', 'merges', String(issueNumber), `${headSha}.json`);
+}
+function mergeIntentPath(root, issueNumber, headSha) {
+    return join(gitCommonDir(root), 'ai-delivery', 'merge-intents', String(issueNumber), `${headSha}.json`);
+}
+function mergeAttemptPath(root, issueNumber, headSha) {
+    return join(gitCommonDir(root), 'ai-delivery', 'merge-attempts', String(issueNumber), `${headSha}.json`);
+}
+function mergeResultPath(root, issueNumber, headSha) {
+    return join(gitCommonDir(root), 'ai-delivery', 'merge-results', String(issueNumber), `${headSha}.json`);
+}
+function readOptionalPrivate(path, parse) {
+    let raw;
+    try {
+        raw = JSON.parse(assertPrivateFile(path).toString('utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new DeliveryError('Stored lifecycle receipt is unreadable.');
+    }
+    try {
+        return parse(raw);
+    }
+    catch {
+        throw new DeliveryError('Stored lifecycle receipt is corrupt.');
+    }
+}
+function readPrivate(path, parse) {
+    let raw;
+    try {
+        raw = JSON.parse(assertPrivateFile(path).toString('utf8'));
+    }
+    catch {
+        throw new DeliveryError('Required private lifecycle receipt is missing or unreadable.');
+    }
+    return parse(raw);
+}
+export function loadPublication(root, issueNumber, headSha) {
+    return readPrivate(publicationPath(root, issueNumber, headSha), (value) => PublicationSchema.parse(value));
+}
+function validateDeliveryImpact(body) {
+    if ((body.match(/^## Delivery Impact\s*$/gmu) ?? []).length !== 1 ||
+        (body.match(/^Roadmap impact:\s*(?:updated|none)\s*$/gmu) ?? []).length !== 1 ||
+        (body.match(/^Docs impact:\s*(?:updated|none)\s*$/gmu) ?? []).length !== 1) {
+        throw new DeliveryError('PR body requires one Delivery Impact section with Roadmap impact and Docs impact.');
+    }
+}
+function baseBranch(root) {
+    const ref = defaultBaseRef(root);
+    const value = ref.startsWith('origin/') ? ref.slice('origin/'.length) : ref;
+    if (!/^[A-Za-z0-9._/-]+$/u.test(value))
+        throw new DeliveryError('Invalid configured default branch.');
+    return value;
+}
+/** @internal Selected-App Git transport, exported for process-boundary tests. */
+export async function runAuthorGit(context, path, args, operation) {
+    await withAuthorGitToken(context.clients, (token) => {
+        const gitEnv = {
+            PATH: process.env.PATH ?? '',
+            GIT_CONFIG_GLOBAL: '/dev/null',
+            GIT_CONFIG_NOSYSTEM: '1',
+        };
+        const unsafeConfig = spawnSync('git', ['config', '--includes', '--get-regexp', '^(url\\..*\\.(insteadof|pushinsteadof)|http(\\..*)?\\.extraheader)$'], {
+            cwd: path,
+            env: gitEnv,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (unsafeConfig.error || (unsafeConfig.status !== 0 && unsafeConfig.status !== 1)) {
+            throw new DeliveryError(`Cannot verify effective Git HTTP transport configuration (git exit ${String(unsafeConfig.status)}).`);
+        }
+        if (unsafeConfig.status === 0) {
+            throw new DeliveryError('Local Git transport configuration conflicts with selected App authentication.');
+        }
+        const temporary = mkdtempSync(join(tmpdir(), 'ai-delivery-git-auth-'));
+        const askpass = join(temporary, 'askpass.sh');
+        try {
+            writeFileSync(askpass, '#!/bin/sh\ncase "$1" in\n  *Username*) printf "%s\\n" x-access-token ;;\n  *Password*) printf "%s\\n" "$AI_DELIVERY_GIT_TOKEN" ;;\n  *) exit 1 ;;\nesac\n', { mode: 0o700 });
+            execFileSync('git', ['-c', 'credential.helper=', ...args], {
+                cwd: path,
+                encoding: 'utf8',
+                env: { ...gitEnv, AI_DELIVERY_GIT_TOKEN: token, GIT_ASKPASS: askpass, GIT_TERMINAL_PROMPT: '0' },
+                maxBuffer: 4 * 1024 * 1024,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (cause) {
+            const error = cause;
+            const detail = String(error.stderr ?? '')
+                .trim()
+                .replaceAll(token, '[redacted]');
+            throw new DeliveryError(`git ${operation} failed${detail ? `: ${detail}` : ''}`);
+        }
+        finally {
+            rmSync(temporary, { recursive: true, force: true });
+        }
+    });
+}
+async function pushReviewedHead(context, path, branch, sha) {
+    await runAuthorGit(context, path, ['push', `https://github.com/${context.repo.owner}/${context.repo.repo}.git`, `${sha}:refs/heads/${branch}`], 'push');
+}
+async function fetchMergedBase(context, branch) {
+    const refspec = `${branch}:refs/remotes/origin/${branch}`;
+    const origin = git(context.root, 'remote', 'get-url', 'origin');
+    if (isAbsolute(origin) || origin.startsWith('file://')) {
+        git(context.root, 'fetch', 'origin', refspec);
+        return;
+    }
+    await runAuthorGit(context, context.root, ['fetch', `https://github.com/${context.repo.owner}/${context.repo.repo}.git`, refspec], 'fetch');
+}
+export async function prInfo(context, input) {
+    if (input.prNumber !== undefined) {
+        const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: input.prNumber })).data;
+        return {
+            number: pr.number,
+            state: pr.state,
+            headSha: pr.head.sha,
+            baseSha: pr.base.sha,
+            draft: pr.draft ?? null,
+            url: pr.html_url,
+        };
+    }
+    if (input.issueNumber === undefined)
+        throw new DeliveryError('Provide an issue or PR number.');
+    const row = getIssueWorktreeStrict(input.issueNumber, context.root);
+    const matches = (await context.clients.rest.pulls.list({
+        ...context.repo,
+        head: `${context.repo.owner}:${row.branch}`,
+        state: 'open',
+        per_page: 100,
+    })).data;
+    if (matches.length > 1)
+        throw new DeliveryError('Multiple open PRs match the registered branch.');
+    const pr = matches[0];
+    return pr
+        ? {
+            number: pr.number,
+            state: pr.state,
+            headSha: pr.head.sha,
+            baseSha: pr.base.sha,
+            draft: pr.draft ?? null,
+            url: pr.html_url,
+        }
+        : { number: null, state: null, headSha: null, baseSha: null, draft: null, url: null };
+}
+export async function listPrs(context, state = 'open') {
+    const prs = await context.clients.rest.paginate(context.clients.rest.pulls.list, {
+        ...context.repo,
+        state,
+        per_page: 100,
+    });
+    return {
+        schemaVersion: 'ai-delivery.pr-list@1',
+        pullRequests: prs.map((pr) => ({
+            number: pr.number,
+            state: pr.state,
+            draft: pr.draft ?? false,
+            headSha: pr.head.sha,
+            baseSha: pr.base.sha,
+            url: pr.html_url,
+        })),
+    };
+}
+export async function prChecks(context, prNumber) {
+    const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: prNumber })).data;
+    const [checks, status] = await Promise.all([
+        context.clients.rest.checks.listForRef({ ...context.repo, ref: pr.head.sha, per_page: 100 }),
+        context.clients.rest.repos.getCombinedStatusForRef({ ...context.repo, ref: pr.head.sha }),
+    ]);
+    return {
+        schemaVersion: 'ai-delivery.pr-checks@1',
+        prNumber: pr.number,
+        headSha: pr.head.sha,
+        combinedStatus: status.data.state,
+        checkRuns: checks.data.check_runs.map((check) => ({
+            name: check.name,
+            status: check.status,
+            conclusion: check.conclusion,
+        })),
+    };
+}
+export async function checkoutPr(context, prNumber) {
+    if (!Number.isSafeInteger(prNumber) || prNumber <= 0)
+        throw new DeliveryError('PR number must be positive.');
+    const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: prNumber })).data;
+    const repository = `${context.repo.owner}/${context.repo.repo}`.toLowerCase();
+    if (pr.state !== 'open' ||
+        pr.head.repo?.full_name.toLowerCase() !== repository ||
+        pr.base.repo?.full_name.toLowerCase() !== repository ||
+        gitExitCode(context.root, 'check-ref-format', '--branch', pr.head.ref) !== 0) {
+        throw new DeliveryError('PR checkout requires an open in-repository branch with a valid ref.');
+    }
+    const remoteHead = (await context.clients.rest.git.getRef({ ...context.repo, ref: `heads/${pr.head.ref}` })).data
+        .object.sha;
+    if (remoteHead !== pr.head.sha)
+        throw new DeliveryError('PR branch ref drifted from the observed head.');
+    const fetchedRef = `refs/remotes/origin/ai-delivery-pr-${prNumber}`;
+    await runAuthorGit(context, context.root, [
+        'fetch',
+        `https://github.com/${context.repo.owner}/${context.repo.repo}.git`,
+        `refs/heads/${pr.head.ref}:${fetchedRef}`,
+    ], 'fetch');
+    if (git(context.root, 'rev-parse', fetchedRef) !== pr.head.sha) {
+        throw new DeliveryError('Fetched PR branch disagrees with the live head.');
+    }
+    const live = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: prNumber })).data;
+    if (live.state !== 'open' || live.head.sha !== pr.head.sha || live.head.ref !== pr.head.ref) {
+        throw new DeliveryError('PR changed during selected-App checkout.');
+    }
+    return preparePrWorktree({
+        headSha: pr.head.sha,
+        identity: context.config.roles.author.identity,
+        prNumber,
+        repoRoot: context.root,
+    });
+}
+export async function publishPr(context, input) {
+    const root = gitRoot(context.root);
+    const row = getIssueWorktreeStrict(input.issueNumber, root);
+    if (row.type !== 'issue' || row.status === 'merged')
+        throw new DeliveryError('PR publication requires an active issue worktree.');
+    const run = loadVerifiedRun(row.path, input.issueNumber);
+    const head = coordinate(row.path);
+    if (input.draft === false) {
+        const publication = loadPublication(row.path, input.issueNumber, head.sha);
+        const receipt = loadSubmittedReview(row.path, input.issueNumber, head.sha);
+        if (!receipt || receipt.publicationEvidenceId !== publication.evidenceId) {
+            throw new DeliveryError('Ready promotion requires a submitted review of the exact published head.');
+        }
+        await assertSubmittedReviewCurrent(context, receipt);
+        const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: publication.prNumber })).data;
+        if (pr.head.sha !== head.sha)
+            throw new DeliveryError('PR head drifted before ready promotion.');
+        if (pr.draft) {
+            await context.clients.graphql(`mutation Ready($id: ID!) { markPullRequestReadyForReview(input: {pullRequestId: $id}) { pullRequest { id isDraft } } }`, { id: pr.node_id });
+        }
+        const readback = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: publication.prNumber }))
+            .data;
+        if (readback.draft || readback.head.sha !== head.sha)
+            throw new DeliveryError('PR ready readback failed.');
+        return { prNumber: publication.prNumber, url: readback.html_url, publicationEvidenceId: publication.evidenceId };
+    }
+    const prepublication = loadPrepublicationArtifact(row.path, input.issueNumber, head.sha);
+    const approval = prepublication
+        ? reviewArtifactApproval({
+            artifact: prepublication,
+            classification: run.classification,
+            config: context.config,
+            issueNumber: input.issueNumber,
+        })
+        : undefined;
+    const evidence = await createIssuePhaseEvidence({
+        ...(approval === undefined ? {} : { approval }),
+        issueNumber: input.issueNumber,
+        phase: 'publish',
+        repoRoot: row.path,
+    });
+    const issue = (await context.clients.rest.issues.get({ ...context.repo, issue_number: input.issueNumber })).data;
+    const title = input.title ?? `${input.issueNumber}: ${issue.title}`;
+    const body = input.body ?? `Closes #${input.issueNumber}\n\n## Delivery Impact\n\nRoadmap impact: none\nDocs impact: none\n`;
+    validateDeliveryImpact(body);
+    const remoteHead = (await context.clients.rest.git.getRef({ ...context.repo, ref: `heads/${baseBranch(root)}` })).data
+        .object.sha;
+    if (remoteHead !== run.classification.base.sha)
+        throw new DeliveryError('Remote base changed after exact-head verification.');
+    await pushReviewedHead(context, row.path, row.branch, head.sha);
+    const matches = (await context.clients.rest.pulls.list({
+        ...context.repo,
+        head: `${context.repo.owner}:${row.branch}`,
+        state: 'open',
+        per_page: 100,
+    })).data;
+    if (matches.length > 1)
+        throw new DeliveryError('Multiple open PRs match the registered branch.');
+    const existing = matches[0];
+    const pr = existing
+        ? (await context.clients.rest.pulls.get({ ...context.repo, pull_number: existing.number })).data
+        : (await context.clients.rest.pulls.create({
+            ...context.repo,
+            base: baseBranch(root),
+            body,
+            draft: true,
+            head: row.branch,
+            title,
+        })).data;
+    if (pr.head.sha !== head.sha || pr.base.sha !== remoteHead || pr.state !== 'open' || !pr.draft) {
+        throw new DeliveryError('Draft PR readback does not match the verified head and base.');
+    }
+    const content = {
+        baseSha: remoteHead,
+        evidenceId: evidence.evidenceId,
+        headSha: head.sha,
+        issueNumber: input.issueNumber,
+        prNumber: pr.number,
+        schemaVersion: 'ai-delivery.publication@1',
+    };
+    const publication = PublicationSchema.parse({ ...content, publicationId: digestValue(content) });
+    writePrivateJsonFileAtomically(publicationPath(row.path, input.issueNumber, head.sha), publication);
+    await updateIssueWorktreeDelivery({
+        branch: row.branch,
+        issueNumber: input.issueNumber,
+        path: row.path,
+        prNumber: pr.number,
+        projectRoot: root,
+        status: 'pr-published',
+    });
+    return { prNumber: pr.number, url: pr.html_url, publicationEvidenceId: evidence.evidenceId };
+}
+export async function submitFormalReview(context, input) {
+    const row = getIssueWorktreeStrict(input.issueNumber, context.root);
+    const run = loadVerifiedRun(row.path, input.issueNumber);
+    const publication = loadPublication(row.path, input.issueNumber, run.classification.head.sha);
+    if (publication.prNumber !== input.prNumber)
+        throw new DeliveryError('Review PR does not match exact publication.');
+    const receipt = await submitReview({
+        artifact: parseReviewArtifact(input.artifact),
+        classification: run.classification,
+        context,
+        issueNumber: input.issueNumber,
+        prNumber: input.prNumber,
+        publicationEvidenceId: publication.evidenceId,
+    });
+    return { receiptId: receipt.receiptId, githubReviewId: receipt.githubReviewId };
+}
+async function checkPrMergeability(context, prNumber, expectedHead) {
+    const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: prNumber })).data;
+    if (pr.state !== 'open' ||
+        pr.draft ||
+        pr.head.sha !== expectedHead ||
+        pr.mergeable !== true ||
+        pr.mergeable_state !== 'clean')
+        throw new DeliveryError('PR is not clean, ready and mergeable at the exact reviewed head.');
+    const issueNumber = Number(/^issue\/(\d+)$/u.exec(pr.head.ref)?.[1]);
+    if (!Number.isSafeInteger(issueNumber))
+        throw new DeliveryError('PR branch is not a registered issue branch.');
+    const relationships = await getNativeBlockerRelationships({
+        graphql: context.clients.graphql,
+        issueNumber,
+        repo: context.repo,
+    });
+    const blockedBy = relationships.blockers.filter((value) => value.state === 'OPEN').map((value) => value.number);
+    const [checks, statuses] = await Promise.all([
+        context.clients.rest.checks.listForRef({ ...context.repo, ref: expectedHead, per_page: 100 }),
+        context.clients.rest.repos.getCombinedStatusForRef({ ...context.repo, ref: expectedHead }),
+    ]);
+    const checksPassed = checks.data.total_count === checks.data.check_runs.length &&
+        checks.data.check_runs.every((check) => check.status === 'completed' && ['success', 'neutral', 'skipped'].includes(check.conclusion ?? '')) &&
+        (statuses.data.statuses.length === 0 || statuses.data.state === 'success');
+    if (!checksPassed || blockedBy.length > 0)
+        throw new DeliveryError('PR has failed or pending checks or unresolved native blockers.');
+    return {
+        baseSha: pr.base.sha,
+        baseBranch: pr.base.ref,
+        headBranch: pr.head.ref,
+        title: pr.title,
+        blockedBy,
+        checksPassed,
+    };
+}
+/** @internal Lifecycle primitive; exported for local interruption tests. */
+export async function mergeWithExactLease(context, input) {
+    if (gitExitCode(input.worktreePath, 'merge-base', '--is-ancestor', input.baseSha, input.headSha) !== 0) {
+        throw new DeliveryError('Exact-lease merge requires the verified base to be an ancestor of the reviewed head.');
+    }
+    const latest = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: input.prNumber })).data;
+    if (latest.base.sha !== input.baseSha ||
+        latest.head.sha !== input.headSha ||
+        latest.base.ref !== input.baseBranch ||
+        latest.head.ref !== input.headBranch)
+        throw new DeliveryError('Exact base or head drifted before atomic merge.');
+    const repo = await context.clients.graphql('query RepositoryId($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { id } }', { owner: context.repo.owner, name: context.repo.repo });
+    if (!repo.repository?.id)
+        throw new DeliveryError('GitHub omitted repository node identity.');
+    input.beforeMutation?.();
+    const created = (await context.clients.rest.git.createCommit({
+        ...context.repo,
+        message: input.title,
+        parents: [input.baseSha, input.headSha],
+        tree: input.headTree,
+    })).data;
+    const mergeSha = Sha.parse(created.sha);
+    input.onPreparedMergeCommit?.(mergeSha);
+    const clientMutationId = `ai-delivery-exact-${mergeSha}`;
+    const response = await context.clients.graphql('mutation UpdateExactRefs($input: UpdateRefsInput!) { updateRefs(input: $input) { clientMutationId } }', {
+        input: {
+            clientMutationId,
+            repositoryId: repo.repository.id,
+            refUpdates: [
+                { name: `refs/heads/${input.baseBranch}`, beforeOid: input.baseSha, afterOid: mergeSha, force: false },
+                { name: `refs/heads/${input.headBranch}`, beforeOid: input.headSha, afterOid: input.headSha, force: false },
+            ],
+        },
+    });
+    if (response.updateRefs.clientMutationId !== clientMutationId)
+        throw new DeliveryError('Atomic merge mutation identity readback failed.');
+    const [base, head, commit] = await Promise.all([
+        context.clients.rest.git.getRef({ ...context.repo, ref: `heads/${input.baseBranch}` }),
+        context.clients.rest.git.getRef({ ...context.repo, ref: `heads/${input.headBranch}` }),
+        context.clients.rest.git.getCommit({ ...context.repo, commit_sha: mergeSha }),
+    ]);
+    if (base.data.object.sha !== mergeSha ||
+        head.data.object.sha !== input.headSha ||
+        commit.data.tree.sha !== input.headTree ||
+        commit.data.parents[0]?.sha !== input.baseSha ||
+        commit.data.parents[1]?.sha !== input.headSha)
+        throw new DeliveryError('Atomic merge ref or commit readback failed.');
+    const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: input.prNumber })).data;
+    if (pr.state !== 'closed' || !pr.merged_at || pr.merge_commit_sha !== mergeSha) {
+        throw new DeliveryError('GitHub did not report the exact merge commit as the completed PR.');
+    }
+    return mergeSha;
+}
+async function readMergedResult(context, intent, expectedSha) {
+    const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: intent.prNumber })).data;
+    if (pr.state !== 'closed' ||
+        !pr.merged_at ||
+        pr.head.sha !== intent.headSha ||
+        pr.head.ref !== intent.headBranch ||
+        pr.base.ref !== intent.baseBranch) {
+        throw new DeliveryError('Merged PR does not match the exact prepared merge intent.');
+    }
+    const mergeSha = Sha.parse(pr.merge_commit_sha);
+    if (expectedSha !== undefined && mergeSha !== expectedSha) {
+        throw new DeliveryError('Merged PR does not match the exact prepared merge intent.');
+    }
+    const [base, head, commit] = await Promise.all([
+        context.clients.rest.git.getRef({ ...context.repo, ref: `heads/${intent.baseBranch}` }),
+        context.clients.rest.git.getRef({ ...context.repo, ref: `heads/${intent.headBranch}` }).catch((error) => {
+            if (error.status === 404)
+                return null;
+            throw error;
+        }),
+        context.clients.rest.git.getCommit({ ...context.repo, commit_sha: mergeSha }),
+    ]);
+    const expectedMergeTree = !intent.exactBaseHeadLease && (intent.strategy === 'merge' || intent.strategy === 'squash')
+        ? git(context.root, 'merge-tree', '--write-tree', intent.baseSha, intent.headSha)
+        : intent.headTree;
+    if (!base.data.object.sha ||
+        (head !== null && head.data.object.sha !== intent.headSha) ||
+        commit.data.sha !== mergeSha ||
+        (intent.strategy === 'merge' &&
+            (commit.data.parents[0]?.sha !== intent.baseSha ||
+                commit.data.parents[1]?.sha !== intent.headSha ||
+                commit.data.tree.sha !== expectedMergeTree)) ||
+        (intent.strategy === 'squash' &&
+            (commit.data.parents[0]?.sha !== intent.baseSha || commit.data.tree.sha !== expectedMergeTree))) {
+        throw new DeliveryError('Remote merge ref, branch or commit readback disagrees with the prepared intent.');
+    }
+    if (expectedSha === undefined && intent.strategy === 'rebase') {
+        throw new DeliveryError('Rebase recovery lacks the returned exact merge SHA.');
+    }
+    return { mergeSha, mergeTree: Sha.parse(commit.data.tree.sha) };
+}
+async function expectedMergeAttempt(context, intent) {
+    if (context.clients.role !== 'author' || !context.clients.authenticatedAuthor) {
+        throw new DeliveryError('Merge recovery requires authenticated author identity readback.');
+    }
+    const verified = await context.clients.authenticatedAuthor();
+    if (!verified.actorLogin || !verified.credentialIdentity) {
+        throw new DeliveryError('Authenticated author identity readback is incomplete.');
+    }
+    const content = {
+        actor: context.config.roles.author.identity,
+        actorLogin: verified.actorLogin,
+        authSource: context.clients.authSource,
+        credentialIdentity: verified.credentialIdentity,
+        intentId: intent.intentId,
+        operation: intent.exactBaseHeadLease ? 'updateRefs' : 'pulls.merge',
+        schemaVersion: 'ai-delivery.merge-attempt@1',
+    };
+    return MergeAttemptSchema.parse({ ...content, attemptId: digestValue(content) });
+}
+function persistMergeResult(root, intent, attempt, mergeSha) {
+    const content = {
+        attemptId: attempt.attemptId,
+        mergeSha: Sha.parse(mergeSha),
+        schemaVersion: 'ai-delivery.merge-result@1',
+    };
+    writePrivateJsonFileAtomically(mergeResultPath(root, intent.issueNumber, intent.headSha), MergeResultSchema.parse({ ...content, resultId: digestValue(content) }));
+}
+/** @internal Lifecycle primitive; exported for local interruption tests. */
+export async function persistMergedResult(context, input) {
+    const { mergeSha, mergeTree } = await readMergedResult(context, input.intent, input.expectedSha);
+    const { schemaVersion: _version, ...intentContent } = input.intent;
+    const content = { ...intentContent, mergeSha, mergeTree, schemaVersion: 'ai-delivery.merge@3' };
+    const merged = MergeSchema.parse({ ...content, mergeId: digestValue(content) });
+    writePrivateJsonFileAtomically(input.path, merged);
+    await updateIssueWorktreeDelivery({
+        branch: input.branch,
+        issueNumber: input.intent.issueNumber,
+        path: input.worktreePath,
+        projectRoot: context.root,
+        status: 'merged',
+    });
+    return merged;
+}
+export async function mergePr(context, input) {
+    const row = getIssueWorktreeStrict(input.issueNumber, context.root);
+    const receiptRoot = existsSync(row.path) ? row.path : context.root;
+    const run = receiptRoot === row.path
+        ? loadVerifiedRun(row.path, input.issueNumber)
+        : loadRemovedMergedRun(context.root, input.issueNumber);
+    const head = run.classification.head;
+    const publication = loadPublication(receiptRoot, input.issueNumber, head.sha);
+    if (publication.prNumber !== input.prNumber)
+        throw new DeliveryError('Merge PR does not match publication receipt.');
+    const existingPath = mergePath(receiptRoot, input.issueNumber, head.sha);
+    const existing = readOptionalPrivate(existingPath, (value) => MergeSchema.parse(value));
+    if (existing) {
+        const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: input.prNumber })).data;
+        if (existing.prNumber !== input.prNumber ||
+            existing.issueNumber !== input.issueNumber ||
+            existing.headSha !== head.sha ||
+            pr.state !== 'closed' ||
+            !pr.merged_at ||
+            pr.head.sha !== head.sha ||
+            pr.head.ref !== row.branch ||
+            pr.merge_commit_sha !== existing.mergeSha) {
+            throw new DeliveryError('Merged PR readback disagrees with terminal receipt.');
+        }
+        const intent = readOptionalPrivate(mergeIntentPath(receiptRoot, input.issueNumber, head.sha), (value) => MergeIntentSchema.parse(value));
+        if (!intent || intent.intentId !== existing.intentId)
+            throw new DeliveryError('Terminal merge lacks its exact intent.');
+        const result = await readMergedResult(context, intent, existing.mergeSha);
+        if (result.mergeTree !== existing.mergeTree)
+            throw new DeliveryError('Terminal merge tree changed.');
+        const { schemaVersion: _version, ...intentContent } = intent;
+        const expected = { ...intentContent, ...result, schemaVersion: 'ai-delivery.merge@3' };
+        if (existing.mergeId !== digestValue(expected))
+            throw new DeliveryError('Terminal merge receipt disagrees with its intent.');
+        await updateIssueWorktreeDelivery({
+            branch: row.branch,
+            issueNumber: input.issueNumber,
+            path: row.path,
+            projectRoot: context.root,
+            status: 'merged',
+        });
+        return existing;
+    }
+    if (receiptRoot !== row.path) {
+        throw new DeliveryError('Removed merged worktree lacks its terminal merge receipt.');
+    }
+    const intentPath = mergeIntentPath(row.path, input.issueNumber, head.sha);
+    const prepared = readOptionalPrivate(intentPath, (value) => MergeIntentSchema.parse(value));
+    const attemptPath = mergeAttemptPath(row.path, input.issueNumber, head.sha);
+    const priorAttempt = readOptionalPrivate(attemptPath, (value) => MergeAttemptSchema.parse(value));
+    const priorResult = readOptionalPrivate(mergeResultPath(row.path, input.issueNumber, head.sha), (value) => MergeResultSchema.parse(value));
+    if ((priorAttempt !== null || priorResult !== null) && prepared === null) {
+        throw new DeliveryError('Merge operation record lacks its prepared intent.');
+    }
+    const review = loadSubmittedReview(row.path, input.issueNumber, head.sha);
+    if (!review || review.prNumber !== input.prNumber || review.publicationEvidenceId !== publication.evidenceId) {
+        throw new DeliveryError('Exact publication lacks its bound submitted independent review.');
+    }
+    await assertSubmittedReviewCurrent(context, review);
+    if (prepared) {
+        if (prepared.issueNumber !== input.issueNumber ||
+            prepared.prNumber !== input.prNumber ||
+            prepared.headSha !== head.sha ||
+            prepared.headTree !== head.tree ||
+            prepared.reviewReceiptId !== review.receiptId ||
+            prepared.headBranch !== row.branch ||
+            prepared.baseSha !== run.classification.base.sha ||
+            (input.strategy !== undefined && input.strategy !== prepared.strategy)) {
+            throw new DeliveryError('Prepared merge intent disagrees with this retry.');
+        }
+        if (priorAttempt !== null) {
+            const expected = await expectedMergeAttempt(context, prepared);
+            if (priorAttempt.attemptId !== expected.attemptId ||
+                (priorResult !== null && priorResult.attemptId !== priorAttempt.attemptId)) {
+                throw new DeliveryError('Merge attempt disagrees with its exact source, operation or author.');
+            }
+            const remote = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: input.prNumber })).data;
+            if (remote.state !== 'closed' || !remote.merged_at) {
+                throw new DeliveryError('Merge mutation was attempted; remote readback is unresolved. Retry readback without another mutation.');
+            }
+            return persistMergedResult(context, {
+                branch: row.branch,
+                intent: prepared,
+                path: existingPath,
+                worktreePath: row.path,
+                ...(priorResult === null ? {} : { expectedSha: priorResult.mergeSha }),
+            });
+        }
+        if (priorResult !== null)
+            throw new DeliveryError('Merge result lacks its bound attempt.');
+        const remote = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: input.prNumber })).data;
+        if (remote.state === 'closed' && remote.merged_at) {
+            return persistMergedResult(context, {
+                branch: row.branch,
+                intent: prepared,
+                path: existingPath,
+                worktreePath: row.path,
+            });
+        }
+        if (remote.state !== 'open' ||
+            remote.head.sha !== head.sha ||
+            remote.head.ref !== row.branch ||
+            remote.base.ref !== prepared.baseBranch ||
+            remote.base.sha !== prepared.baseSha) {
+            throw new DeliveryError('Prepared merge retry disagrees with the remote PR.');
+        }
+    }
+    const currentPublication = await createIssuePhaseEvidence({
+        ...(run.classification.risk === 'high'
+            ? {
+                approval: reviewArtifactApproval({
+                    artifact: review.artifact,
+                    classification: run.classification,
+                    config: context.config,
+                    issueNumber: input.issueNumber,
+                    prNumber: input.prNumber,
+                }),
+            }
+            : {}),
+        issueNumber: input.issueNumber,
+        phase: 'publish',
+        repoRoot: row.path,
+    });
+    if (currentPublication.evidenceId !== publication.evidenceId) {
+        throw new DeliveryError('Publication evidence changed after formal review.');
+    }
+    const readback = await checkPrMergeability(context, input.prNumber, head.sha);
+    if (readback.baseSha !== run.classification.base.sha || readback.headBranch !== row.branch) {
+        throw new DeliveryError('PR base or registered head drifted after verification.');
+    }
+    const approval = {
+        authorIdentity: context.config.roles.author.identity,
+        reviewerIdentity: context.config.roles.reviewer.identity,
+        diffScopeHash: review.artifact.diffScopeHash,
+        head,
+        result: 'approved',
+        reviewReceiptId: review.receiptId,
+    };
+    const evidence = await createIssuePhaseEvidence({
+        approval,
+        issueNumber: input.issueNumber,
+        mergeReadback: {
+            blockedBy: readback.blockedBy,
+            checksPassed: readback.checksPassed,
+            head,
+            mergeable: true,
+            observedAt: new Date().toISOString(),
+        },
+        phase: 'merge',
+        repoRoot: row.path,
+    });
+    const loaded = loadDeliveryConfig(row.path);
+    const selected = await loadSelectedRepositoryPolicy({
+        repoRoot: row.path,
+        policySourcePath: loaded.config.policy.module,
+    });
+    const boundary = validateRepositoryPolicyBoundary({
+        classification: run.classification,
+        configDigest: loaded.configDigest,
+        currentBase: run.classification.base,
+        currentHead: head,
+        phase: 'merge',
+        policy: selected.policy,
+        policySourcePath: loaded.config.policy.module,
+        repoRoot: row.path,
+        stageReceiptIds: run.aggregate.stages.map((stage) => ({ stageId: stage.stageId, receiptId: stage.receiptId })),
+    });
+    if (boundary.additionalConstraints.exactBaseHeadLease && input.strategy && input.strategy !== 'merge') {
+        throw new DeliveryError('Exact base/head lease requires merge-commit strategy.');
+    }
+    const strategy = boundary.additionalConstraints.exactBaseHeadLease
+        ? 'merge'
+        : (input.strategy ?? prepared?.strategy ?? 'squash');
+    const intentContent = {
+        baseBranch: readback.baseBranch,
+        baseSha: readback.baseSha,
+        exactBaseHeadLease: boundary.additionalConstraints.exactBaseHeadLease,
+        evidenceId: prepared?.evidenceId ?? evidence.evidenceId,
+        headBranch: readback.headBranch,
+        headSha: head.sha,
+        headTree: head.tree,
+        issueNumber: input.issueNumber,
+        prNumber: input.prNumber,
+        reviewReceiptId: review.receiptId,
+        schemaVersion: 'ai-delivery.merge-intent@2',
+        strategy,
+    };
+    const intent = MergeIntentSchema.parse({ ...intentContent, intentId: digestValue(intentContent) });
+    if (prepared && prepared.intentId !== intent.intentId) {
+        throw new DeliveryError('Prepared merge intent no longer matches reviewed inputs.');
+    }
+    if (!prepared)
+        writePrivateJsonFileAtomically(intentPath, intent);
+    const attempt = await expectedMergeAttempt(context, intent);
+    let mergeSha;
+    if (boundary.additionalConstraints.exactBaseHeadLease) {
+        mergeSha = await mergeWithExactLease(context, {
+            baseBranch: readback.baseBranch,
+            baseSha: readback.baseSha,
+            headBranch: readback.headBranch,
+            headSha: head.sha,
+            headTree: head.tree,
+            title: readback.title,
+            prNumber: input.prNumber,
+            worktreePath: row.path,
+            beforeMutation: () => writePrivateJsonFileAtomically(attemptPath, attempt),
+            onPreparedMergeCommit: (sha) => persistMergeResult(row.path, intent, attempt, sha),
+        });
+    }
+    else {
+        writePrivateJsonFileAtomically(attemptPath, attempt);
+        mergeSha = (await context.clients.rest.pulls.merge({
+            ...context.repo,
+            pull_number: input.prNumber,
+            sha: head.sha,
+            merge_method: strategy,
+        })).data.sha;
+    }
+    persistMergeResult(row.path, intent, attempt, mergeSha);
+    return persistMergedResult(context, {
+        branch: row.branch,
+        intent,
+        path: existingPath,
+        worktreePath: row.path,
+        expectedSha: Sha.parse(mergeSha),
+    });
+}
+export async function finishIssue(context, input) {
+    const matches = listWorktreesStrict(context.root).filter((entry) => entry.type === 'issue' && entry.issueNumber === input.issueNumber);
+    if (matches.length === 0)
+        return readCompletedIssue(context, input);
+    if (matches.length !== 1)
+        throw new DeliveryError('Issue has duplicate worktree registry rows.');
+    const row = getIssueWorktreeStrict(input.issueNumber, context.root);
+    const metadata = await getConfiguredNativeIssueMetadata({
+        issueNumber: input.issueNumber,
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        rest: context.clients.rest,
+        settings: nativeIssueSettingsFromDeliveryConfig(context.config),
+    });
+    if (metadata.points === undefined || !context.config.native.points.values.includes(String(metadata.points))) {
+        throw new DeliveryError('Executable issue requires configured native Points before finish.');
+    }
+    const points = metadata.points;
+    const merge = await mergePr(context, input);
+    const review = loadSubmittedReview(existsSync(row.path) ? row.path : context.root, input.issueNumber, merge.headSha);
+    if (!review)
+        throw new DeliveryError('Terminal delivery requires the submitted review receipt.');
+    const issue = (await context.clients.rest.issues.get({ ...context.repo, issue_number: input.issueNumber })).data;
+    if (issue.state !== 'closed')
+        await context.clients.rest.issues.update({
+            ...context.repo,
+            issue_number: input.issueNumber,
+            state: 'closed',
+        });
+    const closed = (await context.clients.rest.issues.get({ ...context.repo, issue_number: input.issueNumber })).data;
+    if (closed.state !== 'closed')
+        throw new DeliveryError('Issue close readback failed.');
+    await syncIssueProjectStatus({
+        graphql: context.clients.graphql,
+        issueNodeId: closed.node_id,
+        org: context.config.native.organization,
+        settings: projectSettingsFromDeliveryConfig(context.config),
+        status: 'Done',
+    });
+    const branch = baseBranch(context.root);
+    await fetchMergedBase(context, branch);
+    const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: input.prNumber })).data;
+    const [remoteBase, remoteHead] = await Promise.all([
+        context.clients.rest.git.getRef({ ...context.repo, ref: `heads/${branch}` }),
+        context.clients.rest.git.getRef({ ...context.repo, ref: `heads/issue/${input.issueNumber}` }).catch((error) => {
+            if (error.status === 404)
+                return null;
+            throw error;
+        }),
+    ]);
+    if (pr.state !== 'closed' ||
+        !pr.merged_at ||
+        pr.merge_commit_sha !== merge.mergeSha ||
+        pr.head.sha !== merge.headSha ||
+        pr.head.ref !== `issue/${input.issueNumber}` ||
+        pr.base.ref !== branch)
+        throw new DeliveryError('Merged PR drifted before cleanup.');
+    const attestation = {
+        baseBranch: merge.baseBranch,
+        baseSha: merge.baseSha,
+        headBranch: merge.headBranch,
+        headSha: merge.headSha,
+        mergeSha: merge.mergeSha,
+        mergeTree: merge.mergeTree,
+        remoteBaseSha: remoteBase.data.object.sha,
+        remoteHeadSha: remoteHead?.data.object.sha ?? null,
+        strategy: merge.strategy,
+    };
+    const mergedAt = pr.merged_at;
+    if (typeof mergedAt !== 'string' || Date.parse(mergedAt) < Date.parse(row.createdAt)) {
+        throw new DeliveryError('Terminal delivery timeline is invalid.');
+    }
+    await cleanupMergedIssueWorktree({
+        issueNumber: input.issueNumber,
+        repoRoot: context.root,
+        merge: attestation,
+        afterRemoval: async () => {
+            const terminalCleanupAt = new Date().toISOString();
+            const metrics = review.artifact.deliveryMetrics;
+            await recordMergedDelivery({
+                blockerTimeMs: metrics?.blockerTimeMs ?? null,
+                cycleTimeMs: Date.parse(mergedAt) - Date.parse(row.createdAt),
+                firstPassApproved: metrics === undefined ? null : metrics.reviewRound === 1,
+                issueNumber: input.issueNumber,
+                mergedAt,
+                mergeSha: merge.mergeSha,
+                points,
+                recordedAt: terminalCleanupAt,
+                repository: `${context.repo.owner}/${context.repo.repo}`,
+                reviewRounds: metrics?.reviewRound ?? null,
+                schemaVersion: 'ai-delivery.delivery-record@1',
+                terminalCleanupAt,
+            }, context.root);
+        },
+    });
+    return { mergeSha: merge.mergeSha, issueClosed: true, cleaned: true };
+}
+async function readCompletedIssue(context, input) {
+    const pr = (await context.clients.rest.pulls.get({ ...context.repo, pull_number: input.prNumber })).data;
+    if (pr.state !== 'closed' || !pr.merged_at || !pr.merge_commit_sha || pr.head.ref !== `issue/${input.issueNumber}`) {
+        throw new DeliveryError('Absent issue worktree lacks an exact completed PR.');
+    }
+    const receipt = readOptionalPrivate(mergePath(context.root, input.issueNumber, pr.head.sha), (value) => MergeSchema.parse(value));
+    const intent = readOptionalPrivate(mergeIntentPath(context.root, input.issueNumber, pr.head.sha), (value) => MergeIntentSchema.parse(value));
+    if (!receipt ||
+        !intent ||
+        receipt.issueNumber !== input.issueNumber ||
+        receipt.prNumber !== input.prNumber ||
+        receipt.headSha !== pr.head.sha ||
+        receipt.mergeSha !== pr.merge_commit_sha ||
+        receipt.intentId !== intent.intentId) {
+        throw new DeliveryError('Absent issue worktree lacks exact terminal merge receipts.');
+    }
+    const result = await readMergedResult(context, intent, receipt.mergeSha);
+    const { schemaVersion: _version, ...intentContent } = intent;
+    if (result.mergeTree !== receipt.mergeTree ||
+        receipt.mergeId !== digestValue({ ...intentContent, ...result, schemaVersion: 'ai-delivery.merge@3' })) {
+        throw new DeliveryError('Completed merge receipt disagrees with its intent or remote result.');
+    }
+    const records = getDeliveryRecords(context.root).filter((record) => record.repository === `${context.repo.owner}/${context.repo.repo}` &&
+        record.issueNumber === input.issueNumber &&
+        record.mergeSha === receipt.mergeSha);
+    if (records.length !== 1)
+        throw new DeliveryError('Completed issue lacks one exact terminal delivery record.');
+    const issue = (await context.clients.rest.issues.get({ ...context.repo, issue_number: input.issueNumber })).data;
+    if (issue.state !== 'closed' || 'pull_request' in issue) {
+        throw new DeliveryError('Completed issue is not closed.');
+    }
+    const project = await getIssueProjectStatus({
+        graphql: context.clients.graphql,
+        issueNodeId: issue.node_id,
+        org: context.config.native.organization,
+        settings: projectSettingsFromDeliveryConfig(context.config),
+    });
+    if (project?.status !== 'Done')
+        throw new DeliveryError('Completed issue Project status is not Done.');
+    return { mergeSha: receipt.mergeSha, issueClosed: true, cleaned: true };
+}
+//# sourceMappingURL=pr.js.map