@contextrail/assess 0.0.0-stage → 1.0.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +82 -2
  3. package/assets/brand/icon-dark.png +0 -0
  4. package/assets/brand/icon-light.png +0 -0
  5. package/dist/assess.d.ts +109 -0
  6. package/dist/assess.js +1563 -0
  7. package/dist/assessment.d.ts +571 -0
  8. package/dist/assessment.js +404 -0
  9. package/dist/budget.d.ts +24 -0
  10. package/dist/budget.js +52 -0
  11. package/dist/candidate.d.ts +156 -0
  12. package/dist/candidate.js +361 -0
  13. package/dist/change-summary.d.ts +33 -0
  14. package/dist/change-summary.js +26 -0
  15. package/dist/cli.d.ts +2 -0
  16. package/dist/cli.js +406 -0
  17. package/dist/contracts.d.ts +99 -0
  18. package/dist/contracts.js +62 -0
  19. package/dist/diagnostics.d.ts +44 -0
  20. package/dist/diagnostics.js +412 -0
  21. package/dist/evidence.d.ts +73 -0
  22. package/dist/evidence.js +297 -0
  23. package/dist/feedback.d.ts +21 -0
  24. package/dist/feedback.js +154 -0
  25. package/dist/git.d.ts +40 -0
  26. package/dist/git.js +207 -0
  27. package/dist/github.d.ts +90 -0
  28. package/dist/github.js +1342 -0
  29. package/dist/index.d.ts +14 -0
  30. package/dist/index.js +14 -0
  31. package/dist/mcp.d.ts +28 -0
  32. package/dist/mcp.js +173 -0
  33. package/dist/pack.d.ts +160 -0
  34. package/dist/pack.js +377 -0
  35. package/dist/phases.d.ts +65 -0
  36. package/dist/phases.js +63 -0
  37. package/dist/planning.d.ts +64 -0
  38. package/dist/planning.js +135 -0
  39. package/dist/pr-context.d.ts +316 -0
  40. package/dist/pr-context.js +198 -0
  41. package/dist/prepare.d.ts +71 -0
  42. package/dist/prepare.js +335 -0
  43. package/dist/presentation.d.ts +310 -0
  44. package/dist/presentation.js +1076 -0
  45. package/dist/provider-diagnostics.d.ts +93 -0
  46. package/dist/provider-diagnostics.js +233 -0
  47. package/dist/providers.d.ts +45 -0
  48. package/dist/providers.js +291 -0
  49. package/dist/report-contract.d.ts +137 -0
  50. package/dist/report-contract.js +248 -0
  51. package/dist/results.d.ts +90 -0
  52. package/dist/results.js +128 -0
  53. package/dist/resume.d.ts +25 -0
  54. package/dist/resume.js +116 -0
  55. package/dist/source.d.ts +167 -0
  56. package/dist/source.js +675 -0
  57. package/dist/verification.d.ts +386 -0
  58. package/dist/verification.js +168 -0
  59. package/dist/version.d.ts +2 -0
  60. package/dist/version.js +9 -0
  61. package/docs/README.md +24 -0
  62. package/docs/action-reference.md +85 -0
  63. package/docs/architecture.md +158 -0
  64. package/docs/configuration.md +83 -0
  65. package/docs/contributing.md +46 -0
  66. package/docs/getting-started.md +92 -0
  67. package/docs/github-actions.md +141 -0
  68. package/docs/operations.md +211 -0
  69. package/docs/review-results.md +189 -0
  70. package/docs/security.md +68 -0
  71. package/docs/standards.md +62 -0
  72. package/examples/assess-pull-request.yml +109 -0
  73. package/package.json +56 -5
package/dist/assess.js ADDED
@@ -0,0 +1,1563 @@
1
+ import { CandidateAccumulator, candidateSelectionSchema, candidateInstructions, concernInstructions, concernDecisionSchema, validateConcern, revalidateCandidate, projectCandidates, } from './candidate.js';
2
+ import { createHash } from 'node:crypto';
3
+ import { readFileSync } from 'node:fs';
4
+ import { createRequire } from 'node:module';
5
+ import { readFile, mkdir, readdir, writeFile } from 'node:fs/promises';
6
+ import { dirname, join } from 'node:path';
7
+ import { generateText, tool, jsonSchema, zodSchema } from 'ai';
8
+ import { z } from 'zod';
9
+ import { assessmentCoverage, assessmentProgressLabel, externalEvidenceAssessmentIds, renderReaderGuidance, } from './presentation.js';
10
+ import { validateChangeSummary, changeSummarySelectionSchema, phaseItems, } from './change-summary.js';
11
+ import { parsePrContext } from './pr-context.js';
12
+ import { sendAssessmentReport } from './feedback.js';
13
+ import { atomicJson, digest } from './prepare.js';
14
+ import { CitationError, EvidenceLedger, ModelIdentifiers, modelEvidence, resolveCitationSelections, } from './evidence.js';
15
+ import { DEFAULT_POLICY, assessmentPolicySchema, decideExit, } from './results.js';
16
+ import { assessmentModel, ProviderAccountingError, recoverProviderCalls, reportedUsage, providerFailureDiagnostics, providerResponseDiagnostics, providerRequestDiagnostics, providerTransportDiagnostics, } from './providers.js';
17
+ import { FixedSnapshotSource, SourceAccessError } from './source.js';
18
+ import { publicationSchema } from './contracts.js';
19
+ import { createPhaseRecord, validatePhaseRecord } from './phases.js';
20
+ import { AssessmentBudget, BudgetStop, DEFAULT_EXECUTION_LIMITS, } from './budget.js';
21
+ import { Diagnostics, sanitizeRecord, systemFailureDiagnostics, submissionDiagnostics, submissionToolDiagnostics, } from './diagnostics.js';
22
+ import { exactIds, PlanCitationError } from './planning.js';
23
+ import { loadAssessmentCheckpoint } from './resume.js';
24
+ import { prepareEvidencePack, writeEvidencePack, readPackPublication, modelPackEvidence, modelDiffEvidence, repositoryInstructionsEvidence, modelSourceEvidence, } from './pack.js';
25
+ export { DEFAULT_EXECUTION_LIMITS };
26
+ const phaseOverridesSchema = z.strictObject({
27
+ assess: z.unknown().optional(),
28
+ verify: z.unknown().optional(),
29
+ });
30
+ const providerSchema = z.strictObject({
31
+ provider: z.enum(['openai', 'openrouter']),
32
+ model: z.string().min(1),
33
+ effort: z.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh']).optional(),
34
+ });
35
+ function phaseConfiguration(defaults, overrides = {}) {
36
+ const base = providerSchema.parse(defaults), parsed = phaseOverridesSchema.parse(overrides);
37
+ return Object.fromEntries(['assess', 'verify'].map((p) => [
38
+ p,
39
+ parsed[p] === undefined ? base : providerSchema.parse(parsed[p]),
40
+ ]));
41
+ }
42
+ const sourceSide = z.enum(['base', 'head']);
43
+ const integer = z.number().int().nonnegative().optional();
44
+ const sensitivePath = (path) => path
45
+ .split('/')
46
+ .some((part) => /^\.env(?:\.|$)|^(?:credentials|secrets)(?:\.|$)|\.(?:pem|key|p12|pfx)$/iu.test(part));
47
+ const phaseFilename = (phase, unit, attempt) => `${phase}-${unit}-${attempt}.json`;
48
+ const requireRuntime = createRequire(import.meta.url);
49
+ const runtimeVersion = (name) => {
50
+ try {
51
+ return JSON.parse(readFileSync(join(dirname(requireRuntime.resolve(name)), '..', 'package.json'), 'utf8')).version;
52
+ }
53
+ catch {
54
+ return 'unavailable';
55
+ }
56
+ };
57
+ const cleanIdentity = (value) => typeof value === 'string' && /^[A-Za-z0-9._:/+-]{1,200}$/u.test(value) ? value : null;
58
+ function normalizedWireUsage(raw) {
59
+ if (!raw || typeof raw !== 'object')
60
+ return null;
61
+ const allow = [
62
+ 'input_tokens',
63
+ 'output_tokens',
64
+ 'prompt_tokens',
65
+ 'completion_tokens',
66
+ 'total_tokens',
67
+ 'cost',
68
+ 'input_tokens_details',
69
+ 'output_tokens_details',
70
+ 'prompt_tokens_details',
71
+ 'completion_tokens_details',
72
+ ];
73
+ return Object.fromEntries(Object.entries(raw)
74
+ .filter(([key]) => allow.includes(key))
75
+ .map(([key, value]) => [
76
+ key,
77
+ value && typeof value === 'object'
78
+ ? Object.fromEntries(Object.entries(value).filter(([, v]) => typeof v === 'number' && Number.isFinite(v) && v >= 0))
79
+ : typeof value === 'number' && Number.isFinite(value) && value >= 0
80
+ ? value
81
+ : null,
82
+ ]));
83
+ }
84
+ function initialAssessmentState(options, source, budget, prContext, settings) {
85
+ const { prepared } = options, { models, logLevel, limits } = settings;
86
+ return {
87
+ ...structuredClone(prepared.state),
88
+ schemaVersion: 2,
89
+ entries: structuredClone(prepared.state.entries),
90
+ assessmentStatus: 'running',
91
+ phases: [],
92
+ checks: [],
93
+ findings: [],
94
+ concernValidation: { expected: 0, validated: 0, complete: false, scope: 'nominated_concerns' },
95
+ verification: { expected: prepared.state.entries.length, verified: 0, complete: false },
96
+ decision: null,
97
+ limitations: prepared.state.limitations
98
+ .filter((v) => !v.startsWith('Prepared means'))
99
+ .concat('No runtime code was executed. Exact citations and accounting do not prove interpretation correctness or exhaustive review.'),
100
+ execution: {
101
+ requested: options.provider,
102
+ phaseModels: models,
103
+ limits,
104
+ sourceLimits: source.limits,
105
+ policy: assessmentPolicySchema.parse({ ...DEFAULT_POLICY, ...options.policy }),
106
+ rubric: { adherence: 'adherence-v1', confidence: 'model-confidence-v1' },
107
+ purpose: options.purpose ?? null,
108
+ prContext: prContext
109
+ ? {
110
+ hash: digest(sanitizeRecord(prContext)),
111
+ capturedAt: prContext.capturedAt,
112
+ discussion: prContext.discussion.status,
113
+ historyRuns: prContext.history.runs.length,
114
+ previousHead: prContext.history.assessment?.head ?? null,
115
+ }
116
+ : null,
117
+ scope: null,
118
+ startedAt: new Date().toISOString(),
119
+ elapsedMs: 0,
120
+ calls: 0,
121
+ steps: 0,
122
+ stopReason: null,
123
+ usage: [],
124
+ providerUsage: [],
125
+ returnedIdentities: [],
126
+ reporting: { status: 'pending' },
127
+ capture: 'Bounded phase assessment artifacts and safe diagnostic metadata. No raw prompt/response conversations, headers, error bodies or hidden reasoning. Caller-managed access and retention.',
128
+ logLevel,
129
+ },
130
+ };
131
+ }
132
+ function restoreCheckpoint(options, directory, state, ledger) {
133
+ const { prepared } = options;
134
+ if (options.resume) {
135
+ const loaded = loadAssessmentCheckpoint(directory, {
136
+ artifact: prepared.state.artifact,
137
+ reviewerId: prepared.state.requestedReviewerId,
138
+ });
139
+ if (digest(loaded.checkpoint) !== digest(options.resume) ||
140
+ digest(loaded.prepared.state) !== digest(prepared.state))
141
+ throw new Error('resume_checkpoint_changed');
142
+ const old = options.resume.state;
143
+ if (old.phases.some((p) => p.phase === 'assess' && p.configuration.promptVersion !== 'candidate-observation-v3'))
144
+ throw Error('resume_method_changed_start_new_assessment');
145
+ if (old.runId !== state.runId ||
146
+ digest(old.artifact) !== digest(state.artifact) ||
147
+ old.scopeIdentity !== state.scopeIdentity ||
148
+ digest(old.execution.phaseModels) !== digest(state.execution.phaseModels) ||
149
+ digest(old.execution.sourceLimits) !== digest(state.execution.sourceLimits) ||
150
+ digest(old.execution.policy) !== digest(state.execution.policy) ||
151
+ old.execution.purpose !== state.execution.purpose ||
152
+ old.execution.prContext?.hash !== state.execution.prContext?.hash)
153
+ throw new Error('resume_configuration_changed');
154
+ state.phases = structuredClone(old.phases);
155
+ state.execution.usage = structuredClone(old.execution.usage);
156
+ state.execution.providerUsage = structuredClone(old.execution.providerUsage);
157
+ state.execution.returnedIdentities = structuredClone(old.execution.returnedIdentities);
158
+ state.execution.calls = old.execution.calls;
159
+ state.execution.steps = old.execution.steps;
160
+ for (const record of Object.values(options.resume.evidence))
161
+ ledger.add(record.text, record.provenance, record.fragments);
162
+ }
163
+ }
164
+ async function restorePreparationManifest(options, state, directory, _material, ledger, preparedManifest) {
165
+ if (options.resume) {
166
+ const latest = state.phases.filter((p) => p.phase === 'assess' && p.workUnitId === 'all').at(-1);
167
+ if (latest?.status === 'complete')
168
+ for (const p of phaseItems(latest.output, 'assessments'))
169
+ revalidateCandidate(p, state.entries, ledger);
170
+ else if (latest) {
171
+ const partial = JSON.parse(await readFile(join(directory, 'phases', `partial-assess-all-${latest.attempt}.json`), 'utf8').catch(() => 'null'));
172
+ if (partial)
173
+ for (const p of partial.output.assessments)
174
+ revalidateCandidate(p, state.entries, ledger);
175
+ }
176
+ await atomicJson(join(directory, 'manifest.json'), preparedManifest);
177
+ }
178
+ }
179
+ async function createAssessmentRuntime(options) {
180
+ const { prepared } = options, directory = dirname(prepared.statePath), source = new FixedSnapshotSource(prepared.state.artifact, options.sourceLimits);
181
+ const models = phaseConfiguration(options.provider, options.phaseModels), logLevel = options.logLevel ?? 'info';
182
+ if (!['quiet', 'info', 'debug'].includes(logLevel))
183
+ throw new Error('invalid_log_level');
184
+ const limits = { ...DEFAULT_EXECUTION_LIMITS, ...options.limits }, budget = new AssessmentBudget(limits);
185
+ const prContext = options.prContext
186
+ ? parsePrContext(options.prContext, prepared.state.artifact, prepared.state.reviewer?.nodeId ?? options.prContext.reviewer)
187
+ : null;
188
+ const state = initialAssessmentState(options, source, budget, prContext, { models, logLevel, limits });
189
+ const diagnostics = new Diagnostics(directory, state.runId, logLevel), ledger = new EvidenceLedger();
190
+ restoreCheckpoint(options, directory, state, ledger);
191
+ const invocationPhaseIndex = state.phases.length;
192
+ const previousCalls = state.execution.calls, previousElapsed = options.resume?.state.execution.elapsedMs ?? 0;
193
+ await mkdir(join(directory, 'phases'), { recursive: true, mode: 0o700 });
194
+ let writes = Promise.resolve();
195
+ const persist = () => {
196
+ const next = writes.then(async () => {
197
+ await atomicJson(join(directory, 'evidence.json'), sanitizeRecord(ledger.records));
198
+ await atomicJson(prepared.statePath, sanitizeRecord(state));
199
+ });
200
+ writes = next.catch(() => undefined);
201
+ return next;
202
+ };
203
+ const material = JSON.parse(await readFile(prepared.materialPath, 'utf8'));
204
+ const preparedManifest = options.resume?.preparationManifest ?? JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8'));
205
+ await restorePreparationManifest(options, state, directory, material, ledger, preparedManifest);
206
+ const manifestHash = digest(preparedManifest), materialHash = digest(material);
207
+ return {
208
+ options,
209
+ prepared,
210
+ prContext,
211
+ directory,
212
+ source,
213
+ models,
214
+ limits,
215
+ budget,
216
+ state,
217
+ ledger,
218
+ diagnostics,
219
+ persist,
220
+ material,
221
+ preparedManifest,
222
+ manifestHash,
223
+ materialHash,
224
+ repositoryInstructions: undefined,
225
+ modelDiff: undefined,
226
+ invocationPhaseIndex,
227
+ previousCalls,
228
+ previousElapsed,
229
+ evidencePack: undefined,
230
+ retainedProposals: [],
231
+ };
232
+ }
233
+ const correctionRounds = (session) => remainingContexts(session).length < session.remainingAtLastStep
234
+ ? 0
235
+ : session.rejected + Number(session.stepRejected);
236
+ async function createPhaseRuntime(run, phase, workUnitId, assigned, payload, schema, validate, attempt = 1) {
237
+ const { state, directory, budget, ledger, options, manifestHash, materialHash, retainedProposals, prepared } = run;
238
+ const startedAt = new Date().toISOString(), inputRefs = [
239
+ { ref: 'manifest.json', hash: manifestHash },
240
+ { ref: 'publications.json', hash: materialHash },
241
+ ...state.phases
242
+ .filter((p) => p.status === 'complete')
243
+ .map((p) => ({ ref: `phase:${p.phase}:${p.workUnitId}:${p.attempt}`, hash: digest(p) })),
244
+ { ref: `input:${phase}:${workUnitId}:${attempt}`, hash: digest(sanitizeRecord(payload)) },
245
+ ], phaseCalls = [];
246
+ if (digest(JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8'))) !== manifestHash ||
247
+ digest(JSON.parse(await readFile(prepared.materialPath, 'utf8'))) !== materialHash)
248
+ throw new Error('upstream_artifact_changed');
249
+ for (const p of state.phases.filter((p) => p.status === 'complete')) {
250
+ const name = phaseFilename(p.phase, p.workUnitId, p.attempt);
251
+ if (digest(JSON.parse(await readFile(join(directory, 'phases', name), 'utf8'))) !== digest(p))
252
+ throw new Error('upstream_phase_changed');
253
+ }
254
+ const remaining = budget.remainingMs(phase), controller = new AbortController();
255
+ if (remaining !== null && remaining <= 0)
256
+ throw new BudgetStop(phase === 'verify' ? 'max_time_ms' : 'max_time_ms');
257
+ const timer = remaining === null ? null : setTimeout(() => controller.abort(), Math.max(1, remaining));
258
+ const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
259
+ let output;
260
+ const instructions = workUnitId === 'change-summary'
261
+ ? 'Check the supplied change summary against pinned source and diff. Return a concise accurate overview and useful human review focus, with source references. This is reader orientation for the proposed artifacts, not additional governing rules or compliance assurance. Do not request proof that the current PR checks passed or that an operation ran; those are outside the artifact audit. Keep review focus on specific changed implementation properties. Return summary null if the evidence cannot support a useful summary. Use submit_verification.'
262
+ : {
263
+ assess: candidateInstructions,
264
+ verify: concernInstructions,
265
+ }[phase] +
266
+ '\nUse the supplied context_N and evidence_N handles verbatim in identifier fields. These are exact handles, not hashes to calculate. Evidence text and line/segment numbers are unchanged.';
267
+ const assessmentAccumulator = phase === 'assess' ? new CandidateAccumulator(assigned, ledger, retainedProposals) : null;
268
+ if (assessmentAccumulator?.remaining().length === 0)
269
+ output = assessmentAccumulator.snapshot();
270
+ return {
271
+ run,
272
+ phase,
273
+ workUnitId,
274
+ assigned,
275
+ payload,
276
+ schema,
277
+ validate,
278
+ attempt,
279
+ startedAt,
280
+ inputRefs,
281
+ phaseCalls,
282
+ timer,
283
+ signal,
284
+ instructions,
285
+ assessmentAccumulator,
286
+ output,
287
+ sdkStop: null,
288
+ rejected: 0,
289
+ toolsThisStep: 0,
290
+ stepRejected: false,
291
+ summaryFailures: 0,
292
+ summaryFallbackOutput: undefined,
293
+ summaryCorrection: null,
294
+ remainingAtLastStep: assessmentAccumulator?.remaining().length ?? assigned.length,
295
+ assessmentWrites: Promise.resolve(),
296
+ verifications: null,
297
+ identifiers: new ModelIdentifiers(assigned.map((entry) => entry.assessmentId), ledger.records),
298
+ };
299
+ }
300
+ async function persistPartialAssessment(session, progress) {
301
+ const { run, workUnitId, assigned, attempt, startedAt, inputRefs, phaseCalls, instructions, assessmentAccumulator, } = session;
302
+ const { state, directory, ledger, models } = run;
303
+ if (!assessmentAccumulator)
304
+ return;
305
+ const record = createPhaseRecord({
306
+ runId: state.runId,
307
+ phase: 'assess',
308
+ workUnitId,
309
+ attempt,
310
+ startedAt,
311
+ finishedAt: new Date().toISOString(),
312
+ status: 'incomplete',
313
+ inputRefs,
314
+ artifact: state.artifact,
315
+ scopeIdentity: state.scopeIdentity,
316
+ assessmentIds: assigned.map((entry) => entry.assessmentId),
317
+ evidenceRefs: Object.keys(ledger.records),
318
+ limitations: [
319
+ 'Retained proposals are not final judgments; complete group handoff and independent verification remain required.',
320
+ ],
321
+ stopReason: progress.remaining.length ? 'awaiting_assessment_entries' : 'awaiting_assessment_handoff',
322
+ configuration: {
323
+ provider: models.assess.provider,
324
+ model: models.assess.model,
325
+ promptHash: digest(instructions),
326
+ kind: 'partial_assessment_progress',
327
+ promptVersion: 'candidate-observation-v3',
328
+ },
329
+ usageRefs: phaseCalls.map((call) => `call:${call}`),
330
+ output: {
331
+ assessments: assessmentAccumulator.snapshot(),
332
+ remaining: progress.remaining,
333
+ ...(state.changeSummary ? { changeSummary: state.changeSummary.candidate } : {}),
334
+ },
335
+ });
336
+ const operation = session.assessmentWrites.then(() => atomicJson(join(directory, 'phases', `partial-assess-${workUnitId}-${attempt}.json`), sanitizeRecord(record)));
337
+ session.assessmentWrites = operation.catch(() => undefined);
338
+ await operation;
339
+ }
340
+ async function invokeTool(session, name, body) {
341
+ const { run, phase, workUnitId, attempt, signal } = session;
342
+ const { diagnostics } = run;
343
+ const started = performance.now();
344
+ await diagnostics.event('tool_started', { phase, workUnitId, attempt, tool: name });
345
+ try {
346
+ signal.throwIfAborted();
347
+ if (++session.toolsThisStep > 50)
348
+ return {
349
+ error: 'tool_batch_limit',
350
+ correction: 'Fifty tool calls were processed in this response. Request remaining reads in the next response.',
351
+ };
352
+ const result = await body();
353
+ await diagnostics.event('tool_completed', {
354
+ phase,
355
+ workUnitId,
356
+ attempt,
357
+ tool: name,
358
+ elapsedMs: performance.now() - started,
359
+ });
360
+ return session.identifiers.toModel(result);
361
+ }
362
+ catch (error) {
363
+ await diagnostics.event('tool_failed', {
364
+ phase,
365
+ workUnitId,
366
+ attempt,
367
+ tool: name,
368
+ code: error instanceof SourceAccessError
369
+ ? error.code
370
+ : signal.aborted
371
+ ? 'cancelled'
372
+ : 'tool_execution_failed',
373
+ elapsedMs: performance.now() - started,
374
+ details: { ...providerFailureDiagnostics(error), ...systemFailureDiagnostics(error) },
375
+ });
376
+ if (error instanceof SourceAccessError) {
377
+ return {
378
+ error: error.code,
379
+ correction: name === 'search_source'
380
+ ? 'path must name one exact committed file, not a directory or glob. Locate it with changedFiles/list_source, or omit path for a bounded tree search. Use the exact returned cursor for continuation. No complete evidence returned.'
381
+ : 'Check pinned path/side/range and use exact returned continuation. No complete evidence returned.',
382
+ };
383
+ }
384
+ throw error;
385
+ }
386
+ }
387
+ function submissionCorrection(error, code) {
388
+ const planCorrection = error instanceof PlanCitationError
389
+ ? {
390
+ message: 'Correct every listed governing citation in one resubmission. Use an exact allowed ref only for its canonical assessment/context/version, and select a valid inclusive numbered segment range from that original governing material. Do not substitute another context, invent a ref, or alter governing scope.',
391
+ invalidCitations: error.corrections,
392
+ omittedCount: error.omittedCount,
393
+ }
394
+ : null;
395
+ return ((error instanceof CitationError
396
+ ? {
397
+ message: error.message,
398
+ path: error.path,
399
+ ref: error.ref,
400
+ refHash: error.refHash,
401
+ instruction: 'Correct this exact citation field. Use the ref returned with the relevant pinned guidance or source read and choose valid displayed startSegment/endSegment indices, inclusive and relative to that evidence record. Read a narrower source range if needed. Code extracts the quotation. Do not invent a reference, provide quote text, or change the assessment to evade validation.',
402
+ }
403
+ : planCorrection) ??
404
+ (code === 'verification_acceptance_inconsistent'
405
+ ? 'Accept means the assessment is supported, including an assessment proving code violations. Supported findings need decision=accept (or accept_with_suggestion for an independently checked proposed patch). If any finding is unsupported or missingChecks is nonempty, use revise/reject/unresolved for the context instead of accept; otherwise missingChecks must be empty.'
406
+ : code === 'unproposed_suggestion_acceptance'
407
+ ? 'Use decision=accept_with_suggestion only when this exact finding contains a non-null proposedReplacement object that you independently checked. Use decision=accept for a supported finding without an accepted patch.'
408
+ : error instanceof z.ZodError
409
+ ? error.issues.map((i) => ({
410
+ code: i.code,
411
+ path: i.path.map((p) => (typeof p === 'number' ? p : '[field]')),
412
+ }))
413
+ : error instanceof Error
414
+ ? error.message
415
+ : 'Invalid submission'));
416
+ }
417
+ function remainingContexts(session) {
418
+ if (session.output !== undefined)
419
+ return [];
420
+ return (session.assessmentAccumulator?.remaining() ??
421
+ session.assigned
422
+ .filter((entry) => !session.verifications?.has(entry.assessmentId))
423
+ .map((entry) => entry.assessmentId));
424
+ }
425
+ async function rejectSubmission(session, rawInput, error) {
426
+ const { run, phase, workUnitId, attempt } = session;
427
+ const { diagnostics } = run;
428
+ session.stepRejected = true;
429
+ const { code: diagnosticCode, details } = submissionDiagnostics(error);
430
+ const code = error instanceof PlanCitationError ? error.code : diagnosticCode;
431
+ await diagnostics.event('submission_rejected', {
432
+ phase,
433
+ workUnitId,
434
+ attempt,
435
+ code,
436
+ details,
437
+ remaining: remainingContexts(session),
438
+ ...(error instanceof PlanCitationError
439
+ ? {
440
+ corrections: error.corrections.map((c) => ({
441
+ assessmentId: c.assessmentId,
442
+ entryIndex: c.entryIndex,
443
+ checkIndex: c.checkIndex,
444
+ code: c.code,
445
+ rejectedRefHash: c.rejectedRefHash,
446
+ allowedRefCount: c.allowedRefs.length,
447
+ })),
448
+ omittedCount: error.omittedCount,
449
+ }
450
+ : {}),
451
+ outputHash: digest(rawInput ?? null),
452
+ count: correctionRounds(session),
453
+ });
454
+ return {
455
+ accepted: false,
456
+ code,
457
+ remaining: remainingContexts(session),
458
+ instruction: session.phase === 'verify'
459
+ ? 'Resubmit this concern decision using submit_verification. sourceRefs select source fragments only; governing publication evidence is already pinned. Do not submit assessment groups.'
460
+ : 'Submit only remaining context handles; accepted results are retained and cannot be overwritten.',
461
+ correction: submissionCorrection(error, code),
462
+ remainingCorrections: Math.max(0, 3 - correctionRounds(session)),
463
+ };
464
+ }
465
+ function revalidateSummary(value, ledger) {
466
+ const summary = value;
467
+ return validateChangeSummary({
468
+ ...summary,
469
+ sourceRefs: summary.sourceRefs.map(({ ref, quote, start, end }) => ({ ref, quote, start, end })),
470
+ }, ledger);
471
+ }
472
+ async function captureChangeSummary(session, value) {
473
+ if (value === undefined || value === null) {
474
+ // An omitted summary contributes no update; after feedback it explicitly abandons correction.
475
+ session.summaryCorrection = null;
476
+ if (value === undefined || session.phase === 'assess' || session.run.state.changeSummary?.status === 'verified')
477
+ return;
478
+ }
479
+ else
480
+ session.summaryCorrection = null;
481
+ const { state, ledger, diagnostics } = session.run;
482
+ if (session.phase === 'verify' && value === false) {
483
+ state.changeSummary = { candidate: state.changeSummary?.candidate ?? null, accepted: null, status: 'rejected' };
484
+ await diagnostics.event('change_summary_withdrawn', { phase: session.phase });
485
+ return;
486
+ }
487
+ // Correction batches need not repeat an already checked summary.
488
+ if (value === null && state.changeSummary?.status === 'verified')
489
+ return;
490
+ try {
491
+ const summary = value === null ? null : validateChangeSummary(resolveCitationSelections(value, ledger), ledger);
492
+ if (session.phase === 'assess') {
493
+ if (summary)
494
+ state.changeSummary = { candidate: summary, accepted: null, status: 'pending' };
495
+ }
496
+ else {
497
+ const accepted = state.changeSummary?.candidate ? summary : null;
498
+ state.changeSummary = {
499
+ candidate: state.changeSummary?.candidate ?? null,
500
+ accepted,
501
+ status: accepted ? 'verified' : 'rejected',
502
+ };
503
+ }
504
+ }
505
+ catch (error) {
506
+ session.summaryFailures++;
507
+ const { code, details } = submissionDiagnostics(error);
508
+ session.summaryCorrection = {
509
+ code: error instanceof Error && error.message === 'change_summary_source_required' ? error.message : code,
510
+ correction: submissionCorrection(error, code),
511
+ };
512
+ if (session.phase === 'verify' && state.changeSummary?.status !== 'verified')
513
+ state.changeSummary = {
514
+ candidate: state.changeSummary?.candidate ?? null,
515
+ accepted: null,
516
+ status: 'rejected',
517
+ };
518
+ await diagnostics.event('change_summary_rejected', {
519
+ phase: session.phase,
520
+ ...session.summaryCorrection,
521
+ details,
522
+ attempt: session.summaryFailures,
523
+ retryable: session.summaryFailures < 2,
524
+ });
525
+ }
526
+ }
527
+ function summarySubmissionFeedback(session) {
528
+ const rejected = session.summaryCorrection;
529
+ if (!rejected)
530
+ return {};
531
+ const retryable = session.summaryFailures < 2;
532
+ if (retryable) {
533
+ session.summaryFallbackOutput = session.output;
534
+ session.output = undefined;
535
+ }
536
+ return {
537
+ changeSummary: {
538
+ accepted: false,
539
+ ...rejected,
540
+ retryable,
541
+ instruction: retryable
542
+ ? 'Correct only changeSummary using source evidence, not publication references. Accepted criteria are retained; submit an empty assessments/entries array if none remain. Use null to omit the narrative if it cannot be supported.'
543
+ : 'Summary correction allowance exhausted; the invalid narrative is omitted. Continue only unfinished criteria.',
544
+ },
545
+ };
546
+ }
547
+ async function submitPhaseOutput(session, rawInput) {
548
+ if (!session.assessmentAccumulator)
549
+ return submitSinglePhaseOutput(session, rawInput);
550
+ let batch;
551
+ try {
552
+ batch = z
553
+ .strictObject({ assessments: z.array(z.unknown()), changeSummary: z.unknown().optional() })
554
+ .parse(rawInput);
555
+ }
556
+ catch (error) {
557
+ return rejectSubmission(session, rawInput, error);
558
+ }
559
+ await captureChangeSummary(session, batch.changeSummary);
560
+ const replies = [];
561
+ for (const [entryIndex, candidate] of batch.assessments.entries()) {
562
+ const reply = await submitSinglePhaseOutput(session, { assessments: [candidate], changeSummary: null });
563
+ replies.push({ ...reply, entryIndex });
564
+ }
565
+ const corrections = replies.filter((reply) => !reply.accepted);
566
+ if (remainingContexts(session).length === 0)
567
+ session.output = session.assessmentAccumulator.snapshot();
568
+ const summaryFeedback = summarySubmissionFeedback(session);
569
+ return {
570
+ ...(corrections[0] ?? {}),
571
+ accepted: corrections.length === 0,
572
+ complete: remainingContexts(session).length === 0 && session.output !== undefined,
573
+ ...summaryFeedback,
574
+ newlyAccepted: replies.flatMap((reply) => ('newlyAccepted' in reply ? reply.newlyAccepted : [])),
575
+ alreadyAccepted: replies.flatMap((reply) => ('alreadyAccepted' in reply ? reply.alreadyAccepted : [])),
576
+ remaining: remainingContexts(session),
577
+ corrections,
578
+ remainingCorrections: Math.max(0, 3 - correctionRounds(session)),
579
+ };
580
+ }
581
+ async function submitSinglePhaseOutput(session, rawInput) {
582
+ const { run, phase, workUnitId, assigned, schema, validate, attempt, signal, assessmentAccumulator } = session;
583
+ const { diagnostics, ledger } = run;
584
+ try {
585
+ signal.throwIfAborted();
586
+ const selectedInput = schema.parse(rawInput);
587
+ delete selectedInput.changeSummary;
588
+ if (session.output !== undefined && !assessmentAccumulator)
589
+ throw new Error('phase_already_submitted');
590
+ const input = resolveCitationSelections(selectedInput, ledger);
591
+ if (assessmentAccumulator) {
592
+ const progress = assessmentAccumulator.submit(input);
593
+ await persistPartialAssessment(session, progress);
594
+ if (progress.complete) {
595
+ const proposals = assessmentAccumulator.snapshot();
596
+ exactIds(proposals.map((p) => p.result.assessmentId), assigned.map((entry) => entry.assessmentId));
597
+ session.output = proposals;
598
+ }
599
+ await diagnostics.event('assessment_progress', {
600
+ phase,
601
+ workUnitId,
602
+ attempt,
603
+ newlyAccepted: progress.newlyAccepted,
604
+ alreadyAccepted: progress.alreadyAccepted,
605
+ remaining: progress.remaining,
606
+ });
607
+ if (progress.complete)
608
+ await diagnostics.event('submission_accepted', {
609
+ phase,
610
+ workUnitId,
611
+ attempt,
612
+ outputHash: digest(session.output),
613
+ });
614
+ return {
615
+ accepted: true,
616
+ ...progress,
617
+ remainingCorrections: Math.max(0, 3 - correctionRounds(session)),
618
+ };
619
+ }
620
+ session.output = validate(input);
621
+ await diagnostics.event('submission_accepted', {
622
+ phase,
623
+ workUnitId,
624
+ attempt,
625
+ outputHash: digest(session.output),
626
+ });
627
+ return { accepted: true };
628
+ }
629
+ catch (error) {
630
+ return rejectSubmission(session, rawInput, error);
631
+ }
632
+ }
633
+ function sourceTools(session) {
634
+ const { run, phase, workUnitId, attempt, signal } = session;
635
+ const { source, ledger, persist, diagnostics } = run;
636
+ const invoke = (name, body) => invokeTool(session, name, body);
637
+ return {
638
+ changes: tool({
639
+ strict: false,
640
+ description: 'Changed-file metadata only, not patch text or assessment proof. The prepared changedFiles inventory is complete when labelled complete. Each item.offset opens that file directly with diff({offset, patchLineOffset:0}); metadata paths alone do not establish applicability.',
641
+ inputSchema: z.object({ offset: integer, detectRenames: z.boolean().optional() }),
642
+ execute: (input) => invoke('changes', () => source.changes(input, { signal })),
643
+ }),
644
+ diff: tool({
645
+ strict: false,
646
+ description: 'Ordinary unified diff text with fixed file identities and continuations. Start at an item.offset from changedFiles/changes to inspect a selected file. Follow next when present; source-side reads provide citation evidence.',
647
+ inputSchema: z.object({
648
+ offset: integer,
649
+ patchLineOffset: integer,
650
+ detectRenames: z.boolean().optional(),
651
+ }),
652
+ execute: (input) => invoke('diff', () => source.diff(input, { signal })),
653
+ }),
654
+ list_source: tool({
655
+ strict: false,
656
+ description: 'List fixed snapshot source paths. Supporting unchanged source is available.',
657
+ inputSchema: z.object({ side: sourceSide, offset: integer }),
658
+ execute: (input) => invoke('list_source', () => source.list(input, { signal })),
659
+ }),
660
+ search_source: tool({
661
+ strict: false,
662
+ description: 'Literal source navigation. Optional path is one exact committed file, never a directory or glob; locate it with changedFiles/list_source, or omit path for a bounded tree search. Use exact returned cursor for continuation, not proof of semantic absence.',
663
+ inputSchema: z.object({
664
+ side: sourceSide,
665
+ literal: z.string().min(1),
666
+ path: z.string().nullish().describe('One exact committed file path; no directory or glob.'),
667
+ cursor: z
668
+ .object({
669
+ scope: z.string(),
670
+ entryOffset: z.number().int().nonnegative(),
671
+ characterOffset: z.number().int().nonnegative(),
672
+ })
673
+ .nullish(),
674
+ }),
675
+ execute: (input) => invoke('search_source', () => source.search({ ...input, path: input.path ?? undefined, cursor: input.cursor ?? undefined }, { signal })),
676
+ }),
677
+ read_source: tool({
678
+ strict: false,
679
+ description: 'Read committed text and receive evidence refs with numbered segments for range selection; follow next on truncation. No runtime execution.',
680
+ inputSchema: z.object({
681
+ side: sourceSide,
682
+ path: z.string(),
683
+ start: z
684
+ .object({ line: z.number().int().positive(), column: z.number().int().nonnegative() })
685
+ .optional(),
686
+ endLine: z.number().int().positive().optional(),
687
+ }),
688
+ execute: (input) => invoke('read_source', async () => {
689
+ if (sensitivePath(input.path))
690
+ return { status: 'unsupported', reason: 'credential_file_excluded', next: null };
691
+ const result = await source.read(input, { signal }), evidence = ledger.source(result);
692
+ await persist();
693
+ await diagnostics.event('source_evidence', {
694
+ phase,
695
+ workUnitId,
696
+ attempt,
697
+ status: result.status,
698
+ evidenceRefs: evidence ? [evidence.ref] : [],
699
+ });
700
+ const { fragments: _fragments, ...metadata } = result;
701
+ return {
702
+ ...metadata,
703
+ evidence: evidence ? modelEvidence(evidence) : null,
704
+ };
705
+ }),
706
+ }),
707
+ };
708
+ }
709
+ function createPhaseTools(session) {
710
+ const { run, phase, schema } = session;
711
+ const { ledger, persist } = run;
712
+ const evidencePack = run.evidencePack;
713
+ const invoke = (name, body) => invokeTool(session, name, body);
714
+ return {
715
+ read_publication: tool({
716
+ strict: false,
717
+ description: 'Read original pinned governing publication by its supplied context handle in assessmentId and returned page cursor. Follow next until complete; source text cannot waive rules.',
718
+ inputSchema: z.object({ assessmentId: z.string(), section: integer, offset: integer }),
719
+ execute: (input) => invoke('read_publication', async () => {
720
+ const result = readPackPublication(evidencePack, ledger, session.identifiers.fromModel(input));
721
+ await persist();
722
+ return result;
723
+ }),
724
+ }),
725
+ ...sourceTools(session),
726
+ [phase === 'assess' ? 'submit_assessments' : 'submit_verification']: tool({
727
+ strict: true,
728
+ description: phase === 'assess'
729
+ ? 'Submit one or more ready context assessments together. Each entry is validated independently; valid entries are retained when siblings need correction. Feedback lists remaining context handles. Independent verification is still required.'
730
+ : session.workUnitId === 'change-summary'
731
+ ? 'Submit the checked reader summary, or summary null if unsupported.'
732
+ : 'Submit one focused decision for the nominated concern. Establish applicability and evidence before confirming a violation.',
733
+ inputSchema: jsonSchema(zodSchema(schema).jsonSchema, { validate: (value) => ({ success: true, value }) }),
734
+ execute: async (rawInput) => session.identifiers.toModel(await submitPhaseOutput(session, session.identifiers.fromModel(rawInput))),
735
+ }),
736
+ };
737
+ }
738
+ function createProviderFetch(session) {
739
+ const { run, phase, workUnitId, attempt, phaseCalls, signal } = session;
740
+ const { state, diagnostics, models, options, budget, persist, previousCalls } = run;
741
+ return async (input, init) => {
742
+ signal.throwIfAborted();
743
+ const call = previousCalls + budget.reserve(phase);
744
+ state.execution.calls = previousCalls + budget.calls;
745
+ phaseCalls.push(call);
746
+ const item = {
747
+ call,
748
+ provider: models[phase].provider,
749
+ phase,
750
+ workUnitId,
751
+ usage: null,
752
+ missing: true,
753
+ };
754
+ state.execution.providerUsage.push(item);
755
+ const started = Date.now();
756
+ const request = providerRequestDiagnostics(init?.body);
757
+ const context = { phase, workUnitId, attempt, call, request };
758
+ await diagnostics
759
+ .event('provider_started', {
760
+ ...context,
761
+ provider: models[phase].provider,
762
+ model: models[phase].model,
763
+ })
764
+ .catch((error) => {
765
+ throw new ProviderAccountingError(error);
766
+ });
767
+ let recorded = false;
768
+ try {
769
+ const response = await (options.fetch ?? fetch)(input, init);
770
+ if (!response.ok) {
771
+ budget.record(null);
772
+ recorded = true;
773
+ const details = await providerResponseDiagnostics(response);
774
+ item.httpStatus = response.status;
775
+ item.failureCode = details.code;
776
+ await diagnostics.event('provider_failed', {
777
+ phase,
778
+ workUnitId,
779
+ attempt,
780
+ call,
781
+ status: response.status,
782
+ code: item.failureCode,
783
+ request,
784
+ details,
785
+ elapsedMs: Date.now() - started,
786
+ });
787
+ await persist();
788
+ return response;
789
+ }
790
+ const body = (await response.clone().json());
791
+ item.usage = normalizedWireUsage(body.usage);
792
+ item.missing = item.usage === null;
793
+ const usage = reportedUsage(models[phase].provider, item.usage);
794
+ budget.record(usage.totalTokens);
795
+ recorded = true;
796
+ state.execution.usage.push({
797
+ call,
798
+ phase,
799
+ provider: models[phase].provider,
800
+ ...Object.fromEntries(Object.entries(usage).filter(([key]) => key !== 'raw')),
801
+ });
802
+ state.execution.returnedIdentities.push({
803
+ provider: cleanIdentity(body.provider),
804
+ model: cleanIdentity(body.model),
805
+ });
806
+ await diagnostics.event('provider_completed', {
807
+ phase,
808
+ workUnitId,
809
+ attempt,
810
+ call,
811
+ status: response.status,
812
+ request,
813
+ elapsedMs: Date.now() - started,
814
+ usage: Object.fromEntries(Object.entries(usage).filter(([key]) => key !== 'raw')),
815
+ });
816
+ await persist();
817
+ return response;
818
+ }
819
+ catch (error) {
820
+ if (!recorded)
821
+ budget.record(null);
822
+ await diagnostics
823
+ .event(recorded ? 'provider_accounting_failed' : 'provider_failed', {
824
+ ...context,
825
+ elapsedMs: Date.now() - started,
826
+ details: {
827
+ ...providerFailureDiagnostics(error),
828
+ ...providerTransportDiagnostics(error),
829
+ ...systemFailureDiagnostics(error),
830
+ },
831
+ code: signal.aborted
832
+ ? 'cancelled'
833
+ : recorded
834
+ ? 'provider_accounting_failed'
835
+ : 'transport_or_response_invalid',
836
+ })
837
+ .catch(() => undefined);
838
+ throw recorded ? new ProviderAccountingError(error) : error;
839
+ }
840
+ };
841
+ }
842
+ async function runPhaseModel(session) {
843
+ const { run, phase, workUnitId, payload, attempt, signal, instructions } = session;
844
+ const { state, diagnostics, models, limits } = run;
845
+ const tools = createPhaseTools(session), wire = createProviderFetch(session);
846
+ const configured = assessmentModel(models[phase], wire);
847
+ const model = recoverProviderCalls(configured.model, signal, (event, count, error) => diagnostics.event(event, {
848
+ phase,
849
+ workUnitId,
850
+ attempt,
851
+ count,
852
+ call: state.execution.calls,
853
+ retryScope: 'request',
854
+ backoffMs: event === 'provider_retry' ? 250 * 2 ** (count - 1) : 0,
855
+ ...providerFailureDiagnostics(error),
856
+ }));
857
+ signal.throwIfAborted();
858
+ let continuation = 0;
859
+ let messages = [
860
+ { role: 'user', content: JSON.stringify(session.identifiers.toModel(sanitizeRecord(payload))) },
861
+ ];
862
+ for (; session.output === undefined;) {
863
+ const generated = await generateText({
864
+ ...configured,
865
+ model,
866
+ system: instructions,
867
+ messages,
868
+ tools,
869
+ maxRetries: 0,
870
+ abortSignal: signal,
871
+ ...(limits.maxOutputTokens === null ? {} : { maxOutputTokens: limits.maxOutputTokens }),
872
+ stopWhen: () => session.output !== undefined ||
873
+ session.rejected >= 3 ||
874
+ session.sdkStop !== null ||
875
+ session.phaseCalls.length >= (phase === 'assess' ? 60 : 12),
876
+ prepareStep: () => {
877
+ session.toolsThisStep = 0;
878
+ return phase === 'assess' && session.phaseCalls.length >= 58
879
+ ? { activeTools: ['submit_assessments'] }
880
+ : {};
881
+ },
882
+ onStepEnd: async (step) => {
883
+ state.execution.steps++;
884
+ await diagnostics.event('sdk_step', {
885
+ phase,
886
+ workUnitId,
887
+ attempt,
888
+ finishReason: step.finishReason,
889
+ });
890
+ for (const item of step.content)
891
+ if (item.type === 'tool-error' && item.toolName.startsWith('submit_')) {
892
+ session.stepRejected = true;
893
+ await diagnostics.event('submission_rejected', {
894
+ phase,
895
+ workUnitId,
896
+ attempt,
897
+ ...submissionToolDiagnostics(item, step.toolCalls),
898
+ remaining: remainingContexts(session),
899
+ tool: Object.prototype.hasOwnProperty.call(tools, item.toolName)
900
+ ? item.toolName
901
+ : 'unknown_tool',
902
+ outputHash: digest(item.input ?? null),
903
+ count: correctionRounds(session),
904
+ });
905
+ }
906
+ // Stop stalled corrections, not a larger review making validated progress.
907
+ // Reads and repeated accepted IDs do not reset the allowance.
908
+ session.rejected = correctionRounds(session);
909
+ session.remainingAtLastStep = remainingContexts(session).length;
910
+ session.stepRejected = false;
911
+ if (step.finishReason === 'length')
912
+ session.sdkStop = 'per_call_output_limit';
913
+ if (step.warnings?.some((w) => w.type === 'unsupported'))
914
+ session.sdkStop = 'provider_setting_unsupported';
915
+ },
916
+ });
917
+ if (session.output !== undefined ||
918
+ session.rejected >= 3 ||
919
+ session.sdkStop !== null ||
920
+ session.phaseCalls.length >= (phase === 'assess' ? 60 : 12) ||
921
+ continuation >= 2)
922
+ break;
923
+ continuation++;
924
+ messages = [
925
+ ...messages,
926
+ ...generated.response.messages,
927
+ {
928
+ role: 'user',
929
+ content: JSON.stringify({
930
+ instruction: 'Continue the same investigation. Submit only unfinished context handles; accepted judgments are immutable. Do not repeat completed work.',
931
+ remaining: session.identifiers.toModel({ remaining: remainingContexts(session) }).remaining,
932
+ }),
933
+ },
934
+ ];
935
+ await diagnostics.event(phase === 'assess' ? 'assessment_continuation' : 'verification_continuation', {
936
+ phase,
937
+ workUnitId,
938
+ attempt,
939
+ count: continuation,
940
+ remaining: remainingContexts(session),
941
+ });
942
+ }
943
+ signal.throwIfAborted();
944
+ if (session.sdkStop !== null)
945
+ throw new BudgetStop(session.sdkStop);
946
+ if (session.output === undefined)
947
+ throw new BudgetStop(session.phaseCalls.length >= (phase === 'assess' ? 60 : 12)
948
+ ? 'model_call_limit'
949
+ : session.rejected >= 3
950
+ ? 'phase_corrections_exhausted'
951
+ : 'model_stopped');
952
+ }
953
+ function knownExecutionFailure(error) {
954
+ const codes = [
955
+ 'provider_credential_missing',
956
+ 'provider_selection_invalid',
957
+ 'provider_model_missing',
958
+ 'provider_setting_unsupported',
959
+ 'upstream_artifact_changed',
960
+ 'upstream_phase_changed',
961
+ 'pinned_material_changed',
962
+ ];
963
+ return error instanceof Error && codes.includes(error.message) ? error.message : 'provider_or_execution_failed';
964
+ }
965
+ function phaseStopReason(session, failure) {
966
+ if (!failure)
967
+ return null;
968
+ if (failure instanceof BudgetStop)
969
+ return failure.code;
970
+ if (session.signal.aborted) {
971
+ if (session.run.options.signal?.aborted)
972
+ return 'cancelled';
973
+ return session.phase === 'verify' ? 'max_time_ms' : 'max_time_ms';
974
+ }
975
+ return knownExecutionFailure(failure);
976
+ }
977
+ async function persistPhaseResult(session, failure) {
978
+ const { run, phase, workUnitId, assigned, attempt, startedAt, inputRefs, phaseCalls, signal, instructions } = session;
979
+ const { state, directory, ledger, diagnostics, models, persist } = run;
980
+ const partial = failure && phase === 'assess' && session.assessmentAccumulator?.snapshot().length
981
+ ? {
982
+ assessments: session.assessmentAccumulator.snapshot(),
983
+ remaining: session.assessmentAccumulator.remaining(),
984
+ }
985
+ : failure && session.verifications?.size
986
+ ? {
987
+ verifications: [...session.verifications.values()].map((entry) => entry.result),
988
+ remaining: remainingContexts(session),
989
+ }
990
+ : null;
991
+ if (failure && phase === 'verify' && state.changeSummary) {
992
+ state.changeSummary.accepted = null;
993
+ state.changeSummary.status = 'pending';
994
+ }
995
+ const record = createPhaseRecord({
996
+ runId: state.runId,
997
+ phase,
998
+ workUnitId,
999
+ attempt,
1000
+ startedAt,
1001
+ finishedAt: new Date().toISOString(),
1002
+ status: failure ? (signal.aborted ? 'cancelled' : 'failed') : 'complete',
1003
+ inputRefs,
1004
+ artifact: state.artifact,
1005
+ scopeIdentity: state.scopeIdentity,
1006
+ assessmentIds: assigned.map((e) => e.assessmentId),
1007
+ evidenceRefs: Object.keys(ledger.records),
1008
+ limitations: [],
1009
+ stopReason: phaseStopReason(session, failure),
1010
+ configuration: {
1011
+ provider: models[phase].provider,
1012
+ model: models[phase].model,
1013
+ effort: models[phase].effort ?? null,
1014
+ ...(partial
1015
+ ? { kind: phase === 'assess' ? 'partial_assessment_progress' : 'partial_verification_progress' }
1016
+ : {}),
1017
+ modelIdentifiers: session.identifiers.snapshot(),
1018
+ promptVersion: 'candidate-observation-v3',
1019
+ maxPhaseCalls: phase === 'assess' ? 60 : 12,
1020
+ maxSourceToolsPerResponse: 50,
1021
+ validationConcurrency: 2,
1022
+ promptHash: digest(instructions),
1023
+ sdkVersion: runtimeVersion('ai'),
1024
+ adapter: '@ai-sdk/openai',
1025
+ adapterVersion: runtimeVersion('@ai-sdk/openai'),
1026
+ },
1027
+ usageRefs: phaseCalls.map((c) => `call:${c}`),
1028
+ output: run.state.changeSummary
1029
+ ? {
1030
+ ...(partial ?? { [phase === 'assess' ? 'assessments' : 'entries']: session.output ?? [] }),
1031
+ changeSummary: phase === 'assess' ? run.state.changeSummary.candidate : run.state.changeSummary.accepted,
1032
+ }
1033
+ : (partial ?? session.output ?? null),
1034
+ });
1035
+ const filename = phaseFilename(phase, workUnitId, attempt);
1036
+ await atomicJson(join(directory, 'phases', filename), sanitizeRecord(record));
1037
+ state.phases.push(record);
1038
+ await persist();
1039
+ if (failure)
1040
+ throw failure;
1041
+ const persisted = JSON.parse(await readFile(join(directory, 'phases', filename), 'utf8'));
1042
+ validatePhaseRecord(persisted, {
1043
+ runId: state.runId,
1044
+ artifact: state.artifact,
1045
+ scopeIdentity: state.scopeIdentity,
1046
+ assessmentIds: assigned.map((e) => e.assessmentId),
1047
+ inputRefs,
1048
+ phase,
1049
+ workUnitId,
1050
+ attempt,
1051
+ });
1052
+ await diagnostics.event('phase_completed', {
1053
+ phase,
1054
+ workUnitId,
1055
+ attempt,
1056
+ outputHash: record.outputHash,
1057
+ elapsedMs: Date.now() - Date.parse(startedAt),
1058
+ });
1059
+ // Reconciliation works on a copy; persisted handoffs remain immutable.
1060
+ return structuredClone(session.output);
1061
+ }
1062
+ async function recoverSummaryOnlyFailure(session, error) {
1063
+ if (session.summaryFallbackOutput === undefined ||
1064
+ remainingContexts(session).length ||
1065
+ session.run.options.signal?.aborted ||
1066
+ error instanceof ProviderAccountingError ||
1067
+ knownExecutionFailure(error) !== 'provider_or_execution_failed')
1068
+ return false;
1069
+ session.output = session.summaryFallbackOutput;
1070
+ const summary = session.run.state.changeSummary;
1071
+ if (summary && summary.status !== 'verified') {
1072
+ summary.accepted = null;
1073
+ summary.status = 'rejected';
1074
+ }
1075
+ await session.run.diagnostics.event('change_summary_correction_failed', {
1076
+ phase: session.phase,
1077
+ code: phaseStopReason(session, error),
1078
+ criteriaPreserved: true,
1079
+ ...providerFailureDiagnostics(error),
1080
+ });
1081
+ return true;
1082
+ }
1083
+ async function invokePhase(run, phase, workUnitId, assigned, payload, schema, validate, attempt = 1) {
1084
+ const session = await createPhaseRuntime(run, phase, workUnitId, assigned, payload, schema, validate, attempt);
1085
+ await run.diagnostics.event('phase_started', { phase, workUnitId, attempt, inputHash: session.inputRefs[0].hash });
1086
+ let failure;
1087
+ try {
1088
+ await runPhaseModel(session);
1089
+ }
1090
+ catch (error) {
1091
+ if (!(await recoverSummaryOnlyFailure(session, error))) {
1092
+ failure = session.signal.aborted ? new BudgetStop(phaseStopReason(session, error)) : error;
1093
+ await run.diagnostics.event('phase_failed', {
1094
+ elapsedMs: Date.now() - Date.parse(session.startedAt),
1095
+ phase,
1096
+ workUnitId,
1097
+ attempt,
1098
+ code: error instanceof BudgetStop
1099
+ ? error.code
1100
+ : session.signal.aborted
1101
+ ? 'phase_deadline_or_cancelled'
1102
+ : 'provider_or_execution_failed',
1103
+ details: { ...providerFailureDiagnostics(error), ...systemFailureDiagnostics(error) },
1104
+ });
1105
+ }
1106
+ }
1107
+ finally {
1108
+ if (session.timer !== null)
1109
+ clearTimeout(session.timer);
1110
+ }
1111
+ try {
1112
+ return await persistPhaseResult(session, failure);
1113
+ }
1114
+ catch (error) {
1115
+ // persistPhaseResult rethrows the model failure after saving its handoff.
1116
+ // Only a different failure here means the handoff itself could not be persisted or validated.
1117
+ if (error !== failure) {
1118
+ await run.diagnostics
1119
+ .event(failure ? 'phase_persistence_failed' : 'phase_failed', {
1120
+ phase,
1121
+ workUnitId,
1122
+ attempt,
1123
+ code: 'phase_artifact_failed',
1124
+ elapsedMs: Date.now() - Date.parse(session.startedAt),
1125
+ details: { ...providerFailureDiagnostics(error), ...systemFailureDiagnostics(error) },
1126
+ })
1127
+ .catch(() => undefined);
1128
+ }
1129
+ throw failure ?? error;
1130
+ }
1131
+ }
1132
+ const latestAssessment = (run) => run.state.phases.filter((phase) => phase.phase === 'assess' && phase.workUnitId === 'all').at(-1);
1133
+ const nextAttempt = (run, phase) => Math.max(0, ...run.state.phases
1134
+ .filter((record) => record.phase === phase && record.workUnitId === 'all')
1135
+ .map((record) => record.attempt)) + 1;
1136
+ function artifactPrContext(context) {
1137
+ if (!context || context.version === 1)
1138
+ return context;
1139
+ const { observedChecks: _observedChecks, ...artifactContext } = context;
1140
+ return artifactContext;
1141
+ }
1142
+ const artifactEvidenceBoundary = {
1143
+ available: 'Pinned repository source, diff, supplied publications and prepared evidence. Read repository implementation beyond the diff when needed.',
1144
+ external: [
1145
+ 'External dependency internals not supplied in the repository',
1146
+ 'Live operational state or execution receipts',
1147
+ 'Business records outside the supplied artifacts',
1148
+ ],
1149
+ incompleteWork: 'Unread or paged source, tool failures, budgets and ambiguous requirements are not external evidence exemptions.',
1150
+ };
1151
+ function baseAssessmentPayload(run) {
1152
+ return {
1153
+ reviewer: run.state.reviewer,
1154
+ artifact: run.state.artifact,
1155
+ purpose: run.options.purpose ?? null,
1156
+ prContext: artifactPrContext(run.prContext),
1157
+ governingEvidence: modelPackEvidence(run.evidencePack, run.ledger),
1158
+ diff: run.modelDiff,
1159
+ repositoryInstructions: run.repositoryInstructions,
1160
+ changedFiles: run.prepared.state.changes,
1161
+ sourceLimits: run.source.limits,
1162
+ artifactEvidenceBoundary,
1163
+ };
1164
+ }
1165
+ async function prepareRunEvidence(run) {
1166
+ const { state, directory, prepared, prContext, material, ledger } = run;
1167
+ run.modelDiff = await modelDiffEvidence(directory, run.preparedManifest.files?.['diff.patch'], prepared.state.diff);
1168
+ await atomicJson(join(directory, 'prepared.json'), sanitizeRecord(prepared.state));
1169
+ if (prContext)
1170
+ await atomicJson(join(directory, 'pr-context.json'), sanitizeRecord(prContext));
1171
+ for (const entry of state.entries) {
1172
+ if (!entry.material)
1173
+ continue;
1174
+ const pinned = publicationSchema.parse(material[entry.assessmentId]);
1175
+ if (pinned.nodeId !== entry.nodeId ||
1176
+ pinned.version !== entry.version ||
1177
+ pinned.subtype !== entry.subtype ||
1178
+ digest(pinned.content) !== entry.contentHash)
1179
+ throw new Error('pinned_material_changed');
1180
+ }
1181
+ for (const publication of Object.values(material))
1182
+ ledger.publication(publication);
1183
+ run.evidencePack = prepareEvidencePack({ state: prepared.state, publications: material, ledger });
1184
+ await writeEvidencePack(directory, run.evidencePack);
1185
+ const remaining = run.budget.remainingMs('assess');
1186
+ if (remaining !== null && remaining <= 0)
1187
+ throw new BudgetStop('max_time_ms');
1188
+ const deadline = remaining === null ? undefined : AbortSignal.timeout(Math.ceil(remaining));
1189
+ const signals = [run.options.signal, deadline].filter((value) => value !== undefined);
1190
+ try {
1191
+ run.repositoryInstructions = await repositoryInstructionsEvidence(run.source, ledger, signals.length ? AbortSignal.any(signals) : undefined);
1192
+ }
1193
+ catch (error) {
1194
+ if (deadline?.aborted)
1195
+ throw new BudgetStop('max_time_ms');
1196
+ throw error;
1197
+ }
1198
+ await run.persist();
1199
+ }
1200
+ async function restorePartialProposals(run) {
1201
+ if (!run.options.resume)
1202
+ return;
1203
+ const last = latestAssessment(run);
1204
+ if (!last)
1205
+ return;
1206
+ const partial = JSON.parse(await readFile(join(run.directory, 'phases', `partial-assess-all-${last.attempt}.json`), 'utf8').catch(() => 'null'));
1207
+ if (!partial)
1208
+ return;
1209
+ const { state, ledger } = run;
1210
+ validatePhaseRecord(partial, {
1211
+ runId: state.runId,
1212
+ artifact: state.artifact,
1213
+ scopeIdentity: state.scopeIdentity,
1214
+ assessmentIds: state.entries.map((entry) => entry.assessmentId),
1215
+ inputRefs: last.inputRefs,
1216
+ phase: 'assess',
1217
+ workUnitId: 'all',
1218
+ attempt: last.attempt,
1219
+ requireComplete: false,
1220
+ });
1221
+ if (partial.output.changeSummary)
1222
+ state.changeSummary = {
1223
+ candidate: revalidateSummary(partial.output.changeSummary, ledger),
1224
+ accepted: null,
1225
+ status: 'pending',
1226
+ };
1227
+ run.retainedProposals = partial.output.assessments.map((proposal) => revalidateCandidate(proposal, state.entries, ledger));
1228
+ }
1229
+ async function assessRun(run) {
1230
+ const previous = latestAssessment(run), { state, ledger } = run;
1231
+ if (previous?.status === 'complete') {
1232
+ const proposals = phaseItems(previous.output, 'assessments');
1233
+ const summary = previous.output.changeSummary;
1234
+ if (summary)
1235
+ state.changeSummary = { candidate: revalidateSummary(summary, ledger), accepted: null, status: 'pending' };
1236
+ exactIds(proposals.map((p) => p.result.assessmentId), state.entries.map((entry) => entry.assessmentId));
1237
+ return proposals.map((proposal) => revalidateCandidate(proposal, state.entries, ledger));
1238
+ }
1239
+ await restorePartialProposals(run);
1240
+ return invokePhase(run, 'assess', 'all', state.entries, {
1241
+ ...baseAssessmentPayload(run),
1242
+ expectedChecklist: state.entries.map(({ result: _result, ...entry }) => entry),
1243
+ evidencePack: run.evidencePack.index,
1244
+ retained: run.retainedProposals,
1245
+ remaining: state.entries
1246
+ .filter((entry) => !run.retainedProposals.some((p) => p.result.assessmentId === entry.assessmentId))
1247
+ .map((entry) => entry.assessmentId),
1248
+ }, candidateSelectionSchema, () => {
1249
+ throw new Error('assessment_accumulator_required');
1250
+ }, nextAttempt(run, 'assess'));
1251
+ }
1252
+ async function verifyRun(run, assessments) {
1253
+ const { state, ledger } = run;
1254
+ const observations = assessments.flatMap((p) => p.observations ?? []);
1255
+ if (assessments.some((p) => !p.observations))
1256
+ throw Error('candidate_checkpoint_required');
1257
+ state.observations = observations;
1258
+ const concerns = observations.filter((o) => o.concern !== null);
1259
+ const decisions = [];
1260
+ state.concernDecisions = decisions;
1261
+ const validation = {
1262
+ expected: concerns.length,
1263
+ validated: 0,
1264
+ complete: false,
1265
+ scope: 'nominated_concerns',
1266
+ };
1267
+ state.concernValidation = validation;
1268
+ const validateOne = async (observation) => {
1269
+ const entry = state.entries.find((e) => e.assessmentId === observation.assessmentId);
1270
+ const prior = state.phases
1271
+ .filter((p) => p.phase === 'verify' && p.workUnitId === observation.id && p.status === 'complete')
1272
+ .at(-1);
1273
+ let decision;
1274
+ if (prior) {
1275
+ const saved = (prior.output?.entries ?? prior.output);
1276
+ decision = validateConcern({
1277
+ decision: saved.decision,
1278
+ externalEvidence: saved.externalEvidence,
1279
+ reason: saved.reason,
1280
+ duty: saved.duty,
1281
+ suggestionAccepted: saved.suggestionAccepted,
1282
+ applicability: saved.applicability,
1283
+ consequence: saved.consequence,
1284
+ correction: saved.correction,
1285
+ sourceRefs: saved.sourceRefs.map(({ ref, quote, start, end }) => ({ ref, quote, start, end })),
1286
+ }, observation, ledger);
1287
+ }
1288
+ else {
1289
+ decision = await invokePhase(run, 'verify', observation.id, [entry], {
1290
+ reviewer: state.reviewer,
1291
+ purpose: run.options.purpose ?? null,
1292
+ prContext: artifactPrContext(run.prContext),
1293
+ publication: run.material[entry.assessmentId],
1294
+ observation,
1295
+ artifactEvidenceBoundary,
1296
+ governingEvidence: {
1297
+ evidence: [modelEvidence(ledger.records[observation.passage.ref])],
1298
+ selectedPassage: {
1299
+ ref: observation.passage.ref,
1300
+ startOffset: observation.passage.start,
1301
+ endOffset: observation.passage.end,
1302
+ },
1303
+ },
1304
+ sourceEvidence: modelSourceEvidence(ledger, observation.sourceRefs.map((c) => c.ref)),
1305
+ }, concernDecisionSchema, (value) => validateConcern(value, observation, ledger), 1 +
1306
+ Math.max(0, ...state.phases
1307
+ .filter((p) => p.phase === 'verify' && p.workUnitId === observation.id)
1308
+ .map((p) => p.attempt)));
1309
+ }
1310
+ decisions.push(decision);
1311
+ validation.validated++;
1312
+ projectCandidates(state, assessments, decisions);
1313
+ await run.persist();
1314
+ };
1315
+ let cursor = 0;
1316
+ const failures = [];
1317
+ await Promise.all(Array.from({ length: Math.min(2, concerns.length) }, async () => {
1318
+ while (cursor < concerns.length) {
1319
+ const observation = concerns[cursor++];
1320
+ try {
1321
+ await validateOne(observation);
1322
+ }
1323
+ catch (error) {
1324
+ failures.push(error);
1325
+ }
1326
+ }
1327
+ }));
1328
+ projectCandidates(state, assessments, decisions);
1329
+ validation.complete = validation.validated === validation.expected;
1330
+ state.verification = {
1331
+ expected: concerns.length,
1332
+ verified: validation.validated,
1333
+ complete: validation.complete,
1334
+ };
1335
+ if (failures.length)
1336
+ throw failures[0];
1337
+ await verifyCandidateSummary(run);
1338
+ state.execution.scope =
1339
+ 'Standards observations with independent validation of nominated concerns only. No concern identified does not establish whole-standard compliance. Operational outcomes and missing premises remain separate.';
1340
+ }
1341
+ async function verifyCandidateSummary(run) {
1342
+ const candidate = run.state.changeSummary?.candidate;
1343
+ if (!candidate)
1344
+ return;
1345
+ try {
1346
+ const prior = run.state.phases
1347
+ .filter((p) => p.phase === 'verify' && p.workUnitId === 'change-summary' && p.status === 'complete')
1348
+ .at(-1);
1349
+ const value = prior
1350
+ ? (prior.output?.entries ?? prior.output)
1351
+ : await invokePhase(run, 'verify', 'change-summary', run.state.entries, {
1352
+ artifact: run.state.artifact,
1353
+ summary: candidate,
1354
+ diff: run.modelDiff,
1355
+ sourceEvidence: modelSourceEvidence(run.ledger, candidate.sourceRefs.map((c) => c.ref)),
1356
+ }, z.strictObject({ summary: changeSummarySelectionSchema.nullable() }), (input) => {
1357
+ const value = input;
1358
+ return {
1359
+ summary: value.summary === null ? null : validateChangeSummary(value.summary, run.ledger),
1360
+ };
1361
+ }, 1 +
1362
+ Math.max(0, ...run.state.phases.filter((p) => p.workUnitId === 'change-summary').map((p) => p.attempt)));
1363
+ run.state.changeSummary = {
1364
+ candidate,
1365
+ accepted: value.summary === null ? null : revalidateSummary(value.summary, run.ledger),
1366
+ status: value.summary === null ? 'rejected' : 'verified',
1367
+ };
1368
+ }
1369
+ catch (error) {
1370
+ const optionalContentStop = error instanceof BudgetStop &&
1371
+ ['model_call_limit', 'phase_corrections_exhausted', 'model_stopped'].includes(error.code);
1372
+ if (run.options.signal?.aborted || !optionalContentStop)
1373
+ throw error;
1374
+ run.state.changeSummary = { candidate, accepted: null, status: 'pending' };
1375
+ run.state.limitations.push('Reader change summary verification did not complete; standards concern outcomes are retained.');
1376
+ }
1377
+ }
1378
+ async function executeAssessment(run) {
1379
+ await prepareRunEvidence(run);
1380
+ const { state, models, options, prepared, preparedManifest, diagnostics } = run;
1381
+ if (state.preparationStatus !== 'prepared') {
1382
+ state.execution.stopReason = 'preparation_incomplete';
1383
+ return true;
1384
+ }
1385
+ for (const phase of ['assess', 'verify'])
1386
+ assessmentModel(models[phase], options.fetch ?? fetch);
1387
+ if (prepared.state.changes?.status !== 'complete' ||
1388
+ preparedManifest.changesHash !== digest(prepared.state.changes)) {
1389
+ await diagnostics.event('preparation_inventory_rejected', { code: 'upstream_artifact_changed' });
1390
+ throw new Error('upstream_artifact_changed');
1391
+ }
1392
+ await verifyRun(run, await assessRun(run));
1393
+ const newPhases = state.phases.slice(run.invocationPhaseIndex).filter((p) => p.workUnitId !== 'change-summary');
1394
+ state.execution.stopReason = newPhases.find((phase) => phase.status !== 'complete')?.stopReason ?? 'finished';
1395
+ return newPhases.some((phase) => phase.status !== 'complete');
1396
+ }
1397
+ export async function runAssessment(options) {
1398
+ const run = await createAssessmentRuntime(options);
1399
+ let executionFailure = false;
1400
+ try {
1401
+ executionFailure = await executeAssessment(run);
1402
+ }
1403
+ catch (error) {
1404
+ executionFailure = true;
1405
+ run.state.execution.stopReason =
1406
+ error instanceof BudgetStop
1407
+ ? error.code
1408
+ : options.signal?.aborted
1409
+ ? 'cancelled'
1410
+ : knownExecutionFailure(error);
1411
+ await run.diagnostics
1412
+ .event('execution_stopped', {
1413
+ code: run.state.execution.stopReason,
1414
+ details: { ...providerFailureDiagnostics(error), ...systemFailureDiagnostics(error) },
1415
+ })
1416
+ .catch(() => undefined);
1417
+ }
1418
+ return finalizeAssessment(run, executionFailure);
1419
+ }
1420
+ async function deliverAssessmentFeedback(state, options) {
1421
+ let cleanupTimer;
1422
+ try {
1423
+ return await Promise.race([
1424
+ sendAssessmentReport(state, {
1425
+ mode: options.feedback,
1426
+ sender: options.feedbackSender,
1427
+ repositoryAttribution: options.repositoryAttribution,
1428
+ }),
1429
+ new Promise((resolve) => {
1430
+ cleanupTimer = setTimeout(() => resolve({ status: 'failed', code: 'submission_failed' }), 10_000);
1431
+ }),
1432
+ ]);
1433
+ }
1434
+ finally {
1435
+ if (cleanupTimer !== undefined)
1436
+ clearTimeout(cleanupTimer);
1437
+ }
1438
+ }
1439
+ async function sealReportArtifacts(directory, state) {
1440
+ const hashes = {};
1441
+ for (const name of await readdir(directory)) {
1442
+ if (name === 'manifest.json' || name.endsWith('.tmp'))
1443
+ continue;
1444
+ if (name === 'phases') {
1445
+ for (const child of await readdir(join(directory, name)))
1446
+ hashes[`${name}/${child}`] = `sha256:${createHash('sha256')
1447
+ .update(await readFile(join(directory, name, child)))
1448
+ .digest('hex')}`;
1449
+ }
1450
+ else
1451
+ hashes[name] = `sha256:${createHash('sha256')
1452
+ .update(await readFile(join(directory, name)))
1453
+ .digest('hex')}`;
1454
+ }
1455
+ let original = {};
1456
+ try {
1457
+ original = JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8'));
1458
+ }
1459
+ catch {
1460
+ original = {};
1461
+ }
1462
+ await atomicJson(join(directory, 'manifest.json'), {
1463
+ ...original,
1464
+ runId: state.runId,
1465
+ files: hashes,
1466
+ capture: state.execution.capture,
1467
+ });
1468
+ }
1469
+ async function finalizeAssessment(run, executionFailure) {
1470
+ const { state, directory, budget, diagnostics, persist, options, prepared, previousElapsed } = run;
1471
+ state.execution.elapsedMs = previousElapsed + Date.now() - budget.started;
1472
+ state.decision = decideExit(state.entries, state.execution.policy, !state.verification.complete || state.preparationStatus !== 'prepared', executionFailure, state.findings);
1473
+ state.assessmentStatus = state.decision.complete && !executionFailure ? 'complete' : 'incomplete';
1474
+ const reportPath = join(directory, 'report.json');
1475
+ const started = performance.now();
1476
+ const primaryStopReason = state.execution.stopReason;
1477
+ let stage = 'diagnostics';
1478
+ try {
1479
+ await diagnostics.event('assessment_finalization_started', {
1480
+ status: state.assessmentStatus,
1481
+ exitCode: state.decision.exitCode,
1482
+ elapsedMs: state.execution.elapsedMs,
1483
+ complete: state.verification.complete,
1484
+ });
1485
+ stage = 'state_write';
1486
+ await persist();
1487
+ stage = 'json_report';
1488
+ await atomicJson(reportPath, sanitizeRecord(state));
1489
+ stage = 'markdown_report';
1490
+ await writeFile(join(directory, 'report.md'), markdownReport(state), { mode: 0o600 });
1491
+ stage = 'feedback';
1492
+ state.execution.reporting = await deliverAssessmentFeedback(state, options);
1493
+ await diagnostics.event('assessment_reporting', { reporting: state.execution.reporting.status });
1494
+ stage = 'reporting_status';
1495
+ await atomicJson(join(directory, 'reporting-status.json'), {
1496
+ runId: state.runId,
1497
+ reporting: state.execution.reporting,
1498
+ });
1499
+ stage = 'state_write';
1500
+ await persist();
1501
+ stage = 'json_report';
1502
+ await atomicJson(reportPath, sanitizeRecord(state));
1503
+ stage = 'markdown_report';
1504
+ await writeFile(join(directory, 'report.md'), markdownReport(state), { mode: 0o600 });
1505
+ stage = 'diagnostics';
1506
+ await diagnostics.event('assessment_finalized', {
1507
+ status: state.assessmentStatus,
1508
+ exitCode: state.decision.exitCode,
1509
+ elapsedMs: state.execution.elapsedMs,
1510
+ complete: state.verification.complete,
1511
+ });
1512
+ await diagnostics.flush();
1513
+ stage = 'artifact_seal';
1514
+ await sealReportArtifacts(directory, state);
1515
+ }
1516
+ catch (error) {
1517
+ state.decision = { ...state.decision, exitCode: 2 };
1518
+ state.assessmentStatus = 'incomplete';
1519
+ state.execution.stopReason = executionFailure ? primaryStopReason : 'report_delivery_failed';
1520
+ await diagnostics
1521
+ .event('finalization_failed', {
1522
+ code: 'report_delivery_failed',
1523
+ primaryStopReason,
1524
+ stage,
1525
+ elapsedMs: performance.now() - started,
1526
+ details: { ...providerFailureDiagnostics(error), ...systemFailureDiagnostics(error) },
1527
+ })
1528
+ .catch(() => undefined);
1529
+ if (state.execution.reporting.status === 'pending')
1530
+ state.execution.reporting =
1531
+ options.feedback === 'off' ? { status: 'off' } : { status: 'failed', code: 'finalization_unavailable' };
1532
+ await atomicJson(prepared.statePath, sanitizeRecord(state)).catch(() => undefined);
1533
+ await atomicJson(reportPath, sanitizeRecord(state)).catch(() => undefined);
1534
+ }
1535
+ return { state: sanitizeRecord(state), statePath: prepared.statePath, reportPath, directory };
1536
+ }
1537
+ function markdownReport(state) {
1538
+ const coverage = assessmentCoverage(state);
1539
+ const progressLabel = (assessmentId) => {
1540
+ const progress = coverage.entries.find((p) => p.assessmentId === assessmentId);
1541
+ if (externalEvidenceAssessmentIds(state).has(assessmentId) &&
1542
+ state.entries.find((entry) => entry.assessmentId === assessmentId)?.result.disposition === 'observed')
1543
+ return 'Observed with an independently classified external evidence limitation; external adherence was not assessed.';
1544
+ return assessmentProgressLabel(progress?.status ?? 'unexamined', state.concernValidation?.scope === 'nominated_concerns');
1545
+ };
1546
+ return (`# Standards assessment ${state.runId}\n\nAssessment: **${state.assessmentStatus}**; review exit ${state.decision?.reviewExit}; process exit ${state.decision?.exitCode}.\n\n${state.artifact.base.commit} → ${state.artifact.head.commit}\n\n[Open prepared Git diff](diff.patch) · [Preparation summary](preparation.md)\n\nAssessed ${coverage.assessed}/${coverage.total} governed context assessments; ${coverage.awaitingVerification} awaiting independent verification; ${coverage.needsReassessment} need reassessment; ${coverage.savedProposals} saved proposals with an incomplete assessment handoff; ${coverage.unexamined} unexamined. ${state.concernValidation?.scope === 'nominated_concerns' ? 'Nominated concerns checked' : 'Verified'} ${state.verification.verified}/${state.verification.expected}. Assessment proposals are not accepted findings until independently verified. No runtime tests were executed.\n\n` +
1547
+ 'The JSON diff field is the initial paged diff view: truncated means that view has more content or a bounded patch, not that diff.patch is incomplete. See preparation.md for full permitted capture availability and exclusions. Additional pinned source can be read through tools; capture and availability do not establish what the assessor examined.\n\n' +
1548
+ renderReaderGuidance(state) +
1549
+ '\n\n' +
1550
+ state.entries
1551
+ .map((e) => {
1552
+ const r = e.result;
1553
+ const unscored = state.concernValidation?.scope === 'nominated_concerns' && r.disposition !== 'not_evaluated'
1554
+ ? 'not scored under this method'
1555
+ : 'unknown';
1556
+ return (`## ${e.nodeId} @${e.version}\n\n${progressLabel(e.assessmentId)}\n\nFinal canonical outcome: ${r.disposition}; adherence ${r.adherence ?? unscored}; confidence ${r.confidence ?? unscored}\n\n` +
1557
+ ('explanation' in r
1558
+ ? `${r.explanation}\n\nCorrection: ${r.correction}\n\nLimits: ${r.limitations.join('; ')}\n\n${r.citations.map((c) => `${c.ref}: ${JSON.stringify(c.quote)}`).join('\n\n')}`
1559
+ : progressLabel(e.assessmentId)));
1560
+ })
1561
+ .join('\n\n') +
1562
+ `\n\n## Run details\n\nPhase models: ${JSON.stringify(state.execution.phaseModels)}\n\nDuration ${state.execution.elapsedMs}ms; ${state.execution.calls} calls; stop ${state.execution.stopReason}.\n\n${state.execution.capture}\n`);
1563
+ }