@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/platform/pr-checks.ts

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 
 import { parseTypedTaskFrontmatter } from '../task/frontmatter.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
-import type { PlatformCheckSnapshot } from './adapters.ts';
+import type { PlatformCheckSnapshot } from './snapshots.ts';
+import { checkStatusBucket } from './check-status.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
 import { inspectPlatformPullRequest } from './pull-requests.ts';
@@ -33,7 +34,6 @@ type ChecksResult = PlatformResult & {
   resolution?: { status: 'resolved' | 'missing' | 'ambiguous'; runId: number | null; jobId: number | null };
   logs?: { runId: number; jobId?: number; text: string };
 };
-type GitHubClient = PlatformClient;
 type InspectionOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
 type SharedOptions = { cwd?: string; client?: PlatformClient };
 
@@ -56,18 +56,6 @@ function classifyPullRequestReadiness(input: {
   return { state: 'ready', headSha: input.headSha };
 }
 
-function parseRunJobIdentity(detailsUrl: string): { runId: number; jobId: number | null } | null {
-  try {
-    const url = new URL(detailsUrl);
-    if (url.hostname !== 'github.com') return null;
-    const match = url.pathname.match(/\/actions\/runs\/(\d+)(?:\/job\/(\d+))?/);
-    if (!match) return null;
-    return { runId: Number(match[1]), jobId: match[2] ? Number(match[2]) : null };
-  } catch {
-    return null;
-  }
-}
-
 function resolveRunCandidate(candidates: RunCandidate[], headSha: string, checkName: string):
   | { status: 'resolved'; runId: number; jobId: number | null }
   | { status: 'missing' | 'ambiguous'; runId: null; jobId: null } {
@@ -85,41 +73,6 @@ function checksResult(status: PlatformResult['status'], overrides: Partial<Check
   };
 }
 
-function normalizeBucket(value: { bucket?: string; status?: string; state?: string; conclusion?: string }): CheckBucket {
-  const raw = String(value.bucket || value.status || value.conclusion || value.state || '').toLowerCase();
-  if (['pass', 'success', 'successful', 'neutral'].includes(raw)) return 'pass';
-  if (['fail', 'failure', 'failed', 'error', 'timed_out', 'action_required'].includes(raw)) return 'fail';
-  if (['cancel', 'cancelled', 'canceled', 'skipped', 'stale'].includes(raw)) return 'cancel';
-  return 'pending';
-}
-
-function normalizeChecks(value: unknown): CheckSnapshot[] {
-  if (!Array.isArray(value)) return [];
-  return value.flatMap((raw) => {
-    const item = raw as Record<string, unknown>;
-    const name = String(item.name || item.context || '');
-    return name ? [{
-      name,
-      bucket: normalizeBucket(item as { bucket?: string; state?: string; conclusion?: string }),
-      workflow: item.workflow ? String(item.workflow) : null,
-      conclusion: item.conclusion ? String(item.conclusion) : item.state ? String(item.state) : null,
-      detailsUrl: item.link ? String(item.link) : item.detailsUrl ? String(item.detailsUrl) : null,
-      startedAt: item.startedAt ? String(item.startedAt) : null,
-      completedAt: item.completedAt ? String(item.completedAt) : null
-    }] : [];
-  });
-}
-
-function inspectGitHubRequiredChecks(client: GitHubClient, repository: string, number: number, cwd: string) {
-  const inspected = client.json<unknown>([
-    'pr', 'checks', String(number), '--repo', repository,
-    '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'
-  ], { cwd });
-  return inspected.ok
-    ? { ok: true as const, value: normalizeChecks(inspected.value) }
-    : { ok: false as const, error: inspected.error };
-}
-
 async function resolvedTask(taskRef: string, options: InspectionOptions) {
   const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
   if (!resolved.ok) return { ok: false as const, output: checksResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }) };
@@ -141,14 +94,12 @@ async function resolvedTask(taskRef: string, options: InspectionOptions) {
 async function inspectRequiredChecks(taskRef: string, options: InspectionOptions = {}): Promise<ChecksResult> {
   const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
-  return inspectChecksForResolvedTask(base, options);
+  return inspectChecksForResolvedTask(base);
 }
 
 async function inspectChecksForResolvedTask(
-  base: Extract<Awaited<ReturnType<typeof resolvedTask>>, { ok: true }>,
-  options: InspectionOptions
+  base: Extract<Awaited<ReturnType<typeof resolvedTask>>, { ok: true }>
 ): Promise<ChecksResult> {
-  const repository = base.context.platform.repository!;
   {
     const inspected = base.provider.checks?.inspectRequired
       ? await base.provider.checks.inspectRequired({
@@ -164,7 +115,13 @@ async function inspectChecksForResolvedTask(
       pullRequest: base.pullRequest,
       error: providerError(inspected.error, 'PLATFORM_PROVIDER_OPERATION_FAILED')
     });
-    const required = normalizeChecks(inspected.value);
+    const required = inspected.value.map((check): CheckSnapshot => ({
+      name: check.name,
+      bucket: checkStatusBucket(check.status),
+      conclusion: check.conclusion || null,
+      detailsUrl: check.detailsUrl || null,
+      workflow: null, startedAt: null, completedAt: null
+    }));
     const classified = classifyRequiredChecks(required);
     const status = classified.state === 'passed' || classified.state === 'no-required'
       ? 'no-op'
@@ -184,7 +141,7 @@ async function inspectChecksForResolvedTask(
 async function inspectPullRequestReadiness(taskRef: string, options: InspectionOptions = {}): Promise<ChecksResult> {
   const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
-  const checked = await inspectChecksForResolvedTask(base, options);
+  const checked = await inspectChecksForResolvedTask(base);
   const classifiedCodes = new Set(['REQUIRED_CHECKS_PENDING', 'REQUIRED_CHECKS_FAILED', 'REQUIRED_CHECKS_CANCELLED']);
   if (checked.error && !classifiedCodes.has(checked.error.code)) return checked;
   const readiness = classifyPullRequestReadiness({
@@ -271,15 +228,6 @@ async function resolvePlatformCheckRun(taskRef: string, options: SharedOptions &
   }
 }
 
-function fetchCheckLogText(client: GitHubClient, args: string[], cwd: string) {
-  if (!client.text) return { ok: false as const, error: { code: 'PLATFORM_CLIENT_TEXT_UNAVAILABLE', message: 'Platform client does not support text responses', retryable: false } };
-  const fetched = client.text(args, { cwd });
-  if (fetched.ok || args[0] !== 'api' || !/response contains terminal escape sequences/i.test(fetched.error.message)) {
-    return fetched;
-  }
-  return client.text([...args, '--allow-escape-sequences'], { cwd });
-}
-
 async function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions & { run: number; job?: number }): Promise<ChecksResult> {
   const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
@@ -308,17 +256,5 @@ async function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions &
   }
 }
 
-export {
-  classifyPullRequestReadiness,
-  classifyRequiredChecks,
-  fetchCheckLogText,
-  fetchPlatformCheckLogs,
-  inspectGitHubRequiredChecks,
-  inspectRequiredChecks,
-  inspectPullRequestReadiness,
-  parseRunJobIdentity,
-  resolvePlatformCheckRun,
-  resolveRunCandidate,
-  watchPullRequestReadiness
-};
+export { classifyPullRequestReadiness, classifyRequiredChecks, fetchPlatformCheckLogs, inspectRequiredChecks, inspectPullRequestReadiness, resolvePlatformCheckRun, resolveRunCandidate, watchPullRequestReadiness };
 export type { CheckBucket, CheckSnapshot, ChecksResult, ChecksSnapshot, CheckState, ReadinessSnapshot, ReadinessState, RunCandidate };

package/lib/platform/pr-summary.ts

@@ -11,14 +11,16 @@ import type { PrDeliveryFact } from '../task/pr-delivery-fact.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { LoadedContext, PlatformClient } from './context.ts';
 import { normalizeCommentContent } from './issue-comments.ts';
+import { CONTROL_MARKER_PATTERN, escapeHtmlText, sanitizeMarkdownDocument, splitDocumentPlaceholder } from './comment-safety.ts';
 import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
 import type { OperationWarning } from '../task/operation-outcome.ts';
 import { providerError, providerOperationContext, providerStatus, providerResourceToken, resourceIdentityNumber, unsupportedProviderOperation } from './provider-bridge.ts';
-import type { PlatformChangeRequestSnapshot } from './adapters.ts';
+import type { PlatformChangeRequestSnapshot } from './snapshots.ts';
 import type { ChangeRequestSnapshot } from './provider-contract.ts';
 import {
   buildPrChangeReport,
+  CANONICAL_REPORT_PLACEHOLDER,
   readPrChangeReport,
   replaceCanonicalReportPlaceholder,
   runMechanicalChangeReport,
@@ -31,6 +33,8 @@ import type {
   MechanicalChangeReport,
   PrChangeReport
 } from './pr-change-report.ts';
+import { manualValidationFinalSummaryProjectionMatches } from '../task/manual-validation-receipt.ts';
+import { readManualValidationCompletion } from '../task/manual-validation-completion.ts';
 
 type SummaryComment = { id: number | string; body: string };
 type ChangeReportState = 'ready' | 'missing' | 'stale' | 'invalid';
@@ -48,20 +52,28 @@ type PullRequestSummaryResult = PlatformResult & {
 };
 type PullRequestPrimaryResult = 'pr_created' | 'pr_reused' | 'no_op';
 type SummaryOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
+type ManualValidationSummaryOptions = {
+  phase: 'pending' | 'final';
+  transactionId?: string;
+  receiptDigest?: string;
+  prHeadSha?: string;
+  authority?: 'coordinator';
+};
 type ReportWriteResult = PlatformResult & {
   report: { path: string; status: 'written' | 'no-op' | 'planned'; precheckVerdict: 'clear' | 'needs-review'; nextAction: 'watch-pr' | 'review-code' } | null;
 };
+type SummaryCommentStateResult = Omit<PlatformResult, 'comment'> & {
+  task: { id: string | null; prNumber: number | null };
+  pullRequest: PlatformChangeRequestSnapshot | null;
+  comment: SummaryComment | null;
+};
 
 function summaryMarker(taskId: string): string {
   return `<!-- sync-pr:${taskId}:summary -->`;
 }
 
 function escapeSummaryAuditText(value: string): string {
-  return value
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/\r\n?/g, '\n');
+  return escapeHtmlText(value).replace(/\r\n?/g, '\n');
 }
 
 function renderSummaryAuditLine(value: string): string {
@@ -356,6 +368,23 @@ async function summaryContext(taskRef: string, options: SummaryOptions = {}): Pr
   };
 }
 
+async function summaryCommentState(taskRef: string, options: SummaryOptions = {}): Promise<SummaryCommentStateResult> {
+  const context = await summaryContext(taskRef, options);
+  if (!context.task.prNumber || !context.pullRequest) return { ...context, comment: null };
+  const loaded = await resolvePlatformProviderContext({ cwd: options.cwd, client: options.client });
+  if (!loaded.ok || !loaded.value.provider.comments?.list) return { ...context, comment: null };
+  const listed = await loaded.value.provider.comments.list({
+    context: providerOperationContext(loaded.value),
+    parent: providerResourceToken(loaded.value.provider, 'pull-request', String(context.task.prNumber))
+  });
+  if (!listed.ok) return { ...context, comment: null };
+  const matches = listed.value.filter((comment) => comment.body.includes(summaryMarker(context.task.id!)));
+  return {
+    ...context,
+    comment: matches.length === 1 ? { id: /^\d+$/u.test(matches[0]!.id) ? Number(matches[0]!.id) : matches[0]!.id, body: matches[0]!.body } : null
+  };
+}
+
 type ReportWriteOptions = {
   agent: string;
   mechanicalFile: string;
@@ -452,7 +481,7 @@ async function reportWrite(taskRef: string, options: ReportWriteOptions): Promis
 
 async function syncPullRequestSummary(
   taskRef: string,
-  options: { agent: string; body: string; changeReportFile?: string; cwd?: string; client?: PlatformClient; dryRun?: boolean; strict?: boolean; primaryResult: PullRequestPrimaryResult; runtimeVersion?: string }
+  options: { agent: string; body: string; changeReportFile?: string; cwd?: string; client?: PlatformClient; dryRun?: boolean; strict?: boolean; primaryResult: PullRequestPrimaryResult; runtimeVersion?: string; manualValidation?: ManualValidationSummaryOptions; lockAlreadyHeld?: boolean }
 ): Promise<PullRequestSummaryResult> {
   const warningResult = warningResultForPrimary(options.primaryResult);
   let knownPrNumber: number | null = null;
@@ -505,7 +534,7 @@ async function syncPullRequestSummary(
     return preserveFailure(context);
   }
   try {
-    return await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, async () => {
+    const execute = async (): Promise<PullRequestSummaryResult> => {
       const { taskContent, boundFact } = readBoundTaskSnapshot(resolved.taskMdPath);
       if (!boundFact) return {
         ...platformResult('failed', { resource: { kind: 'pull-request', number: null }, error: { code: 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false } }),
@@ -521,6 +550,27 @@ async function syncPullRequestSummary(
       const prNumber = boundPrNumber;
       const initial = await inspectBoundPullRequest(context, resolved.repoRoot, boundPrNumber, loaded.value);
       if (!initial.ok) return fail(initial.status, context, initial.error);
+      const manual = options.manualValidation;
+      const hasFinalManualValidation = /###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)/u.test(options.body);
+      if (hasFinalManualValidation && (!manual || manual.phase !== 'final')) return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires the transaction coordinator', retryable: false }, prNumber);
+      if (manual && (manual.phase === 'pending' ? hasFinalManualValidation : !hasFinalManualValidation)) return fail('failed', context, { code: 'MANUAL_VALIDATION_SUMMARY_PHASE_INVALID', message: 'manual-validation summary phase does not match the requested writer phase', retryable: false }, prNumber);
+      if (manual) {
+        if (manual.phase === 'final' && (!manual.transactionId || !manual.receiptDigest || !manual.prHeadSha || manual.prHeadSha !== initial.value.head.sha)) return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires transaction, receipt, and current head identity', retryable: false }, prNumber);
+        if (manual.phase === 'final') {
+          if (manual.authority !== 'coordinator') return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires coordinator authority', retryable: false }, prNumber);
+          const completion = readManualValidationCompletion(resolved.taskDir, {
+            transactionId: manual.transactionId,
+            taskId: resolved.taskId,
+            prNumber,
+            prHeadSha: initial.value.head.sha,
+            receiptDigest: manual.receiptDigest
+          });
+          if (!completion.ok) return fail('failed', context, platformError(completion.error), prNumber);
+          const { receipt, transaction } = completion.value;
+          if (transaction.phase !== 'final-promotion-in-progress' || !transaction.eventAppended) return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'final summary requires a receipt-backed promotion intent', retryable: false }, prNumber);
+          if (!manualValidationFinalSummaryProjectionMatches(options.body, receipt)) return fail('failed', context, { code: 'MANUAL_VALIDATION_SUMMARY_PROJECTION_INVALID', message: 'final summary body does not match the canonical receipt projection', retryable: false }, prNumber);
+        }
+      }
       const expectedReportPath = taskReportPath(resolved.taskDir);
       const suppliedReportPath = path.resolve(resolved.repoRoot, options.changeReportFile!);
       if (suppliedReportPath !== expectedReportPath) return fail('failed', context, { code: 'PR_CHANGE_REPORT_PATH_INVALID', message: 'summary-sync must consume the task-bound pr-change-report.json', retryable: false });
@@ -528,7 +578,30 @@ async function syncPullRequestSummary(
       if (!report.ok) return fail('failed', context, platformError(report.error));
       const checked = currentReportCheck(report.value, initial.value, taskContent, resolved.repoRoot);
       if (!checked.ok) return fail('failed', context, checked.error);
-      const replaced = replaceCanonicalReportPlaceholder(options.body, report.value);
+      const placeholder = CANONICAL_REPORT_PLACEHOLDER;
+      const split = splitDocumentPlaceholder(options.body, placeholder);
+      if (!split.ok) return fail('failed', context, {
+        code: 'PR_SUMMARY_BODY_CONTRACT_INVALID',
+        message: split.error.message,
+        retryable: false
+      });
+      const prefix = sanitizeMarkdownDocument(split.value.prefix, { reservedMarkers: [CONTROL_MARKER_PATTERN] });
+      const suffix = sanitizeMarkdownDocument(split.value.suffix, { reservedMarkers: [CONTROL_MARKER_PATTERN] });
+      if (!prefix.ok) {
+        return fail('failed', context, {
+          code: 'PR_SUMMARY_BODY_CONTRACT_INVALID',
+          message: `${prefix.error.message} at offset ${prefix.error.offset}`,
+          retryable: false
+        });
+      }
+      if (!suffix.ok) {
+        return fail('failed', context, {
+          code: 'PR_SUMMARY_BODY_CONTRACT_INVALID',
+          message: `${suffix.error.message} at offset ${suffix.error.offset}`,
+          retryable: false
+        });
+      }
+      const replaced = replaceCanonicalReportPlaceholder(`${prefix.value}${placeholder}${suffix.value}`, report.value);
       if (!replaced.ok) return fail('failed', context, platformError(replaced.error));
       const desired = buildPullRequestSummary(resolved.taskId, replaced.value, initial.value.head.sha, renderHumanOverrideAudit(taskContent));
       if (!isSafeSummaryEnvelope(desired, resolved.taskId)) return fail('failed', context, {
@@ -630,7 +703,10 @@ async function syncPullRequestSummary(
         operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }],
         result: null, warnings: [], ...info
       };
-    });
+    };
+    return await (options.lockAlreadyHeld
+      ? execute()
+      : withTaskExecutionLock(resolved.repoRoot, resolved.taskId, options.agent, execute));
   } catch (error) {
     const lockError = error instanceof TaskExecutionLockError
       ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
@@ -643,9 +719,10 @@ export {
   buildPullRequestSummary,
   reconcileSummaryComment,
   reportWrite,
+  summaryCommentState,
   summaryContext,
   summaryMarker,
   syncPullRequestSummary,
   warningResultForPrimary
 };
-export type { PullRequestSummaryResult, ReportWriteOptions, ReportWriteResult, SummaryContextResult };
+export type { ManualValidationSummaryOptions, PullRequestSummaryResult, ReportWriteOptions, ReportWriteResult, SummaryCommentStateResult, SummaryContextResult };

package/lib/platform/provider-contract.ts

@@ -22,7 +22,7 @@ type PlatformError = {
 
 type ProviderResult<T> =
   | { ok: true; value: T }
-  | { ok: false; error: PlatformError };
+  | { ok: false; error: PlatformError; value?: T };
 
 type ProviderOperationContext = {
   repositoryRoot: string;
@@ -162,6 +162,41 @@ type MutationReceipt = {
   operationId?: string;
 };
 
+type SecurityAlertKind = 'dependabot' | 'code-scanning';
+
+type SecurityAlertSnapshot = {
+  kind: SecurityAlertKind;
+  number: number;
+  state: string;
+  data: JsonValue;
+};
+
+type LabelDefinition = {
+  name: string;
+  color: string;
+  description: string;
+};
+
+type LabelReconciliation = {
+  changed: boolean;
+  created: string[];
+  updated: string[];
+  removed: string[];
+  skipped: string[];
+};
+
+type MilestoneDefinition = {
+  title: string;
+  description: string;
+  state: 'open' | 'closed';
+};
+
+type MilestoneInitialization = {
+  changed: boolean;
+  created: string[];
+  skipped: string[];
+};
+
 type RepositoryMetadataSnapshot = {
   repository: { identity: ResourceIdentity; name: string; url: string | null };
   labels: Array<{ identity: ResourceIdentity; name: string }>;
@@ -286,6 +321,8 @@ type PlatformProvider = {
       head: string;
     }): Promise<ProviderResult<{ sha: string }>>;
     inspect(input: { context: ProviderOperationContext; target: ResourceIdentity }): Promise<ProviderResult<ChangeRequestSnapshot>>;
+    listFiles?(input: { context: ProviderOperationContext; target: ResourceIdentity }): Promise<ProviderResult<string[]>>;
+    listClosingIssues?(input: { context: ProviderOperationContext; target: ResourceIdentity }): Promise<ProviderResult<ResourceIdentity[]>>;
     listClosing(input: { context: ProviderOperationContext; issue: ResourceIdentity }): Promise<ProviderResult<ChangeRequestSnapshot[]>>;
     create(input: {
       context: ProviderOperationContext;
@@ -383,6 +420,34 @@ type PlatformProvider = {
       historyLimit: number;
     }): Promise<ProviderResult<ReleaseNotesFacts>>;
   };
+  securityAlerts?: {
+    inspect(input: {
+      context: ProviderOperationContext;
+      kind: SecurityAlertKind;
+      number: number;
+    }): Promise<ProviderResult<SecurityAlertSnapshot>>;
+    dismiss(input: {
+      context: ProviderOperationContext;
+      kind: SecurityAlertKind;
+      number: number;
+      reason: string;
+      comment: string;
+      mutation: MutationIdentity;
+    }): Promise<ProviderResult<MutationReceipt>>;
+  };
+  repositoryMetadata?: {
+    reconcileLabels(input: {
+      context: ProviderOperationContext;
+      desired: LabelDefinition[];
+      cleanupStaleIn: boolean;
+      mutation: MutationIdentity;
+    }): Promise<ProviderResult<LabelReconciliation>>;
+    reconcileMilestones(input: {
+      context: ProviderOperationContext;
+      desired: MilestoneDefinition[];
+      mutation: MutationIdentity;
+    }): Promise<ProviderResult<MilestoneInitialization>>;
+  };
   verification?: {
     fetchRemoteFacts(input: {
       context: ProviderOperationContext;
@@ -414,12 +479,14 @@ function validatePlatformProvider(
   providerType: string
 ): ProviderResult<PlatformProvider> {
   const operationGroups: Record<string, { required: string[]; optional: string[] }> = {
-    issues: { required: ['inspect', 'create', 'update', 'describeRepository'], optional: [] },
+    issues: { required: ['inspect', 'create', 'update', 'describeRepository'], optional: ['listLabels', 'listMilestones'] },
     comments: { required: ['list', 'write', 'delete'], optional: [] },
-    changeRequests: { required: ['inspect', 'listClosing', 'create', 'update', 'resolveGitEvidence'], optional: ['verifyHead'] },
+    changeRequests: { required: ['inspect', 'listClosing', 'create', 'update', 'resolveGitEvidence'], optional: ['verifyHead', 'listFiles', 'listClosingIssues'] },
     checks: { required: ['inspectRequired', 'resolveRun', 'fetchLogs'], optional: [] },
     reviews: { required: ['list', 'publish'], optional: [] },
     releases: { required: ['inspect', 'create', 'update', 'reconcileMilestones', 'publishNotes', 'collectNotes'], optional: [] },
+    securityAlerts: { required: ['inspect', 'dismiss'], optional: [] },
+    repositoryMetadata: { required: ['reconcileLabels', 'reconcileMilestones'], optional: [] },
     verification: { required: ['fetchRemoteFacts'], optional: [] }
   };
   const resourceKindsByGroup: Record<string, PlatformResourceKind[]> = {
@@ -429,6 +496,8 @@ function validatePlatformProvider(
     checks: ['pull-request'],
     reviews: ['pull-request'],
     releases: ['release', 'issue', 'pull-request'],
+    securityAlerts: [],
+    repositoryMetadata: [],
     verification: ['issue', 'pull-request']
   };
   if (!isRecord(value)
@@ -515,6 +584,10 @@ export type {
   IssueSnapshot,
   JsonValue,
   MilestoneReconciliation,
+  MilestoneDefinition,
+  MilestoneInitialization,
+  LabelDefinition,
+  LabelReconciliation,
   MutationIdentity,
   MutationReceipt,
   PlatformCapabilities,
@@ -531,6 +604,8 @@ export type {
   RepositoryMetadataSnapshot,
   ReleaseNotesFacts,
   ResourceIdentity,
+  SecurityAlertKind,
+  SecurityAlertSnapshot,
   ReviewSnapshot,
   VerificationRemoteFacts
 };

package/lib/platform/provider-validation.ts

@@ -5,7 +5,11 @@ import type {
   CheckLogSnapshot,
   CheckRunSnapshot,
   GitEvidenceSnapshot,
+  LabelDefinition,
+  LabelReconciliation,
   IssueSnapshot,
+  MilestoneDefinition,
+  MilestoneInitialization,
   MilestoneReconciliation,
   MutationReceipt,
   PlatformContextSnapshot,
@@ -18,6 +22,8 @@ import type {
   RepositoryMetadataSnapshot,
   RequiredCheckSnapshot,
   ReviewSnapshot,
+  SecurityAlertKind,
+  SecurityAlertSnapshot,
   VerificationRemoteFacts
 } from './provider-contract.ts';
 import type { JsonValue } from './provider-contract.ts';
@@ -273,6 +279,67 @@ function validateReceipt(value: unknown): MutationReceipt {
   };
 }
 
+function positiveInteger(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) <= 0) throw new Error(`${label} must be a positive integer`);
+  return value as number;
+}
+
+function validateSecurityAlert(value: unknown): SecurityAlertSnapshot {
+  const item = record(value, 'security alert');
+  exactKeys(item, ['kind', 'number', 'state', 'data'], 'security alert');
+  if (item.kind !== 'dependabot' && item.kind !== 'code-scanning') throw new Error('security alert.kind is invalid');
+  return {
+    kind: item.kind as SecurityAlertKind,
+    number: positiveInteger(item.number, 'security alert.number'),
+    state: stringValue(item.state, 'security alert.state'),
+    data: jsonValue(item.data, 'security alert.data')
+  };
+}
+
+function validateLabelDefinition(value: unknown, label: string): LabelDefinition {
+  const item = record(value, label);
+  exactKeys(item, ['name', 'color', 'description'], label);
+  return {
+    name: stringValue(item.name, `${label}.name`),
+    color: stringValue(item.color, `${label}.color`),
+    description: stringValue(item.description, `${label}.description`, true)
+  };
+}
+
+function validateLabelReconciliation(value: unknown): LabelReconciliation {
+  const item = record(value, 'label reconciliation');
+  exactKeys(item, ['changed', 'created', 'updated', 'removed', 'skipped'], 'label reconciliation');
+  const names = (field: string) => arrayValue(item[field], `label reconciliation.${field}`).map((entry) => stringValue(entry, `${field}[]`));
+  return {
+    changed: booleanValue(item.changed, 'label reconciliation.changed'),
+    created: names('created'),
+    updated: names('updated'),
+    removed: names('removed'),
+    skipped: names('skipped')
+  };
+}
+
+function validateMilestoneDefinition(value: unknown, label: string): MilestoneDefinition {
+  const item = record(value, label);
+  exactKeys(item, ['title', 'description', 'state'], label);
+  if (item.state !== 'open' && item.state !== 'closed') throw new Error(`${label}.state is invalid`);
+  return {
+    title: stringValue(item.title, `${label}.title`),
+    description: stringValue(item.description, `${label}.description`, true),
+    state: item.state
+  };
+}
+
+function validateMilestoneInitialization(value: unknown): MilestoneInitialization {
+  const item = record(value, 'milestone initialization');
+  exactKeys(item, ['changed', 'created', 'skipped'], 'milestone initialization');
+  return {
+    changed: booleanValue(item.changed, 'milestone initialization.changed'),
+    created: arrayValue(item.created, 'milestone initialization.created').map((entry) => stringValue(entry, 'created[]')),
+    skipped: arrayValue(item.skipped, 'milestone initialization.skipped').map((entry) => stringValue(entry, 'skipped[]'))
+  };
+}
+
 function validateMetadata(value: unknown): RepositoryMetadataSnapshot {
   const item = record(value, 'repository metadata');
   exactKeys(item, ['repository', 'labels', 'milestones', 'issueTypes', 'fields'], 'repository metadata');
@@ -375,6 +442,11 @@ const PROVIDER_ERROR_CATALOG: Readonly<Record<string, { message: string; retryab
   ISSUE_NUMBER_INVALID: { message: 'The issue number is invalid', retryable: false },
   ISSUE_CREATE_RESPONSE_INVALID: { message: 'Issue creation returned an invalid response', retryable: false },
   COMMENT_ID_INVALID: { message: 'The comment identity is invalid', retryable: false },
+  SECURITY_KIND_INVALID: { message: 'The security alert kind is invalid', retryable: false },
+  SECURITY_NUMBER_INVALID: { message: 'The security alert number is invalid', retryable: false },
+  SECURITY_RESPONSE_INVALID: { message: 'The platform returned an invalid security alert', retryable: false },
+  LABEL_RESPONSE_INVALID: { message: 'The platform returned an invalid label response', retryable: false },
+  MILESTONE_RESPONSE_INVALID: { message: 'The platform returned an invalid milestone response', retryable: false },
   MILESTONE_IDENTITY_INVALID: { message: 'The milestone identity is invalid', retryable: false },
   CHECK_RUN_NOT_FOUND: { message: 'The check run was not found', retryable: false },
   RELEASE_NOTES_AUTHORS_TRUNCATED: { message: 'Release note commit authors exceeded the supported limit', retryable: false },
@@ -415,6 +487,8 @@ function validators(providerType: string, declaration?: ProviderIdentityDeclarat
       return { sha: stringValue(item.sha, 'change request head.sha') };
     },
     'changeRequests.inspect': (value) => validateChangeRequest(value, declaredIdentityKind(declaration, 'pull-request'), true),
+    'changeRequests.listFiles': (value) => arrayValue(value, 'pull request files').map((entry) => stringValue(entry, 'pull request files[]')),
+    'changeRequests.listClosingIssues': (value) => arrayValue(value, 'closing issues').map((entry) => identity(entry, 'closing issues[]', declaredIdentityKind(declaration, 'issue'))),
     'changeRequests.listClosing': (value) => arrayValue(value, 'changeRequests').map((entry) => validateChangeRequest(entry, declaredIdentityKind(declaration, 'pull-request'), true)),
     'changeRequests.create': validateReceipt,
     'changeRequests.update': validateReceipt,
@@ -458,6 +532,10 @@ function validators(providerType: string, declaration?: ProviderIdentityDeclarat
     },
     'releases.publishNotes': validateReceipt,
     'releases.collectNotes': (value) => validateReleaseNotes(value, declaration),
+    'securityAlerts.inspect': validateSecurityAlert,
+    'securityAlerts.dismiss': validateReceipt,
+    'repositoryMetadata.reconcileLabels': validateLabelReconciliation,
+    'repositoryMetadata.reconcileMilestones': validateMilestoneInitialization,
     'verification.fetchRemoteFacts': (value) => {
       const item = record(value, 'verification facts');
       exactKeys(item, ['issue', 'comments', 'changeRequest', 'commit', 'fields'], 'verification facts');
@@ -491,11 +569,15 @@ async function invokeProviderOperation<T>(
     }
     if (envelope.ok === false && envelope.error && typeof envelope.error === 'object' && !Array.isArray(envelope.error)) {
       try {
-        exactKeys(envelope, ['ok', 'error'], `${operation} result`);
+        exactKeys(envelope, Object.hasOwn(envelope, 'value') ? ['ok', 'error', 'value'] : ['ok', 'error'], `${operation} result`);
         const error = envelope.error as Record<string, unknown>;
         exactKeys(error, ['code', 'message', 'retryable'], `${operation} error`);
         if (typeof error.code !== 'string' || !error.code || typeof error.message !== 'string' || !error.message || typeof error.retryable !== 'boolean') throw new Error('invalid provider error');
-        return { ok: false, error: safeProviderError(providerType, operation, error) };
+        return {
+          ok: false,
+          error: safeProviderError(providerType, operation, error),
+          ...(Object.hasOwn(envelope, 'value') ? { value: validate(envelope.value) } : {})
+        };
       } catch {
         return { ok: false, error: validationError(providerType, operation, 'Provider operation returned an invalid error') };
       }
@@ -510,7 +592,7 @@ function wrapProviderOperations(provider: PlatformProvider): PlatformProvider {
   const map = validators(provider.type, provider.identity);
   const wrapped: PlatformProvider = { ...provider, context: { ...provider.context } };
   wrapped.context.resolve = (input) => invokeProviderOperation(provider.type, 'context.resolve', () => provider.context.resolve(input), map['context.resolve']! as ResultValidator<PlatformContextSnapshot>);
-  for (const groupName of ['issues', 'comments', 'changeRequests', 'checks', 'reviews', 'releases', 'verification'] as const) {
+  for (const groupName of ['issues', 'comments', 'changeRequests', 'checks', 'reviews', 'releases', 'securityAlerts', 'repositoryMetadata', 'verification'] as const) {
     const group = provider[groupName];
     if (!group) continue;
     const target: Record<string, unknown> = { ...group };