@fro.bot/systematic 3.33.2 → 3.34.0

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.
@@ -9,8 +9,12 @@ import { type ReadChunk } from './lib/review-return-validator.js';
9
9
  * beyond `screen`'s flag parsing and stdin plumbing.
10
10
  * - `return` -> the bounded raw persona-return validator (stdin).
11
11
  * - `artifact` -> the existing aggregate review-artifact validator.
12
- * - `screen` -> executable reviewer-return admission (`screenReviewReturn`),
13
- * reusing the same bounded stdin reader as `return`.
12
+ * - `screen` -> executable reviewer-return admission
13
+ * (`screenReviewReturnWithReport`), reusing the same bounded
14
+ * stdin reader as `return`. Exit 0 prints the screen result.
15
+ * Exit 1 prints `{ screen, rejection }` on stdout: the
16
+ * helper's own malformed screen result and a bounded,
17
+ * payload-safe rejection report.
14
18
  * - `prepare` -> executable candidate preparation (`prepareReviewCandidates`),
15
19
  * reusing the same bounded stdin reader with the larger
16
20
  * aggregate byte cap.
@@ -27,6 +27,9 @@ export interface ProjectedIssue {
27
27
  export interface ProjectableIssue {
28
28
  readonly path: readonly PropertyKey[];
29
29
  readonly code: string;
30
+ /** The schema's own accepted values on an `invalid_value` issue. Read only
31
+ * by {@link projectRejectionIssues}. */
32
+ readonly values?: readonly unknown[];
30
33
  }
31
34
  export interface ProjectedIssues {
32
35
  readonly issues: readonly ProjectedIssue[];
@@ -39,6 +42,24 @@ export interface ProjectedIssues {
39
42
  * unrecognized key name can reach the projection.
40
43
  */
41
44
  export declare function projectZodIssues(issues: readonly ProjectableIssue[], max?: number): ProjectedIssues;
45
+ /** A projected issue for a rejection report: the safe path and code, plus the
46
+ * schema's accepted values when the issue is a closed-set (enum) violation. */
47
+ export interface ProjectedRejectionIssue extends ProjectedIssue {
48
+ readonly allowed?: readonly string[];
49
+ }
50
+ export interface ProjectedRejectionIssues {
51
+ readonly issues: readonly ProjectedRejectionIssue[];
52
+ /** The full issue count, even when {@link ProjectedRejectionIssues.issues}
53
+ * is capped. */
54
+ readonly total: number;
55
+ }
56
+ /**
57
+ * {@link projectZodIssues} for a rejection report: the same capped
58
+ * `{path, code}` entries and full count, with the authored allowed values
59
+ * added to each enum issue. No issue message, payload value or unrecognized
60
+ * key name is read.
61
+ */
62
+ export declare function projectRejectionIssues(issues: readonly ProjectableIssue[], max?: number): ProjectedRejectionIssues;
42
63
  /** A payload-safe schema rejection: a fixed reason code, the first issue's
43
64
  * safe path, up to {@link MAX_PROJECTED_ISSUE_LINES} projected `{path, code}`
44
65
  * issues and the full issue count. Never a message, a value or an
@@ -1,5 +1,5 @@
1
1
  import type { z } from 'zod';
2
- import { type SchemaRejection } from './review-artifact-path.js';
2
+ import { type ProjectedRejectionIssue, type SchemaRejection } from './review-artifact-path.js';
3
3
  import type { HarnessSchema } from './review-artifact-schema.js';
4
4
  import { type AdjudicationEnvelopeSchema, type FinalizeInputSchema, FinalizeOutputSchema, MergeOutputSchema, type PipelineRoute, type PlanAssessmentEnvelopeSchema, PrepareOutputSchema, ScreenOutputSchema, type ValidatorLifecycleResultsSchema } from './review-pipeline-contract.js';
5
5
  /**
@@ -17,9 +17,8 @@ export declare function normalizeRepoRelativePath(filePath: string): string;
17
17
  * structure. Never reads `process.env`, the filesystem, or the clock --
18
18
  * admission depends only on the payload itself.
19
19
  *
20
- * Reuses `validateReviewReturnValue` from `review-return-validator.ts` for
21
- * the underlying `SubAgentReturnSchema` structural check rather than
22
- * re-validating shape by hand.
20
+ * The structural check is `SubAgentReturnSchema` itself, so `screen` and the
21
+ * sibling `return` validator accept and reject exactly the same payloads.
23
22
  */
24
23
  export type ScreenOutput = ReturnType<typeof ScreenOutputSchema.parse>;
25
24
  /** Raw screen input. `raw_return` is intentionally `unknown`: a reviewer's
@@ -30,17 +29,70 @@ export interface ScreenReviewReturnInput {
30
29
  readonly expected_reviewer: string;
31
30
  readonly invoking_harness: z.infer<typeof HarnessSchema>;
32
31
  }
32
+ /**
33
+ * Why `screen` rejected a return, as a fixed code. Every code but
34
+ * `schema_validation` names a failure that has no schema issue to point at.
35
+ */
36
+ export type ScreenRejectionCode = 'schema_validation' | 'malformed_json' | 'identity_mismatch' | 'input_oversized' | 'input_invalid_utf8';
37
+ /**
38
+ * A bounded, payload-safe account of a rejection, for the parent to quote back
39
+ * to the reviewer. A schema rejection reports the full issue count, up to
40
+ * eight `{path, code}` entries (an enum issue also lists the schema's accepted
41
+ * values), and how many entries were left out. Every other rejection is its
42
+ * fixed code and nothing else. No payload value, no unrecognized key name and
43
+ * no issue message ever reaches a report.
44
+ */
45
+ export type ScreenRejectionReport = {
46
+ readonly code: 'schema_validation';
47
+ readonly issue_count: number;
48
+ readonly issues: readonly ProjectedRejectionIssue[];
49
+ readonly omitted: number;
50
+ } | {
51
+ readonly code: Exclude<ScreenRejectionCode, 'schema_validation'>;
52
+ };
53
+ /** The admission result plus, on a rejection, the report that explains it. */
54
+ export type ScreenAdmission = {
55
+ readonly ok: true;
56
+ readonly result: ScreenOutput;
57
+ } | {
58
+ readonly ok: false;
59
+ readonly result: ScreenOutput;
60
+ readonly rejection: ScreenRejectionReport;
61
+ };
33
62
  /**
34
63
  * Admit one reviewer's raw return and bind it to the parent-expected
35
- * persona.
64
+ * persona, reporting why when it is rejected.
36
65
  *
37
66
  * Rejection is whole-payload only: a schema-invalid return, a reviewer
38
67
  * identity mismatch, or malformed JSON rejects everything. Findings that
39
68
  * pass structural validation are admitted with a stable
40
69
  * `<reviewer>#<original-index>` input ID derived from their position in the
41
70
  * original payload.
71
+ *
72
+ * The rejected `ScreenOutput` is the one `prepare` consumes. It carries a
73
+ * `rejected_summary` row only when the rejected findings can be counted.
74
+ */
75
+ export declare function screenReviewReturnWithReport(input: ScreenReviewReturnInput): ScreenAdmission;
76
+ /**
77
+ * Admit one reviewer's raw return and bind it to the parent-expected
78
+ * persona. See {@link screenReviewReturnWithReport}; this returns the
79
+ * `ScreenOutput` alone.
42
80
  */
43
81
  export declare function screenReviewReturn(input: ScreenReviewReturnInput): ScreenOutput;
82
+ /** Input to {@link rejectUnreadableScreenInput}. */
83
+ export interface RejectUnreadableScreenInput {
84
+ readonly code: Extract<ScreenRejectionCode, 'input_oversized' | 'input_invalid_utf8'>;
85
+ readonly expected_reviewer: string;
86
+ readonly invoking_harness: z.infer<typeof HarnessSchema>;
87
+ }
88
+ /**
89
+ * The rejection for stdin that never reached `screenReviewReturn` as text:
90
+ * over the byte limit or not valid UTF-8. Nothing was parsed, so the finding
91
+ * count is unknowable and the result carries no `rejected_summary` row.
92
+ */
93
+ export declare function rejectUnreadableScreenInput(input: RejectUnreadableScreenInput): Extract<ScreenAdmission, {
94
+ readonly ok: false;
95
+ }>;
44
96
  export type PrepareOutput = ReturnType<typeof PrepareOutputSchema.parse>;
45
97
  /** Raw prepare input. `raw_input` is intentionally `unknown`: the aggregate
46
98
  * payload may arrive as an unparsed JSON string (a raw stdin payload) or as
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.33.2",
3
+ "version": "3.34.0",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -118,7 +118,7 @@
118
118
  }
119
119
  },
120
120
  "devDependencies": {
121
- "@biomejs/biome": "2.6.6",
121
+ "@biomejs/biome": "2.6.7",
122
122
  "@earendil-works/pi-coding-agent": "1.5.2",
123
123
  "@opencode-ai/plugin": "1.19.5",
124
124
  "@opencode-ai/sdk": "1.19.5",
@@ -138,7 +138,7 @@
138
138
  "rimraf": "6.1.4",
139
139
  "semantic-release": "25.0.9",
140
140
  "semantic-release-export-data": "1.2.0",
141
- "typebox": "1.4.6",
141
+ "typebox": "1.4.7",
142
142
  "typescript": "7.0.2"
143
143
  },
144
144
  "dependencies": {