@vibe-agent-toolkit/agent-skills 0.2.0-rc.2 → 0.2.0-rc.3

package/dist/skill-test/grading-adapter.js

@@ -1,3 +1,4 @@
+import { sanitizeGraderText } from './grader-text.js';
 import { GradingReportSchema } from './grading-schema.js';
 /**
  * Thrown when grading.json does not match the canonical skill-creator shape
@@ -29,6 +30,27 @@ export class GradingNonceError extends Error {
         this.name = 'GradingNonceError';
     }
 }
+/**
+ * Thrown when a per-eval grader fragment's `arm` disagrees with the arm the
+ * merge was told it is assembling. Deliberately distinct from
+ * {@link GradingNonceError}: a fragment can carry a perfectly valid nonce for
+ * THIS run and still belong to the other arm, and that is a different failure —
+ * not a forgery, but a mix-up that would fold a control-arm verdict into the
+ * treatment number (or the reverse). Either way the merged total is no longer a
+ * measurement of one arm, which is the entire premise of the `--baseline` A/B,
+ * so the merge refuses rather than emit a mislabelled artifact that downstream
+ * readers would take as authoritative.
+ */
+export class GradingArmError extends Error {
+    constructor(message) {
+        super(`grader fragment arm mismatch: ${message}. Each --baseline arm is merged into its own ` +
+            'artifact (grading.json = the WITH arm, baseline.json = the WITHOUT/control arm), and ' +
+            'every fragment merged into one must come from that arm — a fragment with no `arm` ' +
+            "belongs to the default 'with' arm. Mixing arms would make the merged pass count a " +
+            'measurement of neither.');
+        this.name = 'GradingArmError';
+    }
+}
 /**
  * Detect the common per-eval nested mistake: `{ evals: [ { expectations, ... } ] }`
  * with no top-level `expectations`. The grader (an LLM) reaches for this when the
@@ -48,19 +70,44 @@ export function parseGradingJson(raw) {
                 'grading.json must be ONE flat object whose top-level `expectations` lists every ' +
                 'graded expectation across all evals');
         }
+        // Both halves are attacker-reachable and land in an operator-facing message: a
+        // `.strict()` rejection puts the grader-CHOSEN KEY inside zod's own issue message,
+        // and `path` is built from that same key. Sanitize both — this is the route that
+        // has already been found twice in sibling modules, and it must not reopen here just
+        // because today's only callers are tests.
         const firstIssue = result.error.issues[0];
-        const path = firstIssue?.path.join('.') ?? '(root)';
-        throw new GradingSkewError(`missing/invalid field at "${path}" (${firstIssue?.message ?? 'unknown'})`);
+        const path = sanitizeGraderText(firstIssue?.path.join('.') ?? '(root)');
+        const detail = sanitizeGraderText(firstIssue?.message ?? 'unknown');
+        throw new GradingSkewError(`missing/invalid field at "${path}" (${detail})`);
     }
-    const { summary, expectations, runNonce } = result.data;
+    const { summary, expectations, runNonce, arm } = result.data;
+    // Pass `evalId`/`arm` through WHEN PRESENT. The docblocks on NormalizedGrading
+    // explain why they are optional — an externally produced grading.json legitimately
+    // carries no attribution, and inventing one would be a lie about provenance. That
+    // argues for omitting an ABSENT field, not for discarding a present one: the schema
+    // already parses both, so dropping them silently narrowed the declared type and
+    // threw away exactly the key a reader needs to line the two --baseline artifacts
+    // up per eval.
+    //
+    // 📌 STATE OF PLAY, so nobody mistakes this for load-bearing code: NOTHING IN
+    // SHIPPED CODE READS THESE TWO TODAY. `parseGradingJson` itself is reachable only
+    // from the package barrel and this module's own test file — the harness builds its
+    // NormalizedGrading from per-eval fragments, not by re-parsing an aggregate
+    // grading.json — so the two spreads are written-but-never-read outside tests. They
+    // stay anyway, because the cost of keeping a parsed field is zero and the cost of
+    // reopening the discard is a reader who cannot attribute an expectation to an eval
+    // or an arm. Treat "no production caller" as a reason to leave this alone, not as
+    // permission to delete it.
     return {
         summary: { passed: summary.passed, total: summary.total },
         expectations: expectations.map(e => ({
             text: e.text,
             passed: e.passed,
             ...(e.evidence === undefined ? {} : { evidence: e.evidence }),
+            ...(e.evalId === undefined ? {} : { evalId: e.evalId }),
         })),
         ...(runNonce === undefined ? {} : { runNonce }),
+        ...(arm === undefined ? {} : { arm }),
     };
 }
 /**

package/dist/skill-test/grading-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"grading-adapter.js","sourceRoot":"","sources":["../../src/skill-test/grading-adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grading-adapter.js","sourceRoot":"","sources":["../../src/skill-test/grading-adapter.ts"],"names":[],"mappings":"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"}

package/dist/skill-test/grading-schema.d.ts

@@ -31,20 +31,51 @@ export declare const GradedExpectationSchema: z.ZodObject<{
     text: z.ZodString;
     passed: z.ZodBoolean;
     evidence: z.ZodOptional<z.ZodString>;
+    /**
+     * Which eval this expectation was graded under. vat stamps it when it
+     * assembles the aggregate from per-eval grader fragments, so that a
+     * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+     * in aggregate — without it, a reader can compare two totals but cannot say
+     * which eval moved. Optional because a grading.json produced by external
+     * tooling (skill-creator's own) carries no per-eval attribution; the schema
+     * documents the field vat now emits rather than tightening the contract.
+     */
+    evalId: z.ZodOptional<z.ZodString>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     text: z.ZodString;
     passed: z.ZodBoolean;
     evidence: z.ZodOptional<z.ZodString>;
+    /**
+     * Which eval this expectation was graded under. vat stamps it when it
+     * assembles the aggregate from per-eval grader fragments, so that a
+     * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+     * in aggregate — without it, a reader can compare two totals but cannot say
+     * which eval moved. Optional because a grading.json produced by external
+     * tooling (skill-creator's own) carries no per-eval attribution; the schema
+     * documents the field vat now emits rather than tightening the contract.
+     */
+    evalId: z.ZodOptional<z.ZodString>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     text: z.ZodString;
     passed: z.ZodBoolean;
     evidence: z.ZodOptional<z.ZodString>;
+    /**
+     * Which eval this expectation was graded under. vat stamps it when it
+     * assembles the aggregate from per-eval grader fragments, so that a
+     * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+     * in aggregate — without it, a reader can compare two totals but cannot say
+     * which eval moved. Optional because a grading.json produced by external
+     * tooling (skill-creator's own) carries no per-eval attribution; the schema
+     * documents the field vat now emits rather than tightening the contract.
+     */
+    evalId: z.ZodOptional<z.ZodString>;
 }, z.ZodTypeAny, "passthrough">>;
 export type GradedExpectation = z.infer<typeof GradedExpectationSchema>;
 /**
  * Aggregate pass/fail counts. `failed`/`pass_rate` are documented but optional.
  * Counts are non-negative integers (a float or negative count is a grader bug),
- * and `passed` can never exceed `total`.
+ * and `passed` can never exceed `total` — see {@link SUMMARY_SCHEMA_DESCRIPTION}
+ * for why that last one has to be stated twice.
  */
 export declare const GradingSummarySchema: z.ZodEffects<z.ZodObject<{
     passed: z.ZodNumber;
@@ -83,14 +114,44 @@ export declare const GradingReportSchema: z.ZodObject<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
     summary: z.ZodEffects<z.ZodObject<{
         passed: z.ZodNumber;
@@ -127,19 +188,58 @@ export declare const GradingReportSchema: z.ZodObject<{
      * by untrusted skill code is rejected.
      */
     runNonce: z.ZodOptional<z.ZodString>;
+    /**
+     * Which `--baseline` arm produced this report: `'with'` (the skill declared)
+     * or `'without'` (the control arm run with the skill withheld). vat writes
+     * the two arms to two files of the SAME shape — `grading.json` and
+     * `baseline.json` — so without this field a reader holding one of them
+     * cannot tell which arm it is looking at. Optional for the same reason
+     * `runNonce` is: an externally produced grading.json has no arm to declare.
+     */
+    arm: z.ZodOptional<z.ZodEnum<["with", "without"]>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     expectations: z.ZodArray<z.ZodObject<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
     summary: z.ZodEffects<z.ZodObject<{
         passed: z.ZodNumber;
@@ -176,19 +276,58 @@ export declare const GradingReportSchema: z.ZodObject<{
      * by untrusted skill code is rejected.
      */
     runNonce: z.ZodOptional<z.ZodString>;
+    /**
+     * Which `--baseline` arm produced this report: `'with'` (the skill declared)
+     * or `'without'` (the control arm run with the skill withheld). vat writes
+     * the two arms to two files of the SAME shape — `grading.json` and
+     * `baseline.json` — so without this field a reader holding one of them
+     * cannot tell which arm it is looking at. Optional for the same reason
+     * `runNonce` is: an externally produced grading.json has no arm to declare.
+     */
+    arm: z.ZodOptional<z.ZodEnum<["with", "without"]>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     expectations: z.ZodArray<z.ZodObject<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         text: z.ZodString;
         passed: z.ZodBoolean;
         evidence: z.ZodOptional<z.ZodString>;
+        /**
+         * Which eval this expectation was graded under. vat stamps it when it
+         * assembles the aggregate from per-eval grader fragments, so that a
+         * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+         * in aggregate — without it, a reader can compare two totals but cannot say
+         * which eval moved. Optional because a grading.json produced by external
+         * tooling (skill-creator's own) carries no per-eval attribution; the schema
+         * documents the field vat now emits rather than tightening the contract.
+         */
+        evalId: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
     summary: z.ZodEffects<z.ZodObject<{
         passed: z.ZodNumber;
@@ -225,13 +364,29 @@ export declare const GradingReportSchema: z.ZodObject<{
      * by untrusted skill code is rejected.
      */
     runNonce: z.ZodOptional<z.ZodString>;
+    /**
+     * Which `--baseline` arm produced this report: `'with'` (the skill declared)
+     * or `'without'` (the control arm run with the skill withheld). vat writes
+     * the two arms to two files of the SAME shape — `grading.json` and
+     * `baseline.json` — so without this field a reader holding one of them
+     * cannot tell which arm it is looking at. Optional for the same reason
+     * `runNonce` is: an externally produced grading.json has no arm to declare.
+     */
+    arm: z.ZodOptional<z.ZodEnum<["with", "without"]>>;
 }, z.ZodTypeAny, "passthrough">>;
 export type GradingReport = z.infer<typeof GradingReportSchema>;
 /**
- * Published JSON Schema for grading.json — generated from {@link GradingReportSchema}
- * so the two never drift. Importable by external tooling that wants to validate a
- * grading.json without depending on Zod. Documented in
- * docs/skill-test-grading-schema.md.
+ * Published JSON Schema for grading.json — generated from {@link GradingReportSchema},
+ * so its SHAPE (fields, types, required-ness, additionalProperties) cannot drift from
+ * the Zod schema. Importable by external tooling that wants to validate a grading.json
+ * without depending on Zod. Documented in docs/skill-test-grading-schema.md.
+ *
+ * It is NOT equivalent to the Zod schema, and never can be. `zodToJsonSchema` drops
+ * every `.refine()`, and the two refinements in this file are cross-field relations
+ * JSON Schema has no way to express — so the generated document is strictly weaker
+ * than the validator that generated it. That gap is stated, in the document itself,
+ * on the field it applies to (see {@link SUMMARY_SCHEMA_DESCRIPTION}); a consumer
+ * that needs the invariant enforced must re-implement it or use the Zod schema.
  */
 export declare const GradingReportJsonSchema: import("zod-to-json-schema").JsonSchema7Type & {
     $schema?: string | undefined;

package/dist/skill-test/grading-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grading-schema.d.ts","sourceRoot":"","sources":["../../src/skill-test/grading-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,sFAAsF;AACtF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;gCAMpB,CAAC;AAEjB,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;gCAU7B,CAAC;AAEL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAI5B;;;;;;;OAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAPH;;;;;;;OAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAPH;;;;;;;OAOG;;gCAGS,CAAC;AAEjB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;CAAyD,CAAC"}
+{"version":3,"file":"grading-schema.d.ts","sourceRoot":"","sources":["../../src/skill-test/grading-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,sFAAsF;AACtF,eAAO,MAAM,uBAAuB;;;;IAKhC;;;;;;;;OAQG;;;;;;IARH;;;;;;;;OAQG;;;;;;IARH;;;;;;;;OAQG;;gCAGS,CAAC;AAEjB,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAiCxE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;gCAcM,CAAC;AAExC,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;QA3E5B;;;;;;;;WAQG;;;;;;QARH;;;;;;;;WAQG;;;;;;QARH;;;;;;;;WAQG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuEH;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;;;;;;QA/FH;;;;;;;;WAQG;;;;;;QARH;;;;;;;;WAQG;;;;;;QARH;;;;;;;;WAQG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuEH;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;;;;;;QA/FH;;;;;;;;WAQG;;;;;;QARH;;;;;;;;WAQG;;;;;;QARH;;;;;;;;WAQG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuEH;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;gCAGS,CAAC;AAEjB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB;;;;;CAAyD,CAAC"}

package/dist/skill-test/grading-schema.js

@@ -33,12 +33,51 @@ export const GradedExpectationSchema = z
     text: z.string(),
     passed: z.boolean(),
     evidence: z.string().optional(),
+    /**
+     * Which eval this expectation was graded under. vat stamps it when it
+     * assembles the aggregate from per-eval grader fragments, so that a
+     * `--baseline` run's two artifacts can be lined up PER EVAL rather than only
+     * in aggregate — without it, a reader can compare two totals but cannot say
+     * which eval moved. Optional because a grading.json produced by external
+     * tooling (skill-creator's own) carries no per-eval attribution; the schema
+     * documents the field vat now emits rather than tightening the contract.
+     */
+    evalId: z.string().optional(),
 })
     .passthrough();
+/**
+ * The cross-field invariant, worded once and carried into BOTH surfaces that can
+ * state it: the Zod refine's failure message, and the `description` on `summary`
+ * in the published JSON Schema.
+ *
+ * It has to be carried explicitly because `zodToJsonSchema` DISCARDS `.refine()`.
+ * Without this, the published document said `{passed: integer≥0, total: integer≥0}`
+ * and nothing else — so external tooling validating against it accepted
+ * `{passed: 9, total: 3}`, the exact shape the Zod validator rejects and the exact
+ * shape that produced a confident `delta: -8`. The invariant was not enforced OR
+ * mentioned, which is worse than unenforced: a consumer reading the schema had no
+ * way to learn the check existed.
+ *
+ * JSON Schema cannot close the gap. No draft can compare one property against
+ * another (`maximum` takes a number, not a pointer; `if`/`then` can only test a
+ * value, not a relation), and the Ajv `$data` extension that could is not portable
+ * — a plain Ajv without `$data: true` FAILS TO COMPILE a schema containing it,
+ * which would break every conforming consumer to serve one. So the published
+ * schema records the constraint and says plainly that it is on the consumer to
+ * check, rather than pretending to enforce it.
+ */
+const SUMMARY_INVARIANT_MESSAGE = 'summary.passed must not exceed summary.total';
+const SUMMARY_SCHEMA_DESCRIPTION = 'Aggregate pass/fail counts. INVARIANT: ' +
+    `${SUMMARY_INVARIANT_MESSAGE}. It is enforced by the Zod schema this document is generated from ` +
+    'and by vat when it merges grader fragments, but NOT by this document: JSON Schema cannot express ' +
+    'a comparison between two properties in any draft, so a validator running this schema alone will ' +
+    'accept {"passed": 9, "total": 3}. Check it yourself before trusting any figure derived from these ' +
+    'counts (a baseline delta subtracts them).';
 /**
  * Aggregate pass/fail counts. `failed`/`pass_rate` are documented but optional.
  * Counts are non-negative integers (a float or negative count is a grader bug),
- * and `passed` can never exceed `total`.
+ * and `passed` can never exceed `total` — see {@link SUMMARY_SCHEMA_DESCRIPTION}
+ * for why that last one has to be stated twice.
  */
 export const GradingSummarySchema = z
     .object({
@@ -49,8 +88,12 @@ export const GradingSummarySchema = z
 })
     .passthrough()
     .refine(s => s.passed <= s.total, {
-    message: 'summary.passed must not exceed summary.total',
-});
+    message: SUMMARY_INVARIANT_MESSAGE,
+})
+    // `.describe()` AFTER `.refine()`: zodToJsonSchema reads the description off the
+    // outermost node, and this is the only channel through which a Zod refinement's
+    // meaning can reach the emitted document at all.
+    .describe(SUMMARY_SCHEMA_DESCRIPTION);
 /**
  * The full grading.json contract. Required: top-level `expectations[]` and
  * `summary`. Everything else passes through untouched (forward-compatible with
@@ -69,13 +112,29 @@ export const GradingReportSchema = z
      * by untrusted skill code is rejected.
      */
     runNonce: z.string().optional(),
+    /**
+     * Which `--baseline` arm produced this report: `'with'` (the skill declared)
+     * or `'without'` (the control arm run with the skill withheld). vat writes
+     * the two arms to two files of the SAME shape — `grading.json` and
+     * `baseline.json` — so without this field a reader holding one of them
+     * cannot tell which arm it is looking at. Optional for the same reason
+     * `runNonce` is: an externally produced grading.json has no arm to declare.
+     */
+    arm: z.enum(['with', 'without']).optional(),
 })
     .passthrough();
 /**
- * Published JSON Schema for grading.json — generated from {@link GradingReportSchema}
- * so the two never drift. Importable by external tooling that wants to validate a
- * grading.json without depending on Zod. Documented in
- * docs/skill-test-grading-schema.md.
+ * Published JSON Schema for grading.json — generated from {@link GradingReportSchema},
+ * so its SHAPE (fields, types, required-ness, additionalProperties) cannot drift from
+ * the Zod schema. Importable by external tooling that wants to validate a grading.json
+ * without depending on Zod. Documented in docs/skill-test-grading-schema.md.
+ *
+ * It is NOT equivalent to the Zod schema, and never can be. `zodToJsonSchema` drops
+ * every `.refine()`, and the two refinements in this file are cross-field relations
+ * JSON Schema has no way to express — so the generated document is strictly weaker
+ * than the validator that generated it. That gap is stated, in the document itself,
+ * on the field it applies to (see {@link SUMMARY_SCHEMA_DESCRIPTION}); a consumer
+ * that needs the invariant enforced must re-implement it or use the Zod schema.
  */
 export const GradingReportJsonSchema = zodToJsonSchema(GradingReportSchema, 'grading-report');
 //# sourceMappingURL=grading-schema.js.map

package/dist/skill-test/grading-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"grading-schema.js","sourceRoot":"","sources":["../../src/skill-test/grading-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC;KACD,WAAW,EAAE,CAAC;AAIjB;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACrC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACjD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC;KACD,WAAW,EAAE;KACb,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,EAAE;IAChC,OAAO,EAAE,8CAA8C;CACxD,CAAC,CAAC;AAIL;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;IAC9C,OAAO,EAAE,oBAAoB;IAC7B;;;;;;;OAOG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC;KACD,WAAW,EAAE,CAAC;AAIjB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"grading-schema.js","sourceRoot":"","sources":["../../src/skill-test/grading-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC;KACD,WAAW,EAAE,CAAC;AAIjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,yBAAyB,GAAG,8CAA8C,CAAC;AAEjF,MAAM,0BAA0B,GAC9B,yCAAyC;IACzC,GAAG,yBAAyB,qEAAqE;IACjG,mGAAmG;IACnG,kGAAkG;IAClG,oGAAoG;IACpG,2CAA2C,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACrC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACjD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC;KACD,WAAW,EAAE;KACb,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,EAAE;IAChC,OAAO,EAAE,yBAAyB;CACnC,CAAC;IACF,iFAAiF;IACjF,gFAAgF;IAChF,iDAAiD;KAChD,QAAQ,CAAC,0BAA0B,CAAC,CAAC;AAIxC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;IAC9C,OAAO,EAAE,oBAAoB;IAC7B;;;;;;;OAOG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B;;;;;;;OAOG;IACH,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC5C,CAAC;KACD,WAAW,EAAE,CAAC;AAIjB;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAAC"}

package/dist/skill-test/index.d.ts

@@ -4,7 +4,7 @@ export { lintEvalExpectations, lintToolExpectationExecutables, type EvalLintWarn
 export { FrictionCategorySchema, FrictionItemSchema, FrictionReportJsonSchema, FrictionReportSchema, FrictionSeveritySchema, type FrictionItem, type FrictionReport, } from './friction-schema.js';
 export { mergeFragmentsToFriction, mergeFragmentsToGrading, mergeFragmentsToToolEval, } from './fragment-merge.js';
 export { ToolEvalReportJsonSchema, ToolEvalReportSchema, ToolVerdictBodySchema, ToolVerdictSchema, type ToolEvalReport, type ToolVerdict, type ToolVerdictBody, } from './tool-eval-schema.js';
-export { GradingNonceError, GradingSkewError, parseGradingJson, reconcileGrading, type GradingVerdict, type NormalizedGrading, } from './grading-adapter.js';
+export { GradingArmError, GradingNonceError, GradingSkewError, parseGradingJson, reconcileGrading, type GradingVerdict, type NormalizedGrading, } from './grading-adapter.js';
 export { GradedExpectationSchema, GradingReportJsonSchema, GradingReportSchema, GradingSummarySchema, type GradedExpectation, type GradingReport, type GradingSummary, } from './grading-schema.js';
 export { assertSafeHarnessRoot, assertSafeWorkdir, deriveHarnessKey, HarnessLocationError, resolveHarnessRoot, } from './harness-location.js';
 export { computeReconcilePlan, StagedEntrySchema, StagedManifestSchema, type ReconcilePlan, type StagedEntry, type StagedManifest, } from './manifest.js';

package/dist/skill-test/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skill-test/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skill-test/index.ts"],"names":[],"mappings":"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"}

package/dist/skill-test/index.js

@@ -4,7 +4,7 @@ export { lintEvalExpectations, lintToolExpectationExecutables } from './eval-lin
 export { FrictionCategorySchema, FrictionItemSchema, FrictionReportJsonSchema, FrictionReportSchema, FrictionSeveritySchema, } from './friction-schema.js';
 export { mergeFragmentsToFriction, mergeFragmentsToGrading, mergeFragmentsToToolEval, } from './fragment-merge.js';
 export { ToolEvalReportJsonSchema, ToolEvalReportSchema, ToolVerdictBodySchema, ToolVerdictSchema, } from './tool-eval-schema.js';
-export { GradingNonceError, GradingSkewError, parseGradingJson, reconcileGrading, } from './grading-adapter.js';
+export { GradingArmError, GradingNonceError, GradingSkewError, parseGradingJson, reconcileGrading, } from './grading-adapter.js';
 export { GradedExpectationSchema, GradingReportJsonSchema, GradingReportSchema, GradingSummarySchema, } from './grading-schema.js';
 export { assertSafeHarnessRoot, assertSafeWorkdir, deriveHarnessKey, HarnessLocationError, resolveHarnessRoot, } from './harness-location.js';
 export { computeReconcilePlan, StagedEntrySchema, StagedManifestSchema, } from './manifest.js';

package/dist/skill-test/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skill-test/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,EACd,mBAAmB,GAIpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,6BAA6B,EAC7B,kBAAkB,EAClB,iBAAiB,GAGlB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,8BAA8B,EAAwB,MAAM,gBAAgB,CAAC;AAC5G,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,GAGvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,GAIlB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GAGjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,GAIrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,GAIrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,GAKrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,WAAW,EAA2B,MAAM,eAAe,CAAC;AACtF,OAAO,EACL,YAAY,GAIb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,GAEjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,8BAA8B,EAC9B,mBAAmB,GAEpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,GAElB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,6BAA6B,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAoB,MAAM,WAAW,CAAC;AACvF,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,YAAY,GAIb,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,GAEjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAClH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,EACpB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,GAIhB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skill-test/index.ts"],"names":[],"mappings":"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"}

package/dist/skill-test/lock.d.ts

@@ -1,7 +1,35 @@
+/**
+ * The harness root for a subject set is already locked.
+ *
+ * Exit 2 (PREFLIGHT), not 1. This is the most user-correctable condition in the
+ * command — the remedy is "wait, or delete one file" — and it was the ONE error
+ * class in this feature with no `exitCode`, so it fell through
+ * `mapErrorToExitCode`'s default to Internal (1). The published CI recipe reads 1
+ * as "the harness broke, fail the build", which is exactly the wrong verdict for a
+ * lock held by the operator's own second terminal.
+ *
+ * The field below is what `mapErrorToExitCode` READS — it is not decoration
+ * mirroring an `instanceof` row, which is what it was when it was added. Deleting it
+ * turns this back into an exit 1.
+ *
+ * The message names `lockPath` because the lockfile is created `O_EXCL` in the
+ * DETERMINISTIC harness root and released only on normal exit or SIGINT/SIGTERM —
+ * a SIGKILL, an OOM, or a crash leaves it behind and every later run of that skill
+ * fails here, with no `--force` to escape. Until the staleness protocol (pid +
+ * timestamp + liveness probe + `--force`) lands in its own lane, naming the path
+ * and saying to delete it IS the escape hatch, so it belongs in the message rather
+ * than in a doc the operator is not currently reading.
+ */
 export declare class HarnessLockBusyError extends Error {
+    readonly lockPath: string;
+    readonly exitCode: 2;
     constructor(lockPath: string);
 }
 export interface HarnessLock {
+    /**
+     * Release the lock. NEVER THROWS — see {@link acquireHarnessLock}. Callers run
+     * this from a cleanup path and must be able to call it bare.
+     */
     release(): void;
 }
 /**
@@ -9,6 +37,34 @@ export interface HarnessLock {
  * vat-vs-vat staging/result races for the same subject set. `wait: false`
  * fails fast; the default `wait: true` is reserved for the CLI to poll (v1
  * keeps the simple fail-fast — the CLI surfaces the busy message).
+ *
+ * ACQUIRING can throw (that is the whole point: EEXIST → {@link HarnessLockBusyError}).
+ * RELEASING cannot, and that asymmetry is deliberate. `rmSync(..., {force: true})`
+ * swallows only ENOENT, so an EPERM/EACCES/EROFS on the lockfile — a read-only
+ * volume, a `root`-owned temp dir, a Windows handle still open — threw out of the
+ * harness `finally` and REPLACED an already-good result (verdict computed, artifacts
+ * written, summary composed) with exit 1 and no summary, every artifact sitting
+ * unread on disk.
+ *
+ * The guard lives HERE rather than at the call site, where it originally went. A
+ * call-site wrapper is invisible to the compiler: reverting it to a bare
+ * `lock.release()` left the whole unit suite AND the integration suite green, so
+ * nothing but review stood between the fix and its own silent removal. Owning the
+ * contract in the definition — `release()` never throws — means there is no unwrapped
+ * call site left to lose. Note what that does NOT mean: `release(): void` encodes
+ * nothing about throwing, because TypeScript has no throws clause. The contract is
+ * held up by the two nested `try`s below and by the tests that pin each one, not by
+ * the signature.
+ *
+ * BOTH statements of the catch are guarded, and the second one is why: the warning
+ * write is itself an fd-level operation, and a synchronous EBADF/EPIPE on a file- or
+ * TTY-backed fd 2 threw straight back out — reinstating the exact failure the outer
+ * catch was added to prevent, on a path only reachable once something had already
+ * gone wrong. A test that mocks `process.stderr.write` to RETURN cannot see it.
+ *
+ * The failure is not silent: a lockfile that could not be removed will fail the NEXT
+ * run of this skill with a "busy" error, and an operator who saw nothing here has no
+ * way to connect the two.
  */
 export declare function acquireHarnessLock(harnessRoot: string, opts?: {
     wait?: boolean;

package/dist/skill-test/lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/skill-test/lock.ts"],"names":[],"mappings":"AAIA,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM;CAI7B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,CAwBlG;AAWD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,MAAM,IAAI,CAgBlF"}
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/skill-test/lock.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAEjB,QAAQ,EAAE,MAAM;IAD5C,QAAQ,CAAC,QAAQ,EAAG,CAAC,CAAU;gBACH,QAAQ,EAAE,MAAM;CAS7C;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,CAyClG;AAWD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,MAAM,IAAI,CAgBlF"}