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

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 +1548 -0
  7. package/dist/assessment.d.ts +566 -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 +147 -0
  12. package/dist/candidate.js +321 -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 +140 -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 +309 -0
  44. package/dist/presentation.js +1026 -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 +132 -0
  50. package/dist/report-contract.js +240 -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 +156 -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 +203 -0
  69. package/docs/review-results.md +173 -0
  70. package/docs/security.md +64 -0
  71. package/docs/standards.md +62 -0
  72. package/examples/assess-pull-request.yml +109 -0
  73. package/package.json +56 -5
@@ -0,0 +1,132 @@
1
+ import { z } from 'zod';
2
+ export declare const reviewReportInputSchema: z.ZodObject<{
3
+ kind: z.ZodLiteral<"review_report">;
4
+ contractVersion: z.ZodLiteral<1>;
5
+ runId: z.ZodString;
6
+ origin: z.ZodEnum<{
7
+ npm: "npm";
8
+ agent_skill: "agent_skill";
9
+ }>;
10
+ packageVersion: z.ZodNullable<z.ZodString>;
11
+ methodVersion: z.ZodString;
12
+ reviewer: z.ZodObject<{
13
+ nodeId: z.ZodString;
14
+ version: z.ZodNumber;
15
+ }, z.core.$strict>;
16
+ repository: z.ZodDiscriminatedUnion<[z.ZodObject<{
17
+ status: z.ZodLiteral<"unavailable">;
18
+ reason: z.ZodEnum<{
19
+ no_remote: "no_remote";
20
+ ambiguous_remote: "ambiguous_remote";
21
+ not_determined: "not_determined";
22
+ withheld: "withheld";
23
+ no_workspace: "no_workspace";
24
+ not_git_repository: "not_git_repository";
25
+ }>;
26
+ }, z.core.$strict>, z.ZodObject<{
27
+ status: z.ZodLiteral<"reported">;
28
+ provider: z.ZodString;
29
+ owner: z.ZodString;
30
+ name: z.ZodString;
31
+ }, z.core.$strict>], "status">;
32
+ scope: z.ZodObject<{
33
+ enumeration: z.ZodEnum<{
34
+ complete: "complete";
35
+ incomplete: "incomplete";
36
+ }>;
37
+ expectedCount: z.ZodNullable<z.ZodNumber>;
38
+ expected: z.ZodArray<z.ZodObject<{
39
+ entryId: z.ZodString;
40
+ context: z.ZodObject<{
41
+ nodeId: z.ZodString;
42
+ version: z.ZodNullable<z.ZodNumber>;
43
+ }, z.core.$strict>;
44
+ }, z.core.$strict>>;
45
+ }, z.core.$strict>;
46
+ outcomes: z.ZodArray<z.ZodObject<{
47
+ entryId: z.ZodString;
48
+ disposition: z.ZodEnum<{
49
+ not_evaluated: "not_evaluated";
50
+ evaluated: "evaluated";
51
+ observed: "observed";
52
+ not_applicable: "not_applicable";
53
+ unresolved: "unresolved";
54
+ }>;
55
+ adherence: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodNull]>;
56
+ confidence: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodNull]>;
57
+ finding: z.ZodEnum<{
58
+ none: "none";
59
+ binding_violation: "binding_violation";
60
+ behavioral_defect: "behavioral_defect";
61
+ guidance_departure: "guidance_departure";
62
+ }>;
63
+ blocking: z.ZodNullable<z.ZodBoolean>;
64
+ }, z.core.$strict>>;
65
+ runner: z.ZodNullable<z.ZodObject<{
66
+ policy: z.ZodUnion<readonly [z.ZodObject<{
67
+ enforcement: z.ZodEnum<{
68
+ advisory: "advisory";
69
+ required: "required";
70
+ strict: "strict";
71
+ }>;
72
+ }, z.core.$strict>, z.ZodObject<{
73
+ minAdherence: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodNull]>;
74
+ minConfidence: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodNull]>;
75
+ advisory: z.ZodBoolean;
76
+ }, z.core.$strict>]>;
77
+ reviewExit: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
78
+ exitCode: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
79
+ }, z.core.$strict>>;
80
+ concernValidation: z.ZodOptional<z.ZodObject<{
81
+ scope: z.ZodLiteral<"nominated_concerns">;
82
+ expected: z.ZodNumber;
83
+ validated: z.ZodNumber;
84
+ complete: z.ZodBoolean;
85
+ }, z.core.$strict>>;
86
+ completion: z.ZodEnum<{
87
+ complete: "complete";
88
+ incomplete: "incomplete";
89
+ }>;
90
+ stopReason: z.ZodEnum<{
91
+ timeout: "timeout";
92
+ cancelled: "cancelled";
93
+ finished: "finished";
94
+ preparation_incomplete: "preparation_incomplete";
95
+ max_turns: "max_turns";
96
+ max_total_tokens: "max_total_tokens";
97
+ usage_unavailable: "usage_unavailable";
98
+ provider_error: "provider_error";
99
+ execution_error: "execution_error";
100
+ report_delivery_failed: "report_delivery_failed";
101
+ output_limit: "output_limit";
102
+ model_stopped: "model_stopped";
103
+ }>;
104
+ telemetry: z.ZodObject<{
105
+ durationMs: z.ZodNullable<z.ZodNumber>;
106
+ provider: z.ZodNullable<z.ZodString>;
107
+ model: z.ZodNullable<z.ZodString>;
108
+ harness: z.ZodNullable<z.ZodString>;
109
+ returned: z.ZodArray<z.ZodObject<{
110
+ provider: z.ZodNullable<z.ZodString>;
111
+ model: z.ZodNullable<z.ZodString>;
112
+ }, z.core.$strict>>;
113
+ calls: z.ZodNullable<z.ZodNumber>;
114
+ usage: z.ZodArray<z.ZodObject<{
115
+ call: z.ZodNumber;
116
+ inputTokens: z.ZodNullable<z.ZodNumber>;
117
+ outputTokens: z.ZodNullable<z.ZodNumber>;
118
+ totalTokens: z.ZodNullable<z.ZodNumber>;
119
+ cachedInputTokens: z.ZodNullable<z.ZodNumber>;
120
+ reasoningTokens: z.ZodNullable<z.ZodNumber>;
121
+ }, z.core.$strict>>;
122
+ }, z.core.$strict>;
123
+ }, z.core.$strict>;
124
+ export type ReviewReportInput = z.infer<typeof reviewReportInputSchema>;
125
+ /** Declared accounting only; never independent observation of the host review. */
126
+ export declare function isCompleteReviewCoverage(report: Pick<ReviewReportInput, 'scope' | 'outcomes'>): boolean;
127
+ export type ReviewReportReceipt = {
128
+ runId: string;
129
+ eventId: string;
130
+ receivedAt: string;
131
+ duplicate: boolean;
132
+ };
@@ -0,0 +1,240 @@
1
+ // Generated by scripts/sync-report-contract.mjs; edit v2-core/src/schemas/review-report.ts.
2
+ import { z } from 'zod';
3
+ // Metadata identifiers are grammar constrained, not bounded prose. This file is also
4
+ // copied by maintained tooling into the independently installable npm package.
5
+ const integer = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
6
+ const identifier = z
7
+ .string()
8
+ .min(1)
9
+ .max(160)
10
+ .regex(/^[A-Za-z0-9][A-Za-z0-9._/+:-]*$/u)
11
+ .refine((v) => !v.includes('://') &&
12
+ !v.includes('..') &&
13
+ !/^[A-Za-z]:[\\/]/u.test(v) &&
14
+ !/^(?:sk-|ghp_|github_pat_|AIza)/u.test(v));
15
+ const nodeId = (kind) => z
16
+ .string()
17
+ .max(400)
18
+ .regex(new RegExp(`^${kind}://[a-z0-9][a-z0-9_/-]*$`, 'u'));
19
+ const version = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
20
+ const context = z.strictObject({ nodeId: nodeId('context'), version: version.nullable() });
21
+ const entryId = z
22
+ .string()
23
+ .max(100)
24
+ .regex(/^[A-Za-z0-9][A-Za-z0-9_:-]*$/u);
25
+ const repository = z.discriminatedUnion('status', [
26
+ z.strictObject({
27
+ status: z.literal('unavailable'),
28
+ reason: z.enum([
29
+ 'withheld',
30
+ 'no_workspace',
31
+ 'not_git_repository',
32
+ 'no_remote',
33
+ 'ambiguous_remote',
34
+ 'not_determined',
35
+ ]),
36
+ }),
37
+ z.strictObject({
38
+ status: z.literal('reported'),
39
+ provider: z
40
+ .string()
41
+ .max(253)
42
+ .regex(/^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/u),
43
+ owner: z
44
+ .string()
45
+ .max(200)
46
+ .regex(/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9._-]+)*$/u)
47
+ .refine((v) => !v.split('/').some((s) => s === '.' || s === '..')),
48
+ name: z
49
+ .string()
50
+ .max(100)
51
+ .regex(/^[A-Za-z0-9_-][A-Za-z0-9._-]*$/u)
52
+ .refine((v) => !v.endsWith('.git')),
53
+ }),
54
+ ]);
55
+ export const reviewReportInputSchema = z
56
+ .strictObject({
57
+ kind: z.literal('review_report'),
58
+ contractVersion: z.literal(1),
59
+ runId: z.string().uuid(),
60
+ origin: z.enum(['npm', 'agent_skill']),
61
+ packageVersion: z
62
+ .string()
63
+ .max(64)
64
+ .regex(/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/u)
65
+ .nullable(),
66
+ methodVersion: identifier,
67
+ reviewer: z.strictObject({ nodeId: nodeId('skill'), version }),
68
+ repository,
69
+ scope: z.strictObject({
70
+ enumeration: z.enum(['complete', 'incomplete']),
71
+ expectedCount: integer.nullable(),
72
+ expected: z.array(z.strictObject({ entryId, context })).max(5000),
73
+ }),
74
+ outcomes: z
75
+ .array(z.strictObject({
76
+ entryId,
77
+ disposition: z.enum(['evaluated', 'observed', 'not_applicable', 'unresolved', 'not_evaluated']),
78
+ adherence: z.union([z.literal(0), z.literal(1), z.literal(2), z.null()]),
79
+ confidence: z.union([z.literal(1), z.literal(2), z.literal(3), z.null()]),
80
+ finding: z.enum(['none', 'binding_violation', 'behavioral_defect', 'guidance_departure']),
81
+ blocking: z.boolean().nullable(),
82
+ }))
83
+ .max(5000),
84
+ runner: z
85
+ .strictObject({
86
+ policy: z.union([
87
+ z.strictObject({ enforcement: z.enum(['advisory', 'required', 'strict']) }),
88
+ // Historical reports retain the policy and decision semantics used at the time.
89
+ z.strictObject({
90
+ minAdherence: z.union([z.literal(0), z.literal(1), z.literal(2), z.null()]),
91
+ minConfidence: z.union([z.literal(1), z.literal(2), z.literal(3), z.null()]),
92
+ advisory: z.boolean(),
93
+ }),
94
+ ]),
95
+ reviewExit: z.union([z.literal(0), z.literal(1), z.literal(2)]),
96
+ exitCode: z.union([z.literal(0), z.literal(1), z.literal(2)]),
97
+ })
98
+ .nullable(),
99
+ concernValidation: z
100
+ .strictObject({
101
+ scope: z.literal('nominated_concerns'),
102
+ expected: integer,
103
+ validated: integer,
104
+ complete: z.boolean(),
105
+ })
106
+ .optional(),
107
+ completion: z.enum(['complete', 'incomplete']),
108
+ stopReason: z.enum([
109
+ 'finished',
110
+ 'preparation_incomplete',
111
+ 'cancelled',
112
+ 'timeout',
113
+ 'max_turns',
114
+ 'max_total_tokens',
115
+ 'usage_unavailable',
116
+ 'provider_error',
117
+ 'execution_error',
118
+ 'report_delivery_failed',
119
+ 'output_limit',
120
+ 'model_stopped',
121
+ ]),
122
+ telemetry: z.strictObject({
123
+ durationMs: integer.nullable(),
124
+ provider: identifier.nullable(),
125
+ model: identifier.nullable(),
126
+ harness: identifier.nullable(),
127
+ returned: z
128
+ .array(z.strictObject({ provider: identifier.nullable(), model: identifier.nullable() }))
129
+ .max(10000),
130
+ calls: integer.nullable(),
131
+ usage: z
132
+ .array(z.strictObject({
133
+ call: integer.refine((v) => v > 0),
134
+ inputTokens: integer.nullable(),
135
+ outputTokens: integer.nullable(),
136
+ totalTokens: integer.nullable(),
137
+ cachedInputTokens: integer.nullable(),
138
+ reasoningTokens: integer.nullable(),
139
+ }))
140
+ .max(10000),
141
+ }),
142
+ })
143
+ .superRefine((v, ctx) => {
144
+ const issue = () => ctx.addIssue({ code: 'custom', message: 'Inconsistent structured review metadata.' });
145
+ const expected = v.scope.expected;
146
+ if (v.concernValidation &&
147
+ (v.concernValidation.validated > v.concernValidation.expected ||
148
+ v.concernValidation.complete !== (v.concernValidation.validated === v.concernValidation.expected)))
149
+ issue();
150
+ if (v.completion === 'complete' && v.concernValidation?.complete === false)
151
+ issue();
152
+ if (new Set(expected.map((e) => e.entryId)).size !== expected.length ||
153
+ new Set(expected.map((e) => `${e.context.nodeId}@${e.context.version}`)).size !== expected.length)
154
+ issue();
155
+ if (v.scope.expectedCount !== null && v.scope.expectedCount < expected.length)
156
+ issue();
157
+ if (v.scope.enumeration === 'complete' && (v.scope.expectedCount !== expected.length || !expected.length))
158
+ issue();
159
+ if (new Set(v.outcomes.map((e) => e.entryId)).size !== v.outcomes.length)
160
+ issue();
161
+ for (const o of v.outcomes) {
162
+ if (!expected.some((e) => e.entryId === o.entryId))
163
+ issue();
164
+ if (o.disposition === 'evaluated') {
165
+ if (o.adherence === null ||
166
+ (o.confidence === null && !v.concernValidation) ||
167
+ (o.finding === 'none') !== (o.adherence === 2))
168
+ issue();
169
+ }
170
+ else if (o.adherence !== null ||
171
+ (o.disposition !== 'unresolved' && o.finding !== 'none') ||
172
+ (o.disposition !== 'not_applicable' && o.confidence !== null))
173
+ issue();
174
+ if (v.origin === 'agent_skill' ? o.blocking !== null : typeof o.blocking !== 'boolean')
175
+ issue();
176
+ if (v.runner && o.blocking !== policyBlocksOutcome(v.runner.policy, o))
177
+ issue();
178
+ }
179
+ if (v.origin === 'npm' ? !v.runner || v.packageVersion === null : v.runner !== null || v.packageVersion !== null)
180
+ issue();
181
+ if (v.completion === 'complete' && (!isCompleteReviewCoverage(v) || v.stopReason !== 'finished'))
182
+ issue();
183
+ if (v.runner && 'enforcement' in v.runner.policy) {
184
+ if (!validEnforcementDecision(v))
185
+ issue();
186
+ }
187
+ else if (v.runner && 'advisory' in v.runner.policy) {
188
+ const policy = v.runner.policy;
189
+ const blocking = v.outcomes.some((o) => o.blocking);
190
+ const insufficient = v.outcomes.some((o) => policy.minConfidence !== null && (o.confidence === null || o.confidence < policy.minConfidence));
191
+ const reviewExit = blocking ? 1 : v.completion === 'incomplete' || insufficient ? 2 : 0;
192
+ if (v.completion === 'complete' && insufficient)
193
+ issue();
194
+ if (v.runner.reviewExit !== reviewExit ||
195
+ (v.runner.exitCode !== reviewExit && !(v.runner.exitCode === 2 && v.completion === 'incomplete')))
196
+ issue();
197
+ }
198
+ const usage = v.telemetry.usage;
199
+ if (new Set(usage.map((u) => u.call)).size !== usage.length ||
200
+ (v.telemetry.calls === null ? usage.length > 0 : usage.some((u) => u.call > v.telemetry.calls)))
201
+ issue();
202
+ })
203
+ .refine((v) => new TextEncoder().encode(JSON.stringify(v)).length <= 512 * 1024, 'Review metadata exceeds 512 KiB.');
204
+ /** Declared accounting only; never independent observation of the host review. */
205
+ export function isCompleteReviewCoverage(report) {
206
+ return (report.scope.enumeration === 'complete' &&
207
+ report.scope.expectedCount === report.scope.expected.length &&
208
+ report.scope.expected.every((e) => e.context.version !== null &&
209
+ report.outcomes.some((o) => o.entryId === e.entryId && ['evaluated', 'observed', 'not_applicable'].includes(o.disposition))));
210
+ }
211
+ function policyBlocksOutcome(policy, outcome) {
212
+ const supportedFinding = ['evaluated', 'unresolved'].includes(outcome.disposition) &&
213
+ ['binding_violation', 'behavioral_defect'].includes(outcome.finding);
214
+ if ('enforcement' in policy) {
215
+ return (policy.enforcement !== 'advisory' &&
216
+ (supportedFinding || (policy.enforcement === 'strict' && outcome.disposition === 'unresolved')));
217
+ }
218
+ if (policy.advisory)
219
+ return false;
220
+ if (outcome.disposition === 'unresolved')
221
+ return supportedFinding;
222
+ const assured = policy.minConfidence === null || (outcome.confidence !== null && outcome.confidence >= policy.minConfidence);
223
+ return (assured &&
224
+ outcome.disposition === 'evaluated' &&
225
+ (supportedFinding ||
226
+ (policy.minAdherence !== null && outcome.adherence !== null && outcome.adherence < policy.minAdherence)));
227
+ }
228
+ function validEnforcementDecision(report) {
229
+ const runner = report.runner;
230
+ if (!runner || !('enforcement' in runner.policy))
231
+ return false;
232
+ const blocking = report.outcomes.some((o) => o.blocking);
233
+ const strictGap = runner.policy.enforcement === 'strict' && report.completion === 'incomplete';
234
+ const executionFailed = report.stopReason !== 'finished' ||
235
+ report.scope.enumeration !== 'complete' ||
236
+ report.scope.expected.some((e) => e.context.version === null ||
237
+ !report.outcomes.some((o) => o.entryId === e.entryId && o.disposition !== 'not_evaluated'));
238
+ const reviewExit = blocking || (strictGap && !executionFailed) ? 1 : 0;
239
+ return runner.reviewExit === reviewExit && runner.exitCode === (executionFailed ? 2 : reviewExit);
240
+ }
@@ -0,0 +1,90 @@
1
+ import { z } from 'zod';
2
+ import { type Citation, type EvidenceLedger } from './evidence.js';
3
+ import type { PreparedState } from './prepare.js';
4
+ export declare const resultSchema: z.ZodObject<{
5
+ assessmentId: z.ZodString;
6
+ revisionOf: z.ZodNullable<z.ZodNumber>;
7
+ disposition: z.ZodEnum<{
8
+ evaluated: "evaluated";
9
+ observed: "observed";
10
+ not_applicable: "not_applicable";
11
+ unresolved: "unresolved";
12
+ }>;
13
+ adherence: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodNull]>;
14
+ confidence: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodNull]>;
15
+ confidenceReason: z.ZodString;
16
+ finding: z.ZodEnum<{
17
+ none: "none";
18
+ binding_violation: "binding_violation";
19
+ behavioral_defect: "behavioral_defect";
20
+ guidance_departure: "guidance_departure";
21
+ }>;
22
+ explanation: z.ZodString;
23
+ consequence: z.ZodString;
24
+ correction: z.ZodString;
25
+ limitations: z.ZodArray<z.ZodString>;
26
+ citations: z.ZodArray<z.ZodObject<{
27
+ ref: z.ZodString;
28
+ quote: z.ZodString;
29
+ start: z.ZodOptional<z.ZodNumber>;
30
+ end: z.ZodOptional<z.ZodNumber>;
31
+ }, z.core.$strict>>;
32
+ }, z.core.$strict>;
33
+ /** Models judge applicability and confidence; code derives aggregate outcomes from finding accounts. */
34
+ export declare function modelResultSchema(): z.ZodObject<{
35
+ assessmentId: z.ZodString;
36
+ disposition: z.ZodEnum<{
37
+ evaluated: "evaluated";
38
+ observed: "observed";
39
+ not_applicable: "not_applicable";
40
+ unresolved: "unresolved";
41
+ }>;
42
+ confidence: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodNull]>;
43
+ confidenceReason: z.ZodString;
44
+ explanation: z.ZodString;
45
+ limitations: z.ZodArray<z.ZodString>;
46
+ }, z.core.$strict>;
47
+ export type AcceptedResult = Omit<z.infer<typeof resultSchema>, 'citations'> & {
48
+ citations: Citation[];
49
+ revision: number;
50
+ };
51
+ type ResultSlot = PreparedState['entries'][number]['result'] | AcceptedResult;
52
+ export type AssessmentEntry = Omit<PreparedState['entries'][number], 'result'> & {
53
+ result: ResultSlot;
54
+ };
55
+ export declare const assessmentPolicySchema: z.ZodObject<{
56
+ enforcement: z.ZodEnum<{
57
+ advisory: "advisory";
58
+ required: "required";
59
+ strict: "strict";
60
+ }>;
61
+ }, z.core.$strict>;
62
+ export type AssessmentPolicy = z.infer<typeof assessmentPolicySchema>;
63
+ export declare const DEFAULT_POLICY: AssessmentPolicy;
64
+ export declare function validateResult(input: unknown, entries: AssessmentEntry[], ledger: EvidenceLedger, path?: Array<string | number>): AcceptedResult;
65
+ type PolicyFinding = {
66
+ verified: boolean;
67
+ classification: string;
68
+ assessmentIds: string[];
69
+ };
70
+ type PolicyReason = {
71
+ assessmentId: string | null;
72
+ gate: string;
73
+ blocking: boolean;
74
+ };
75
+ /** Judgment is unchanged; only deterministic automation policy is applied here. */
76
+ export declare function decideExit(entries: AssessmentEntry[], policy: AssessmentPolicy, incomplete?: boolean, executionFailure?: boolean, findings?: PolicyFinding[]): {
77
+ exitCode: number;
78
+ reviewExit: number;
79
+ complete: boolean;
80
+ counts: {
81
+ recorded: number;
82
+ evaluated: number;
83
+ observed: number;
84
+ unresolved: number;
85
+ notApplicable: number;
86
+ notEvaluated: number;
87
+ };
88
+ reasons: PolicyReason[];
89
+ };
90
+ export {};
@@ -0,0 +1,128 @@
1
+ import { z } from 'zod';
2
+ import { citationSchema } from './evidence.js';
3
+ export const resultSchema = z.strictObject({
4
+ assessmentId: z.string(),
5
+ revisionOf: z.number().int().positive().nullable(),
6
+ disposition: z.enum(['evaluated', 'observed', 'not_applicable', 'unresolved']),
7
+ adherence: z.union([z.literal(0), z.literal(1), z.literal(2), z.null()]),
8
+ confidence: z.union([z.literal(1), z.literal(2), z.literal(3), z.null()]),
9
+ confidenceReason: z.string().min(1),
10
+ finding: z.enum(['none', 'binding_violation', 'behavioral_defect', 'guidance_departure']),
11
+ explanation: z.string().min(1),
12
+ consequence: z.string(),
13
+ correction: z.string(),
14
+ limitations: z.array(z.string()),
15
+ citations: z.array(citationSchema),
16
+ });
17
+ /** Models judge applicability and confidence; code derives aggregate outcomes from finding accounts. */
18
+ export function modelResultSchema() {
19
+ return resultSchema.pick({
20
+ assessmentId: true,
21
+ disposition: true,
22
+ confidence: true,
23
+ confidenceReason: true,
24
+ explanation: true,
25
+ limitations: true,
26
+ });
27
+ }
28
+ export const assessmentPolicySchema = z.strictObject({ enforcement: z.enum(['advisory', 'required', 'strict']) });
29
+ export const DEFAULT_POLICY = { enforcement: 'advisory' };
30
+ function validateJudgment(value) {
31
+ if (value.disposition === 'evaluated') {
32
+ if (value.adherence === null)
33
+ throw new Error('Evaluated judgments require adherence with reasons. Missing decisive evidence must be unresolved; unavailable confidence remains null.');
34
+ if (value.finding !== 'none' && value.adherence === 2)
35
+ throw new Error('A supported unmet criterion needs adherence 0 or 1; satisfied permitted alternatives use 2 and finding none.');
36
+ if (value.adherence < 2 && value.finding === 'none')
37
+ throw new Error('Adherence below 2 requires a supported specific unmet criterion. Missing evidence is unresolved.');
38
+ }
39
+ else if (value.adherence !== null ||
40
+ (value.finding !== 'none' && value.disposition !== 'unresolved') ||
41
+ (['unresolved', 'observed'].includes(value.disposition) && value.confidence !== null))
42
+ throw new Error('Unresolved/nonapplicable judgments and observations have null adherence and no proven finding; unresolved confidence is null.');
43
+ }
44
+ export function validateResult(input, entries, ledger, path = []) {
45
+ const parsed = resultSchema.safeParse(input);
46
+ if (!parsed.success)
47
+ throw new Error(`Result shape invalid: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.code}`).join('; ')}. Correct these fields and resubmit this result.`);
48
+ const value = parsed.data;
49
+ const entry = entries.find((e) => e.assessmentId === value.assessmentId);
50
+ if (!entry)
51
+ throw new Error('Unknown assessmentId. Use the expected checklist identity.');
52
+ const currentRevision = 'revision' in entry.result ? entry.result.revision : null;
53
+ if (value.revisionOf !== currentRevision)
54
+ throw new Error(`Duplicate/stale update. To explicitly correct this entry, set revisionOf to ${currentRevision ?? 'null'}.`);
55
+ if (!entry.material)
56
+ throw new Error('Pinned publication unavailable; this entry cannot be assessed.');
57
+ validateJudgment(value);
58
+ const citations = value.citations.map((citation, index) => ledger.cite(citation, [...path, 'citations', index]));
59
+ if (!citations.some((c) => c.provenance.kind === 'publication' &&
60
+ c.provenance.nodeId === entry.nodeId &&
61
+ c.provenance.version === entry.version))
62
+ throw new Error('Cite an exact governing passage from this entry’s pinned publication.');
63
+ if ((value.disposition === 'evaluated' || value.finding !== 'none') &&
64
+ !citations.some((c) => c.provenance.kind === 'source'))
65
+ throw new Error('Evaluated judgments require concrete pinned source evidence from read_source. Navigation/search alone is not assessment evidence.');
66
+ if (value.finding !== 'none' && (!value.consequence.trim() || !value.correction.trim()))
67
+ throw new Error('Findings need a concrete consequence and proportionate correction.');
68
+ return { ...value, citations, revision: (currentRevision ?? 0) + 1 };
69
+ }
70
+ function resultGate(result) {
71
+ if (result.disposition === 'not_evaluated' || result.disposition === 'unresolved')
72
+ return { name: result.disposition, incomplete: true };
73
+ if (result.disposition === 'evaluated' &&
74
+ (result.finding === 'binding_violation' || result.finding === 'behavioral_defect'))
75
+ return { name: result.finding, incomplete: false };
76
+ return null;
77
+ }
78
+ function addFindingReasons(entries, findings, policy, reasons) {
79
+ for (const finding of findings) {
80
+ if (!finding.verified || !['binding_violation', 'behavioral_defect'].includes(finding.classification))
81
+ continue;
82
+ for (const id of finding.assessmentIds) {
83
+ if (!entries.some((entry) => entry.assessmentId === id) ||
84
+ reasons.some((reason) => reason.assessmentId === id && reason.gate === finding.classification))
85
+ continue;
86
+ reasons.push({
87
+ assessmentId: id,
88
+ gate: finding.classification,
89
+ blocking: policy.enforcement !== 'advisory',
90
+ });
91
+ }
92
+ }
93
+ }
94
+ function entryPolicyReasons(entries, policy) {
95
+ return entries.flatMap((entry) => {
96
+ const gate = resultGate(entry.result);
97
+ if (!gate)
98
+ return [];
99
+ const blocking = gate.name !== 'not_evaluated' &&
100
+ (gate.incomplete ? policy.enforcement === 'strict' : policy.enforcement !== 'advisory');
101
+ return [{ assessmentId: entry.assessmentId, gate: gate.name, blocking }];
102
+ });
103
+ }
104
+ /** Judgment is unchanged; only deterministic automation policy is applied here. */
105
+ export function decideExit(entries, policy, incomplete = false, executionFailure = false, findings = []) {
106
+ const reasons = entryPolicyReasons(entries, policy);
107
+ incomplete ||= reasons.some((reason) => ['unresolved', 'not_evaluated'].includes(reason.gate));
108
+ let blocker = reasons.some((reason) => reason.blocking);
109
+ addFindingReasons(entries, findings, policy, reasons);
110
+ blocker ||= reasons.some((reason) => reason.blocking);
111
+ const unavailable = executionFailure || !entries.length || entries.some((entry) => entry.result.disposition === 'not_evaluated');
112
+ if (incomplete && !unavailable && policy.enforcement === 'strict' && !reasons.some((reason) => reason.blocking)) {
113
+ reasons.push({ assessmentId: null, gate: 'incomplete_assessment', blocking: true });
114
+ blocker = true;
115
+ }
116
+ const reviewExit = blocker ? 1 : 0;
117
+ // An unavailable review remains an error even when judgments are advisory.
118
+ const exitCode = unavailable ? 2 : reviewExit;
119
+ const counts = {
120
+ recorded: entries.length,
121
+ evaluated: entries.filter((e) => e.result.disposition === 'evaluated').length,
122
+ observed: entries.filter((e) => e.result.disposition === 'observed').length,
123
+ unresolved: entries.filter((e) => e.result.disposition === 'unresolved').length,
124
+ notApplicable: entries.filter((e) => e.result.disposition === 'not_applicable').length,
125
+ notEvaluated: entries.filter((e) => e.result.disposition === 'not_evaluated').length,
126
+ };
127
+ return { exitCode, reviewExit, complete: !incomplete && !unavailable, counts, reasons };
128
+ }
@@ -0,0 +1,25 @@
1
+ import { type Evidence } from './evidence.js';
2
+ import { type GitIdentity, type PreparedState } from './prepare.js';
3
+ import type { AssessmentState } from './assess.js';
4
+ export type AssessmentCheckpoint = {
5
+ state: AssessmentState;
6
+ evidence: Record<string, Evidence>;
7
+ preparationManifest: Record<string, unknown>;
8
+ };
9
+ /** Resume only sealed incomplete runs. An interrupted unsealed write is not a trusted checkpoint. */
10
+ export declare function loadAssessmentCheckpoint(runDirectory: string, expected: {
11
+ artifact: GitIdentity;
12
+ reviewerId: string;
13
+ }): {
14
+ prepared: {
15
+ state: PreparedState;
16
+ statePath: string;
17
+ materialPath: string;
18
+ manifestPath: string;
19
+ };
20
+ checkpoint: {
21
+ state: AssessmentState;
22
+ evidence: Record<string, Evidence>;
23
+ preparationManifest: Record<string, unknown>;
24
+ };
25
+ };