@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/dist/lib/platform/pull-requests.js

@@ -4,12 +4,13 @@ import { parseTaskFrontmatter } from '../task/frontmatter.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { extractSection } from '../task/sections.js';
 import { captureTaskWriteMetadata, writeTask } from '../task/write.js';
-import { inspectPlatformChangeRequest, registerPlatformCapabilities } from './adapters.js';
+import { inspectPlatformChangeRequest, inspectPlatformIssueClosingChangeRequests, registerPlatformCapabilities } from './adapters.js';
 import { parseGitHubRemote, resolvePlatformContext } from './context.js';
 import { createGitHubClient } from './github-client.js';
 import { inspectPlatformIssue } from './issues.js';
 import { planPullRequestMetadata } from './pull-request-metadata.js';
 import { platformResult } from './types.js';
+import { inspectCompletionArtifacts } from '../task/finalization-artifacts.js';
 function result(status, taskId, issueNumber, prNumber, overrides = {}) {
     return {
         ...platformResult(status),
@@ -18,6 +19,17 @@ function result(status, taskId, issueNumber, prNumber, overrides = {}) {
         ...overrides
     };
 }
+function externalResult(base, overrides = {}) {
+    return {
+        ...base,
+        mode: null,
+        authorization: null,
+        candidates: [],
+        eligible: [],
+        selected: null,
+        ...overrides
+    };
+}
 function normalizePullRequest(remote, repository) {
     const number = Number(remote.number);
     const headRepository = remote.head?.repo?.full_name;
@@ -25,6 +37,12 @@ function normalizePullRequest(remote, repository) {
     if (!Number.isInteger(number) || number <= 0 || !remote.node_id || !remote.html_url ||
         !remote.head?.ref || !remote.head.sha || !headRepository || !remote.base?.ref || !baseRepository)
         return null;
+    const mergeabilityDetail = remote.mergeable_state?.trim().toLowerCase() || null;
+    const mergeability = remote.mergeable === false
+        ? { state: 'conflicting', detail: mergeabilityDetail }
+        : remote.mergeable === true && mergeabilityDetail !== 'dirty'
+            ? { state: 'mergeable', detail: mergeabilityDetail }
+            : { state: 'unknown', detail: mergeabilityDetail };
     return {
         repository,
         number,
@@ -40,9 +58,141 @@ function normalizePullRequest(remote, repository) {
         mergeCommitSha: remote.merge_commit_sha || null,
         labels: (remote.labels || []).map((label) => typeof label === 'string' ? label : label.name || '').filter(Boolean).sort(),
         assignees: (remote.assignees || []).map((assignee) => assignee.login || '').filter(Boolean).sort(),
-        milestone: remote.milestone?.title || null
+        milestone: remote.milestone?.title || null,
+        mergeability
     };
 }
+function normalizeClosingPullRequest(node, repository) {
+    return normalizePullRequest({
+        number: node.number,
+        node_id: node.id,
+        html_url: node.url,
+        state: node.state === 'OPEN' ? 'open' : 'closed',
+        title: node.title,
+        body: node.body,
+        draft: node.isDraft,
+        head: { ref: node.headRefName, sha: node.headRefOid, repo: node.headRepository ? { full_name: node.headRepository.nameWithOwner } : null },
+        base: { ref: node.baseRefName, sha: node.baseRefOid, repo: node.baseRepository ? { full_name: node.baseRepository.nameWithOwner } : null },
+        merged_at: node.mergedAt,
+        merge_commit_sha: node.mergeCommit?.oid,
+        labels: node.labels?.nodes,
+        assignees: node.assignees?.nodes,
+        milestone: node.milestone
+    }, repository);
+}
+function repositoryKey(repository) {
+    return repository.trim().toLowerCase();
+}
+function identitySignature(pullRequest) {
+    return [
+        pullRequest.repository, pullRequest.number, pullRequest.nodeId, pullRequest.url,
+        pullRequest.head.repository, pullRequest.head.ref, pullRequest.head.sha,
+        pullRequest.base.repository, pullRequest.base.ref, pullRequest.base.sha,
+        pullRequest.mergedAt || '', pullRequest.mergeCommitSha || ''
+    ].join('|');
+}
+function hasCompleteExternalIdentity(pullRequest) {
+    const required = [
+        pullRequest.repository, pullRequest.nodeId, pullRequest.url,
+        pullRequest.head.repository, pullRequest.head.ref, pullRequest.head.sha,
+        pullRequest.base.repository, pullRequest.base.ref, pullRequest.base.sha
+    ];
+    return Number.isInteger(pullRequest.number) && pullRequest.number > 0 &&
+        required.every((value) => Boolean(value?.trim())) &&
+        Boolean(pullRequest.mergedAt) === Boolean(pullRequest.mergeCommitSha);
+}
+function selectExternalPullRequest(candidates, repository, existingPrNumber, explicitPrNumber) {
+    const invalid = candidates.find((candidate) => !hasCompleteExternalIdentity(candidate));
+    if (invalid)
+        return {
+            status: 'failed', code: 'PR_IDENTITY_INVALID',
+            message: `Closing PR #${invalid.number} lacks required identity`, candidates, eligible: []
+        };
+    const byNumber = new Map();
+    for (const candidate of candidates) {
+        const signature = identitySignature(candidate);
+        const prior = byNumber.get(candidate.number);
+        if (prior && prior !== signature)
+            return {
+                status: 'failed', code: 'PR_IDENTITY_INVALID',
+                message: `Closing PR #${candidate.number} has conflicting identities`, candidates, eligible: []
+            };
+        byNumber.set(candidate.number, signature);
+    }
+    const unique = candidates.filter((candidate, index) => candidates.findIndex((other) => other.number === candidate.number) === index);
+    const wantedRepository = repositoryKey(repository);
+    const eligible = unique.filter((candidate) => repositoryKey(candidate.repository) === wantedRepository &&
+        repositoryKey(candidate.base.repository) === wantedRepository &&
+        Boolean(candidate.mergedAt && candidate.mergeCommitSha));
+    if (explicitPrNumber !== null) {
+        const selected = unique.find((candidate) => candidate.number === explicitPrNumber);
+        if (!selected)
+            return { status: 'failed', code: 'PR_NOT_FOUND', message: `PR #${explicitPrNumber} is not a closing PR`, candidates, eligible };
+        if (!eligible.some((candidate) => candidate.number === explicitPrNumber)) {
+            return { status: 'failed', code: 'PR_IDENTITY_INVALID', message: `PR #${explicitPrNumber} is not an eligible merged PR`, candidates, eligible };
+        }
+        if (existingPrNumber !== null && existingPrNumber !== explicitPrNumber) {
+            return { status: 'failed', code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${existingPrNumber}`, candidates, eligible };
+        }
+        return { status: 'selected', source: 'explicit', selected, candidates, eligible };
+    }
+    if (existingPrNumber !== null && eligible.length === 1 && existingPrNumber !== eligible[0].number) {
+        return { status: 'failed', code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${existingPrNumber}`, candidates, eligible };
+    }
+    if (eligible.length === 0)
+        return { status: 'normal', candidates, eligible: [] };
+    if (eligible.length > 1)
+        return {
+            status: 'failed', code: 'PR_IDENTITY_AMBIGUOUS',
+            message: 'Multiple eligible merged closing pull requests were found', candidates, eligible
+        };
+    return { status: 'selected', source: 'unique', selected: eligible[0], candidates, eligible };
+}
+const CLOSING_PULL_REQUESTS_QUERY = `query($owner:String!,$name:String!,$issue:Int!,$cursor:String){repository(owner:$owner,name:$name){issue(number:$issue){closedByPullRequestsReferences(first:100,after:$cursor){nodes{number id url state title body isDraft headRefName headRefOid headRepository{nameWithOwner} baseRefName baseRefOid baseRepository{nameWithOwner} mergedAt mergeCommit{oid} labels(first:100){nodes{name}} assignees(first:100){nodes{login}} milestone{title}} pageInfo{hasNextPage endCursor}}}}}`;
+function inspectGitHubIssueClosingChangeRequests(client, repository, issueNumber, cwd) {
+    const [owner, name] = repository.split('/');
+    if (!owner || !name || !Number.isInteger(issueNumber) || issueNumber <= 0)
+        return {
+            ok: false,
+            error: { code: 'PR_IDENTITY_INVALID', message: 'Repository or Issue identity is invalid', retryable: false }
+        };
+    const candidates = [];
+    let cursor = null;
+    for (;;) {
+        const args = [
+            'api', 'graphql', '-f', `query=${CLOSING_PULL_REQUESTS_QUERY}`,
+            '-F', `owner=${owner}`, '-F', `name=${name}`, '-F', `issue=${issueNumber}`
+        ];
+        if (cursor)
+            args.push('-F', `cursor=${cursor}`);
+        const response = client.json(args, { cwd });
+        if (!response.ok)
+            return response;
+        const connection = response.value?.data?.repository?.issue?.closedByPullRequestsReferences;
+        if (!connection || !Array.isArray(connection.nodes) || !connection.pageInfo)
+            return {
+                ok: false,
+                error: { code: 'PR_IDENTITY_INVALID', message: 'Closing pull request response is incomplete', retryable: false }
+            };
+        for (const node of connection.nodes) {
+            const normalized = normalizeClosingPullRequest(node, repository);
+            if (!normalized)
+                return {
+                    ok: false,
+                    error: { code: 'PR_IDENTITY_INVALID', message: 'Closing pull request identity is incomplete', retryable: false }
+                };
+            candidates.push(normalized);
+        }
+        if (!connection.pageInfo.hasNextPage)
+            return { ok: true, value: candidates };
+        if (!connection.pageInfo.endCursor || connection.pageInfo.endCursor === cursor)
+            return {
+                ok: false,
+                error: { code: 'PR_IDENTITY_INVALID', message: 'Closing pull request pagination cursor is invalid', retryable: false }
+            };
+        cursor = connection.pageInfo.endCursor;
+    }
+}
 function expectedHead(repository, head) {
     const colon = head.indexOf(':');
     if (colon === -1)
@@ -179,6 +329,9 @@ registerPlatformCapabilities('github', {
     inspectChangeRequest({ client, repository, number, cwd }) {
         return inspectGitHubPullRequest(client || createGitHubClient(), repository, number, cwd);
     },
+    inspectIssueClosingChangeRequests({ client, repository, issueNumber, cwd }) {
+        return inspectGitHubIssueClosingChangeRequests(client || createGitHubClient(), repository, issueNumber, cwd);
+    },
     resolveChangeRequestGitEvidence(context) {
         return resolveGitHubChangeRequestGitEvidence(context);
     }
@@ -230,6 +383,43 @@ function inspectPlatformPullRequest(taskRef, options = {}) {
         resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value, error: null
     });
 }
+function inspectPlatformPullRequestByNumber(prNumber, options = {}) {
+    const client = options.client || createGitHubClient();
+    const context = resolvePlatformContext({ cwd: options.cwd || process.cwd(), client });
+    const usable = (context.status === 'no-op' || context.status === 'degraded') && context.platform.repository;
+    if (!usable) {
+        return result(context.status, null, null, null, {
+            platform: context.platform, capabilities: context.capabilities, operations: context.operations, error: context.error
+        });
+    }
+    if (!Number.isInteger(prNumber) || prNumber <= 0) {
+        return result('failed', null, null, null, {
+            platform: context.platform, capabilities: context.capabilities,
+            error: { code: 'PR_NUMBER_INVALID', message: 'PR number must be positive', retryable: false }
+        });
+    }
+    const fetched = inspectPlatformChangeRequest(context.platform.type, {
+        cwd: options.cwd || process.cwd(),
+        repository: context.platform.repository,
+        number: prNumber,
+        client
+    });
+    if (!fetched.ok || !fetched.value) {
+        const error = fetched.error || {
+            code: 'PR_INSPECTION_INVALID',
+            message: 'Platform adapter returned no change-request snapshot',
+            retryable: false
+        };
+        return result(error.retryable ? 'blocked' : 'failed', null, null, prNumber, {
+            platform: context.platform, capabilities: context.capabilities,
+            resource: { kind: 'pull-request', number: prNumber }, error
+        });
+    }
+    return result('no-op', null, null, prNumber, {
+        platform: context.platform, capabilities: context.capabilities,
+        resource: { kind: 'pull-request', number: prNumber }, pullRequest: fetched.value, error: null
+    });
+}
 function appendActivity(content, line) {
     const body = extractSection(content, ['活动日志', 'Activity Log']);
     return `${body.replace(/\s+$/, '')}${body.trim() ? '\n' : ''}${line}`;
@@ -291,6 +481,137 @@ function bindPlatformPullRequest(taskRef, options) {
         operations: [{ name: 'task:bind-pr', status: options.dryRun ? 'planned' : written.status === 'no-op' ? 'no-op' : 'applied', reasonCode: null }], error: null
     });
 }
+function externalEvidenceNote(issueNumber, source, pullRequest) {
+    return [
+        `authorization=${source}`,
+        externalIdentityEvidenceNote(issueNumber, pullRequest)
+    ].join('; ');
+}
+function externalIdentityEvidenceNote(issueNumber, pullRequest) {
+    return [
+        `issue=#${issueNumber}`,
+        `pr=#${pullRequest.number}`,
+        `url=${pullRequest.url}`,
+        `base=${pullRequest.base.repository}:${pullRequest.base.ref}@${pullRequest.base.sha}`,
+        `head=${pullRequest.head.repository}:${pullRequest.head.ref}@${pullRequest.head.sha}`,
+        `mergedAt=${pullRequest.mergedAt}`,
+        `mergeCommitSha=${pullRequest.mergeCommitSha}`
+    ].join('; ');
+}
+function resolveExternalPullRequest(taskRef, options) {
+    const base = resolvedContext(taskRef, options);
+    if (!base.ok)
+        return externalResult(base.output);
+    const inventory = inspectCompletionArtifacts(base.resolved.taskId, { repoRoot: base.resolved.repoRoot });
+    if (inventory.status === 'failed')
+        return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            error: { code: inventory.error?.code || 'ARTIFACT_TOPOLOGY_CONFLICT', message: inventory.error?.message || 'Completion artifact inventory failed', retryable: false }
+        }));
+    if (inventory.artifacts.length > 0) {
+        if (options.pr !== undefined)
+            return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+                platform: base.context.platform,
+                capabilities: base.context.capabilities,
+                error: { code: 'EXTERNAL_DELIVERY_NOT_APPLICABLE', message: 'External PR selection is only valid when the completion inventory is empty', retryable: false }
+            }), { mode: 'normal' });
+        return externalResult(result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            operations: [{ name: 'external-pr:inventory', status: 'no-op', reasonCode: 'CANONICAL_ARTIFACTS_PRESENT' }],
+            error: null
+        }), { mode: 'normal' });
+    }
+    if (!base.issueNumber)
+        return externalResult(result('failed', base.resolved.taskId, null, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            error: { code: 'EXTERNAL_DELIVERY_ISSUE_REQUIRED', message: 'External delivery requires a valid issue_number', retryable: false }
+        }));
+    const inspected = inspectPlatformIssueClosingChangeRequests(base.context.platform.type, {
+        cwd: base.resolved.repoRoot,
+        repository: base.context.platform.repository,
+        issueNumber: base.issueNumber,
+        client: base.client
+    });
+    if (!inspected.ok || !inspected.value) {
+        const error = inspected.error || { code: 'PR_IDENTITY_INVALID', message: 'Closing PR inspection returned no candidates', retryable: false };
+        return externalResult(result(error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform, capabilities: base.context.capabilities, error
+        }));
+    }
+    const selected = selectExternalPullRequest(inspected.value, base.context.platform.repository, base.prNumber, options.pr ?? null);
+    if (selected.status === 'normal')
+        return externalResult(result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            operations: [{ name: 'external-pr:select', status: 'no-op', reasonCode: 'NO_ELIGIBLE_CANDIDATE' }],
+            error: null
+        }), { mode: 'normal', candidates: selected.candidates, eligible: selected.eligible });
+    if (selected.status === 'failed')
+        return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            error: { code: selected.code, message: selected.message, retryable: false }
+        }), { candidates: selected.candidates, eligible: selected.eligible });
+    const note = externalEvidenceNote(base.issueNumber, selected.source, selected.selected);
+    const identityNote = externalIdentityEvidenceNote(base.issueNumber, selected.selected);
+    const activityEntry = `**Bind External PR** by ${options.agent} — ${note}`;
+    const auditLines = base.content.split(/\r?\n/).filter((line) => line.includes('**Bind External PR**'));
+    const alreadyAudited = auditLines.some((line) => line.endsWith(identityNote));
+    if (auditLines.length > 0 && !alreadyAudited)
+        return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            pullRequest: selected.selected,
+            error: { code: 'PR_BIND_CONFLICT', message: 'Existing external PR audit evidence conflicts with the selected identity', retryable: false }
+        }), { candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+    if (alreadyAudited && base.prNumber !== selected.selected.number)
+        return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            pullRequest: selected.selected,
+            error: { code: 'PR_BIND_CONFLICT', message: 'External PR audit evidence does not match the task binding', retryable: false }
+        }), { candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+    if (base.prNumber === selected.selected.number && alreadyAudited) {
+        return externalResult(result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            resource: { kind: 'pull-request', number: selected.selected.number },
+            pullRequest: selected.selected,
+            operations: [{ name: 'task:bind-external-pr', status: 'no-op', reasonCode: 'EVIDENCE_ALREADY_RECORDED' }],
+            error: null
+        }), { mode: 'external', authorization: selected.source, candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+    }
+    const metadata = captureTaskWriteMetadata();
+    const write = writeTask({
+        taskRef: base.resolved.taskId,
+        expectedState: 'active',
+        dryRun: options.dryRun,
+        mutations: [
+            { kind: 'frontmatter', set: { pr_number: selected.selected.number, pr_status: 'created', assigned_to: options.agent } },
+            { kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: '活动日志', body: appendActivity(base.content, `- ${metadata.timestamp} — ${activityEntry}`) }
+        ]
+    }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
+    if (write.status === 'failed')
+        return externalResult(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform,
+            capabilities: base.context.capabilities,
+            pullRequest: selected.selected,
+            error: { code: write.error.code, message: write.error.message, retryable: false }
+        }), { candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+    const operationStatus = options.dryRun ? 'planned' : write.status === 'applied' ? 'applied' : 'no-op';
+    return externalResult(result(operationStatus, base.resolved.taskId, base.issueNumber, options.dryRun ? base.prNumber : selected.selected.number, {
+        changed: !options.dryRun && write.changed,
+        platform: base.context.platform,
+        capabilities: base.context.capabilities,
+        resource: { kind: 'pull-request', number: selected.selected.number },
+        pullRequest: selected.selected,
+        operations: [{ name: 'task:bind-external-pr', status: operationStatus, reasonCode: null }],
+        error: null
+    }), { mode: 'external', authorization: selected.source, candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
+}
 function createPlatformPullRequest(taskRef, options) {
     const base = resolvedContext(taskRef, options);
     if (!base.ok)
@@ -440,5 +761,5 @@ function syncPlatformPullRequest(taskRef, options) {
         operations: operations.map((operation) => operation.status === 'planned' ? { ...operation, status: 'applied' } : operation), error: null
     });
 }
-export { bindPlatformPullRequest, createPlatformPullRequest, inspectGitHubPullRequest, inspectPlatformPullRequest, normalizePullRequest, resolveGitHubChangeRequestGitEvidence, selectPullRequest, syncPlatformPullRequest };
+export { bindPlatformPullRequest, createPlatformPullRequest, inspectGitHubPullRequest, inspectGitHubIssueClosingChangeRequests, inspectPlatformPullRequest, inspectPlatformPullRequestByNumber, normalizePullRequest, resolveGitHubChangeRequestGitEvidence, resolveExternalPullRequest, selectExternalPullRequest, selectPullRequest, syncPlatformPullRequest };
 //# sourceMappingURL=pull-requests.js.map

package/dist/lib/platform/release-notes.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { resolvePlatformContext } from './context.js';
 import { fetchGitHubReleaseNoteData, publishGitHubReleaseNotes } from './github-release-notes.js';
 const unsupportedError = {
@@ -8,6 +9,77 @@ const unsupportedError = {
     message: 'Release notes are not supported for the configured platform',
     retryable: false
 };
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+function releaseNoteFailure(code, message) {
+    return {
+        status: 'failed',
+        changed: false,
+        operation: null,
+        url: null,
+        error: { code, message, retryable: false }
+    };
+}
+function normalizeReleaseNoteBytes(input) {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(input);
+    const normalized = text.replace(/\r\n?/g, '\n').replace(/\n*$/, '') + '\n';
+    return Buffer.from(normalized, 'utf8');
+}
+function releaseNoteSha256(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+function isWithin(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+function stageReleaseNotes(input, options = {}) {
+    if (!input.notesFile || input.notesFile === '-') {
+        return { status: 'failed', changed: false, notesFile: null, sha256: null, byteLength: null, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'notes-file must identify an existing external file', retryable: false } };
+    }
+    const requestedPath = path.resolve(input.notesFile);
+    let notesFile;
+    let sourceStat;
+    try {
+        if (fs.lstatSync(requestedPath).isSymbolicLink())
+            throw new Error('symbolic links are not allowed');
+        notesFile = fs.realpathSync(requestedPath);
+        sourceStat = fs.statSync(notesFile);
+        const worktree = fs.realpathSync(path.resolve(options.cwd || process.cwd()));
+        if (!sourceStat.isFile() || isWithin(worktree, notesFile))
+            throw new Error('path is not an external regular file');
+    }
+    catch {
+        return { status: 'failed', changed: false, notesFile: null, sha256: null, byteLength: null, error: { code: 'RELEASE_NOTES_PATH_INVALID', message: 'notes-file must be a regular file outside the current worktree and must not be a symbolic link', retryable: false } };
+    }
+    let original;
+    let normalized;
+    try {
+        original = fs.readFileSync(notesFile);
+        normalized = normalizeReleaseNoteBytes(original);
+    }
+    catch {
+        return { status: 'failed', changed: false, notesFile, sha256: null, byteLength: null, error: { code: 'RELEASE_NOTES_CONTENT_INVALID', message: 'notes-file must contain valid UTF-8', retryable: false } };
+    }
+    const changed = !original.equals(normalized);
+    if (changed) {
+        const temporary = path.join(path.dirname(notesFile), `.${path.basename(notesFile)}.${process.pid}.${Date.now()}.tmp`);
+        try {
+            fs.writeFileSync(temporary, normalized, { flag: 'wx', mode: sourceStat.mode });
+            fs.renameSync(temporary, notesFile);
+        }
+        catch {
+            fs.rmSync(temporary, { force: true });
+            return { status: 'failed', changed: false, notesFile, sha256: null, byteLength: null, error: { code: 'RELEASE_NOTES_STAGE_FAILED', message: 'notes-file could not be staged atomically', retryable: false } };
+        }
+    }
+    return {
+        status: changed ? 'applied' : 'no-op',
+        changed,
+        notesFile,
+        sha256: releaseNoteSha256(normalized),
+        byteLength: normalized.byteLength,
+        error: null
+    };
+}
 function baseResult(status) {
     return {
         status,
@@ -126,8 +198,18 @@ function releaseNoteContext(input, options = {}) {
     };
 }
 function publishReleaseNotes(input, options = {}) {
-    if (!input.tag || !input.title || !input.notesFile) {
-        return { status: 'failed', changed: false, operation: null, url: null, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'tag, title, and notes-file are required', retryable: false } };
+    if (!input.tag || !input.title || !input.notesFile || !SHA256_PATTERN.test(input.expectedSha256)) {
+        return releaseNoteFailure('RELEASE_NOTES_INPUT_INVALID', 'tag, title, notes-file, and expected-sha256 are required');
+    }
+    let actualSha256;
+    try {
+        actualSha256 = releaseNoteSha256(fs.readFileSync(input.notesFile));
+    }
+    catch {
+        return releaseNoteFailure('RELEASE_NOTES_FILE_UNREADABLE', 'notes-file could not be read');
+    }
+    if (actualSha256 !== input.expectedSha256) {
+        return releaseNoteFailure('RELEASE_NOTES_DIGEST_MISMATCH', 'notes-file does not match the confirmed SHA-256 digest');
     }
     const cwd = path.resolve(options.cwd || process.cwd());
     const platformType = options.platformType ?? configuredPlatform(cwd);
@@ -139,5 +221,5 @@ function publishReleaseNotes(input, options = {}) {
     }
     return publishGitHubReleaseNotes({ ...input, repository: context.platform.repository }, { cwd, client: options.client });
 }
-export { publishReleaseNotes, releaseNoteContext };
+export { normalizeReleaseNoteBytes, publishReleaseNotes, releaseNoteContext, releaseNoteSha256, stageReleaseNotes };
 //# sourceMappingURL=release-notes.js.map