@cat-factory/contracts 0.286.0 → 0.287.0

package/dist/public-spec.d.ts

@@ -43,6 +43,10 @@ export declare const PUBLIC_SPEC_MAX_ISSUES = 200;
  * than the one named. A null means the head could not be resolved at all: the tree below is still
  * what the branch held, we simply cannot name the commit.
  *
+ * Shared by both reads, which is why `ref` is the field a caller must actually look at rather than
+ * assume: WHICH branch each one answers is the distinction between them (see
+ * {@link publicRunSpecSchema}).
+ *
  * There is no `directory` here, and its absence is the fact: the `spec/` tree is anchored at the
  * REPOSITORY ROOT, so two services carved out of one monorepo share one spec. Naming a
  * subdirectory would imply a scoping the reader does not apply.
@@ -53,7 +57,13 @@ export declare const publicSpecProvenanceSchema: v.ObjectSchema<{
     readonly owner: v.StringSchema<undefined>;
     /** The repository's name. */
     readonly repo: v.StringSchema<undefined>;
-    /** The branch the spec was read from: the repository's default branch. */
+    /**
+     * The branch the spec was read from, named rather than implied because the two reads answer at
+     * different refs: the repository's default branch for a service read, and the branch the run
+     * pushed its work to for a run read. A run read names the default branch when the run opened no
+     * pull request, and when the one it opened has had its head branch deleted (the usual sequel to
+     * a merge), which is the same tree under its surviving name.
+     */
     readonly ref: v.StringSchema<undefined>;
     /** The head commit of `ref` at read time, or null when it could not be resolved. */
     readonly commit: v.NullableSchema<v.StringSchema<undefined>, undefined>;
@@ -201,7 +211,13 @@ export declare const publicServiceSpecSchema: v.ObjectSchema<{
         readonly owner: v.StringSchema<undefined>;
         /** The repository's name. */
         readonly repo: v.StringSchema<undefined>;
-        /** The branch the spec was read from: the repository's default branch. */
+        /**
+         * The branch the spec was read from, named rather than implied because the two reads answer at
+         * different refs: the repository's default branch for a service read, and the branch the run
+         * pushed its work to for a run read. A run read names the default branch when the run opened no
+         * pull request, and when the one it opened has had its head branch deleted (the usual sequel to
+         * a merge), which is the same tree under its surviving name.
+         */
         readonly ref: v.StringSchema<undefined>;
         /** The head commit of `ref` at read time, or null when it could not be resolved. */
         readonly commit: v.NullableSchema<v.StringSchema<undefined>, undefined>;
@@ -229,4 +245,138 @@ export declare const publicServiceSpecSchema: v.ObjectSchema<{
     }, undefined>, undefined>;
 }, undefined>;
 export type PublicServiceSpec = v.InferOutput<typeof publicServiceSpecSchema>;
+/**
+ * How the presence anchor resolved for a RUN's spec, for a caller that got a `200`.
+ *
+ * {@link publicSpecAnchorSchema} plus `not_read`, which is a fact about the RUN rather than about
+ * the repository and therefore cannot occur on the service-scoped read:
+ *
+ *  - `not_read` — nothing was read. The run's spec read is gated on a tester having reported, so
+ *    that the tree served is the one the verdicts were made against; before that point the
+ *    platform has consulted no tree, which is exactly what `requirements.spec: "not_read"` on the
+ *    same run's outcome summary already says. `provenance` is null, because there is no snapshot
+ *    to name.
+ *
+ * A separate picklist rather than a fourth member on the service one: `not_read` is unreachable
+ * there, and an enum carrying a value its endpoint can never answer is a state consumers write
+ * dead branches for.
+ */
+export declare const publicRunSpecAnchorSchema: v.PicklistSchema<["present", "absent", "unparsed", "not_read"], undefined>;
+export type PublicRunSpecAnchor = v.InferOutput<typeof publicRunSpecAnchorSchema>;
+/**
+ * The spec ONE RUN was judged against, as `/api/v1` serves it.
+ *
+ * The sibling of {@link publicServiceSpecSchema} rather than a flag on it, for the reason the
+ * internal pair already splits on: they answer different questions. The service read answers "what
+ * does this service require", from the repository's DEFAULT branch. This answers "what did this run
+ * rule on", from the branch the run pushed its work to, which is a different tree for as long as
+ * the pull request is open. A caller joining `requirements` rows on `/api/v1/runs/:runId/outcome`
+ * or `…/report` back to the criteria they were scored against needs THIS one: every requirement the
+ * run itself added is missing from the default branch, so the service read leaves each of those
+ * verdicts unjoinable.
+ *
+ * Same body as the service read (the tree, the Gherkin, the issues, the caps), because it is the
+ * same document read at a different ref, and two wire shapes over one artifact are two things to
+ * keep in step. What differs is the key (`runId`), the fourth {@link publicRunSpecAnchorSchema}
+ * state, and a nullable `provenance`.
+ */
+export declare const publicRunSpecSchema: v.ObjectSchema<{
+    /** The run this spec was read for, echoed so a response stands alone. */
+    readonly runId: v.StringSchema<undefined>;
+    /**
+     * What the RUN's branch holds where the spec should be, or `not_read` when the platform has
+     * consulted no tree for this run yet. `spec` is non-null exactly when this is `present`.
+     */
+    readonly anchor: v.PicklistSchema<["present", "absent", "unparsed", "not_read"], undefined>;
+    /** The structured tree, or null when `anchor` is not `present`. */
+    readonly spec: v.NullableSchema<v.ObjectSchema<{
+        readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+        readonly modules: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+            readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+            readonly groups: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+                readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+                readonly requirements: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+                    readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+                    readonly statement: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+                    readonly kind: v.PicklistSchema<["functional", "nonfunctional", "constraint"], undefined>;
+                    readonly priority: v.PicklistSchema<["must", "should", "could"], undefined>;
+                    readonly state: v.OptionalSchema<v.PicklistSchema<["aspirational", "established"], undefined>, "aspirational">;
+                    readonly sourceBlockIds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+                    readonly acceptance: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+                        readonly given: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                        readonly when: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                        readonly outcome: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                    }, undefined>, undefined>, readonly []>;
+                }, undefined>, undefined>, readonly []>;
+                readonly rules: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+                    readonly rule: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+                    readonly rationale: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+                    readonly sourceBlockIds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+                }, undefined>, undefined>, readonly []>;
+            }, undefined>, undefined>, readonly []>;
+        }, undefined>, undefined>, readonly []>;
+        readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 120, undefined>]>, "">;
+    }, undefined>, undefined>;
+    /** The rendered Gherkin, one entry per `.feature` file. */
+    readonly features: v.ArraySchema<v.ObjectSchema<{
+        /** The owning module's display name. */
+        readonly module: v.StringSchema<undefined>;
+        /** The feature/group display name. */
+        readonly group: v.StringSchema<undefined>;
+        /** Repo-relative path of the `.feature` file. */
+        readonly path: v.StringSchema<undefined>;
+        /** The Gherkin, clamped to {@link PUBLIC_SPEC_MAX_FEATURE_CHARS}. */
+        readonly content: v.StringSchema<undefined>;
+        /** Characters actually returned in `content`. */
+        readonly chars: v.NumberSchema<undefined>;
+        /** Characters the file holds in the repository, whatever was returned. */
+        readonly totalChars: v.NumberSchema<undefined>;
+        /** True when `chars < totalChars`. */
+        readonly truncated: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>;
+    /**
+     * Where the tree was read from: the RUN's branch (its pull request's head while one is open, the
+     * repository default otherwise) and the commit it was at.
+     *
+     * Null exactly when `anchor` is `not_read`, and that is the whole reason it is nullable: there is
+     * no snapshot to name, and naming the branch anyway would imply a read that did not happen.
+     */
+    readonly provenance: v.NullableSchema<v.ObjectSchema<{
+        readonly provider: v.PicklistSchema<["github", "gitlab"], undefined>;
+        /** The repository's owner (org or user). */
+        readonly owner: v.StringSchema<undefined>;
+        /** The repository's name. */
+        readonly repo: v.StringSchema<undefined>;
+        /**
+         * The branch the spec was read from, named rather than implied because the two reads answer at
+         * different refs: the repository's default branch for a service read, and the branch the run
+         * pushed its work to for a run read. A run read names the default branch when the run opened no
+         * pull request, and when the one it opened has had its head branch deleted (the usual sequel to
+         * a merge), which is the same tree under its surviving name.
+         */
+        readonly ref: v.StringSchema<undefined>;
+        /** The head commit of `ref` at read time, or null when it could not be resolved. */
+        readonly commit: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** Files the read could not fully account for. Capped at {@link PUBLIC_SPEC_MAX_ISSUES}. */
+    readonly issues: v.ArraySchema<v.ObjectSchema<{
+        readonly path: v.StringSchema<undefined>;
+        readonly kind: v.PicklistSchema<["read_failed", "unparsed", "partial", "unread"], undefined>;
+        readonly dropped: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, 0>;
+    }, undefined>, undefined>;
+    /** Every cap that bit. Empty when nothing was left out. */
+    readonly truncations: v.ArraySchema<v.ObjectSchema<{
+        readonly section: v.PicklistSchema<["requirements", "rules", "acceptance", "features", "issues"], undefined>;
+        /** How many rows the response carries. */
+        readonly shown: v.NumberSchema<undefined>;
+        /** How many rows the spec holds. */
+        readonly total: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type PublicRunSpec = v.InferOutput<typeof publicRunSpecSchema>;
 //# sourceMappingURL=public-spec.d.ts.map

package/dist/public-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-spec.d.ts","sourceRoot":"","sources":["../src/public-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA8C5B,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,OAAQ,CAAA;AAEjD,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,OAAQ,CAAA;AAE1C;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAA;AAE/C,4EAA4E;AAC5E,eAAO,MAAM,6BAA6B,MAAM,CAAA;AAEhD,uEAAuE;AACvE,eAAO,MAAM,6BAA6B,QAAS,CAAA;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,UAAY,CAAA;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B;;IAErC,4CAA4C;;IAE5C,6BAA6B;;IAE7B,0EAA0E;;IAE1E,oFAAoF;;aAEpF,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;IACtC,wCAAwC;;IAExC,sCAAsC;;IAEtC,iDAAiD;;IAEjD,qEAAqE;;IAErE,iDAAiD;;IAEjD,0EAA0E;;IAE1E,sCAAsC;;aAEtC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF,6FAA6F;AAC7F,eAAO,MAAM,iCAAiC,4FAM5C,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iCAAiC,CAAC,CAAA;AAEjG;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;IAErC,0CAA0C;;IAE1C,oCAAoC;;aAEpC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sBAAsB,gEAAgD,CAAA;AACnF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;IAClC,uFAAuF;;IAEvF;;;OAGG;;IAEH;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEH,6FAA6F;;QAzF7F,wCAAwC;;QAExC,sCAAsC;;QAEtC,iDAAiD;;QAEjD,qEAAqE;;QAErE,iDAAiD;;QAEjD,0EAA0E;;QAE1E,sCAAsC;;;;;QA/BtC,4CAA4C;;QAE5C,6BAA6B;;QAE7B,0EAA0E;;QAE1E,oFAAoF;;;IAyGpF;;;;;;;OAOG;;;;;;IAEH,2DAA2D;;;QAhE3D,0CAA0C;;QAE1C,oCAAoC;;;aAgEpC,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA"}
+{"version":3,"file":"public-spec.d.ts","sourceRoot":"","sources":["../src/public-spec.ts"],"names":[],"mappings":"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"}

package/dist/public-spec.js

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 import { vcsProviderSchema } from './routes/auth.js';
 import { readSpecDocSchema, specReadIssueSchema } from './spec.js';
 // ---------------------------------------------------------------------------
-// The public read of a service's in-repo SPECIFICATION (`GET /api/v1/services/:serviceId/spec`).
+// The public reads of the in-repo SPECIFICATION: a service's, from the repository's default branch
+// (`GET /api/v1/services/:serviceId/spec`), and a run's, from the branch that run pushed its work
+// to (`GET /api/v1/runs/:runId/spec`). Everything below describes the first; the second carries the
+// same body at a different ref, and {@link publicRunSpecSchema} states what it changes and why.
 //
 // The spec is the platform's requirements truth: structured requirement items with a MoSCoW
 // priority, an `aspirational ⇄ established` lifecycle state and Gherkin-shaped acceptance
@@ -86,6 +89,10 @@ export const PUBLIC_SPEC_MAX_ISSUES = 200;
  * than the one named. A null means the head could not be resolved at all: the tree below is still
  * what the branch held, we simply cannot name the commit.
  *
+ * Shared by both reads, which is why `ref` is the field a caller must actually look at rather than
+ * assume: WHICH branch each one answers is the distinction between them (see
+ * {@link publicRunSpecSchema}).
+ *
  * There is no `directory` here, and its absence is the fact: the `spec/` tree is anchored at the
  * REPOSITORY ROOT, so two services carved out of one monorepo share one spec. Naming a
  * subdirectory would imply a scoping the reader does not apply.
@@ -96,7 +103,13 @@ export const publicSpecProvenanceSchema = v.object({
     owner: v.string(),
     /** The repository's name. */
     repo: v.string(),
-    /** The branch the spec was read from: the repository's default branch. */
+    /**
+     * The branch the spec was read from, named rather than implied because the two reads answer at
+     * different refs: the repository's default branch for a service read, and the branch the run
+     * pushed its work to for a run read. A run read names the default branch when the run opened no
+     * pull request, and when the one it opened has had its head branch deleted (the usual sequel to
+     * a merge), which is the same tree under its surviving name.
+     */
     ref: v.string(),
     /** The head commit of `ref` at read time, or null when it could not be resolved. */
     commit: v.nullable(v.string()),
@@ -205,4 +218,63 @@ export const publicServiceSpecSchema = v.object({
     /** Every cap that bit. Empty when nothing was left out. */
     truncations: v.array(publicSpecTruncationSchema),
 });
+/**
+ * How the presence anchor resolved for a RUN's spec, for a caller that got a `200`.
+ *
+ * {@link publicSpecAnchorSchema} plus `not_read`, which is a fact about the RUN rather than about
+ * the repository and therefore cannot occur on the service-scoped read:
+ *
+ *  - `not_read` — nothing was read. The run's spec read is gated on a tester having reported, so
+ *    that the tree served is the one the verdicts were made against; before that point the
+ *    platform has consulted no tree, which is exactly what `requirements.spec: "not_read"` on the
+ *    same run's outcome summary already says. `provenance` is null, because there is no snapshot
+ *    to name.
+ *
+ * A separate picklist rather than a fourth member on the service one: `not_read` is unreachable
+ * there, and an enum carrying a value its endpoint can never answer is a state consumers write
+ * dead branches for.
+ */
+export const publicRunSpecAnchorSchema = v.picklist(['present', 'absent', 'unparsed', 'not_read']);
+/**
+ * The spec ONE RUN was judged against, as `/api/v1` serves it.
+ *
+ * The sibling of {@link publicServiceSpecSchema} rather than a flag on it, for the reason the
+ * internal pair already splits on: they answer different questions. The service read answers "what
+ * does this service require", from the repository's DEFAULT branch. This answers "what did this run
+ * rule on", from the branch the run pushed its work to, which is a different tree for as long as
+ * the pull request is open. A caller joining `requirements` rows on `/api/v1/runs/:runId/outcome`
+ * or `…/report` back to the criteria they were scored against needs THIS one: every requirement the
+ * run itself added is missing from the default branch, so the service read leaves each of those
+ * verdicts unjoinable.
+ *
+ * Same body as the service read (the tree, the Gherkin, the issues, the caps), because it is the
+ * same document read at a different ref, and two wire shapes over one artifact are two things to
+ * keep in step. What differs is the key (`runId`), the fourth {@link publicRunSpecAnchorSchema}
+ * state, and a nullable `provenance`.
+ */
+export const publicRunSpecSchema = v.object({
+    /** The run this spec was read for, echoed so a response stands alone. */
+    runId: v.string(),
+    /**
+     * What the RUN's branch holds where the spec should be, or `not_read` when the platform has
+     * consulted no tree for this run yet. `spec` is non-null exactly when this is `present`.
+     */
+    anchor: publicRunSpecAnchorSchema,
+    /** The structured tree, or null when `anchor` is not `present`. */
+    spec: v.nullable(readSpecDocSchema),
+    /** The rendered Gherkin, one entry per `.feature` file. */
+    features: v.array(publicSpecFeatureFileSchema),
+    /**
+     * Where the tree was read from: the RUN's branch (its pull request's head while one is open, the
+     * repository default otherwise) and the commit it was at.
+     *
+     * Null exactly when `anchor` is `not_read`, and that is the whole reason it is nullable: there is
+     * no snapshot to name, and naming the branch anyway would imply a read that did not happen.
+     */
+    provenance: v.nullable(publicSpecProvenanceSchema),
+    /** Files the read could not fully account for. Capped at {@link PUBLIC_SPEC_MAX_ISSUES}. */
+    issues: v.array(specReadIssueSchema),
+    /** Every cap that bit. Empty when nothing was left out. */
+    truncations: v.array(publicSpecTruncationSchema),
+});
 //# sourceMappingURL=public-spec.js.map

package/dist/public-spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-spec.js","sourceRoot":"","sources":["../src/public-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAElE,8EAA8E;AAC9E,iGAAiG;AACjG,EAAE;AACF,4FAA4F;AAC5F,0FAA0F;AAC1F,gGAAgG;AAChG,iGAAiG;AACjG,2FAA2F;AAC3F,0FAA0F;AAC1F,iGAAiG;AACjG,uFAAuF;AACvF,EAAE;AACF,kCAAkC;AAClC,EAAE;AACF,mGAAmG;AACnG,kGAAkG;AAClG,8FAA8F;AAC9F,gGAAgG;AAChG,6FAA6F;AAC7F,kGAAkG;AAClG,4CAA4C;AAC5C,oGAAoG;AACpG,iGAAiG;AACjG,kGAAkG;AAClG,gGAAgG;AAChG,kGAAkG;AAClG,8FAA8F;AAC9F,8FAA8F;AAC9F,eAAe;AACf,iGAAiG;AACjG,iGAAiG;AACjG,kGAAkG;AAClG,iGAAiG;AACjG,mGAAmG;AACnG,uEAAuE;AACvE,EAAE;AACF,gGAAgG;AAChG,oGAAoG;AACpG,iGAAiG;AACjG,oEAAoE;AACpE,8EAA8E;AAE9E,iFAAiF;AACjF,MAAM,CAAC,MAAM,4BAA4B,GAAG,KAAK,CAAA;AAEjD,iFAAiF;AACjF,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAA;AAE/C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAA;AAEhD,uEAAuE;AACvE,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAA;AAEnD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,SAAS,CAAA;AAE5D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,QAAQ,EAAE,iBAAiB;IAC3B,4CAA4C;IAC5C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,6BAA6B;IAC7B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,0EAA0E;IAC1E,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,oFAAoF;IACpF,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC/B,CAAC,CAAA;AAGF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,wCAAwC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,sCAAsC;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,iDAAiD;IACjD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,qEAAqE;IACrE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,iDAAiD;IACjD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,0EAA0E;IAC1E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,sCAAsC;IACtC,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;CACvB,CAAC,CAAA;AAGF,6FAA6F;AAC7F,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC1D,cAAc;IACd,OAAO;IACP,YAAY;IACZ,UAAU;IACV,QAAQ;CACT,CAAC,CAAA;AAGF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,OAAO,EAAE,iCAAiC;IAC1C,0CAA0C;IAC1C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,oCAAoC;IACpC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAA;AAGF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAA;AAGnF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,uFAAuF;IACvF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB;;;OAGG;IACH,MAAM,EAAE,sBAAsB;IAC9B;;;;;OAKG;IACH,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACnC,6FAA6F;IAC7F,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,2BAA2B,CAAC;IAC9C,UAAU,EAAE,0BAA0B;IACtC;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;IACpC,2DAA2D;IAC3D,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;CACjD,CAAC,CAAA"}
+{"version":3,"file":"public-spec.js","sourceRoot":"","sources":["../src/public-spec.ts"],"names":[],"mappings":"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"}

package/dist/routes/public-spec.d.ts

@@ -107,4 +107,114 @@ export declare const getPublicServiceSpecContract: {
 } & {
     readonly minScope: "read";
 };
+/**
+ * The specification ONE RUN was judged against, read from the branch that run pushed its work to.
+ *
+ * The sibling of {@link getPublicServiceSpecContract}, and the reason it is a sibling rather than a
+ * query parameter is the reason the internal pair already splits: they answer different questions,
+ * and a caller that asked the first while meaning the second got a document missing exactly the
+ * requirements the run had added. Every verdict naming one of those landed as unjoinable.
+ *
+ * `read` scope, and addressed under `/api/v1/runs/:runId/*` beside `…/report` and `…/outcome`, so
+ * the requirement ids on those two and the criteria they were scored against are three GETs on one
+ * key rather than a repository clone.
+ */
+export declare const getPublicRunSpecContract: {
+    readonly method: "get";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        runId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/core").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ runId }: {
+        runId: string;
+    }) => string;
+    readonly responsesByStatusCode: {
+        readonly '4xx': import("valibot").ObjectSchema<{
+            readonly error: import("valibot").ObjectSchema<{
+                readonly code: import("valibot").StringSchema<undefined>;
+                readonly message: import("valibot").StringSchema<undefined>;
+                readonly details: import("valibot").OptionalSchema<import("valibot").UnknownSchema, undefined>;
+                readonly issues: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                    readonly path: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+                    readonly message: import("valibot").StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+            }, undefined>;
+        }, undefined>;
+        readonly '5xx': import("valibot").ObjectSchema<{
+            readonly error: import("valibot").ObjectSchema<{
+                readonly code: import("valibot").StringSchema<undefined>;
+                readonly message: import("valibot").StringSchema<undefined>;
+                readonly details: import("valibot").OptionalSchema<import("valibot").UnknownSchema, undefined>;
+                readonly issues: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                    readonly path: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+                    readonly message: import("valibot").StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+            }, undefined>;
+        }, undefined>;
+        readonly 200: import("valibot").ObjectSchema<{
+            readonly runId: import("valibot").StringSchema<undefined>;
+            readonly anchor: import("valibot").PicklistSchema<["present", "absent", "unparsed", "not_read"], undefined>;
+            readonly spec: import("valibot").NullableSchema<import("valibot").ObjectSchema<{
+                readonly summary: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").MaxLengthAction<string, 2000, undefined>]>, "">;
+                readonly modules: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                    readonly name: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 120, undefined>]>;
+                    readonly summary: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").MaxLengthAction<string, 2000, undefined>]>, "">;
+                    readonly groups: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                        readonly name: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 120, undefined>]>;
+                        readonly summary: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").MaxLengthAction<string, 2000, undefined>]>, "">;
+                        readonly requirements: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                            readonly id: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 200, undefined>]>;
+                            readonly title: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 120, undefined>]>;
+                            readonly statement: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 4000, undefined>]>;
+                            readonly kind: import("valibot").PicklistSchema<["functional", "nonfunctional", "constraint"], undefined>;
+                            readonly priority: import("valibot").PicklistSchema<["must", "should", "could"], undefined>;
+                            readonly state: import("valibot").OptionalSchema<import("valibot").PicklistSchema<["aspirational", "established"], undefined>, "aspirational">;
+                            readonly sourceBlockIds: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+                            readonly acceptance: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                                readonly id: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 200, undefined>]>;
+                                readonly given: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").MaxLengthAction<string, 2000, undefined>]>;
+                                readonly when: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").MaxLengthAction<string, 2000, undefined>]>;
+                                readonly outcome: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").MaxLengthAction<string, 2000, undefined>]>;
+                            }, undefined>, undefined>, readonly []>;
+                        }, undefined>, undefined>, readonly []>;
+                        readonly rules: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                            readonly id: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 200, undefined>]>;
+                            readonly rule: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 4000, undefined>]>;
+                            readonly rationale: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").MaxLengthAction<string, 2000, undefined>]>, "">;
+                            readonly sourceBlockIds: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MinLengthAction<string, 1, undefined>, import("valibot").MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+                        }, undefined>, undefined>, readonly []>;
+                    }, undefined>, undefined>, readonly []>;
+                }, undefined>, undefined>, readonly []>;
+                readonly service: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").TrimAction, import("valibot").MaxLengthAction<string, 120, undefined>]>, "">;
+            }, undefined>, undefined>;
+            readonly features: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                readonly module: import("valibot").StringSchema<undefined>;
+                readonly group: import("valibot").StringSchema<undefined>;
+                readonly path: import("valibot").StringSchema<undefined>;
+                readonly content: import("valibot").StringSchema<undefined>;
+                readonly chars: import("valibot").NumberSchema<undefined>;
+                readonly totalChars: import("valibot").NumberSchema<undefined>;
+                readonly truncated: import("valibot").BooleanSchema<undefined>;
+            }, undefined>, undefined>;
+            readonly provenance: import("valibot").NullableSchema<import("valibot").ObjectSchema<{
+                readonly provider: import("valibot").PicklistSchema<["github", "gitlab"], undefined>;
+                readonly owner: import("valibot").StringSchema<undefined>;
+                readonly repo: import("valibot").StringSchema<undefined>;
+                readonly ref: import("valibot").StringSchema<undefined>;
+                readonly commit: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            }, undefined>, undefined>;
+            readonly issues: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                readonly path: import("valibot").StringSchema<undefined>;
+                readonly kind: import("valibot").PicklistSchema<["read_failed", "unparsed", "partial", "unread"], undefined>;
+                readonly dropped: import("valibot").OptionalSchema<import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>, 0>;
+            }, undefined>, undefined>;
+            readonly truncations: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                readonly section: import("valibot").PicklistSchema<["requirements", "rules", "acceptance", "features", "issues"], undefined>;
+                readonly shown: import("valibot").NumberSchema<undefined>;
+                readonly total: import("valibot").NumberSchema<undefined>;
+            }, undefined>, undefined>;
+        }, undefined>;
+    };
+} & {
+    readonly minScope: "read";
+};
 //# sourceMappingURL=public-spec.d.ts.map

package/dist/routes/public-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-spec.d.ts","sourceRoot":"","sources":["../../src/routes/public-spec.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQxC,CAAA"}
+{"version":3,"file":"public-spec.d.ts","sourceRoot":"","sources":["../../src/routes/public-spec.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQxC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQpC,CAAA"}

package/dist/routes/public-spec.js

@@ -1,15 +1,17 @@
 import { defineApiContract } from '@toad-contracts/valibot';
-import { publicServiceSpecSchema } from '../public-spec.js';
+import { publicRunSpecSchema, publicServiceSpecSchema } from '../public-spec.js';
 import { errorResponses, singleStringParam, withMinScope } from './_shared.js';
 // ---------------------------------------------------------------------------
-// The public SPEC read: absolute `/api/v1` path, authenticated in-controller by a public-API key.
-// The wire shape and the reasoning behind it live in `../public-spec.ts`; the honesty contract the
-// controller implements (four outcomes, never folded) is in `PublicSpecController`.
+// The public SPEC reads: absolute `/api/v1` paths, authenticated in-controller by a public-API key.
+// The wire shapes and the reasoning behind them live in `../public-spec.ts`; the honesty contract
+// the controller implements (the outcomes, never folded) is in `PublicSpecController`.
 //
-// Addressed under `/api/v1/services/:serviceId/*`, beside `…/tasks`, because a spec is a fact about
-// a SERVICE. The `serviceId` is the board service-frame id every other endpoint on this surface
-// already uses, and it resolves through the same board read, so a key can only ever name a service
-// of its own workspace.
+// Each is addressed under the resource the question is ABOUT, which is why there are two of them
+// rather than one with a `ref` parameter. The service read is a fact about a SERVICE and sits
+// beside `…/tasks`; the `serviceId` is the board service-frame id every other endpoint on this
+// surface already uses, and it resolves through the same board read, so a key can only ever name a
+// service of its own workspace. The run read is a fact about a RUN and sits beside `…/report` and
+// `…/outcome`, so criterion to evidence is three GETs on one key.
 // ---------------------------------------------------------------------------
 /**
  * The service's in-repo specification: the structured requirement tree, the rendered Gherkin, and
@@ -28,4 +30,22 @@ export const getPublicServiceSpecContract = withMinScope('read', defineApiContra
     pathResolver: ({ serviceId }) => `/api/v1/services/${serviceId}/spec`,
     responsesByStatusCode: { 200: publicServiceSpecSchema, ...errorResponses },
 }));
+/**
+ * The specification ONE RUN was judged against, read from the branch that run pushed its work to.
+ *
+ * The sibling of {@link getPublicServiceSpecContract}, and the reason it is a sibling rather than a
+ * query parameter is the reason the internal pair already splits: they answer different questions,
+ * and a caller that asked the first while meaning the second got a document missing exactly the
+ * requirements the run had added. Every verdict naming one of those landed as unjoinable.
+ *
+ * `read` scope, and addressed under `/api/v1/runs/:runId/*` beside `…/report` and `…/outcome`, so
+ * the requirement ids on those two and the criteria they were scored against are three GETs on one
+ * key rather than a repository clone.
+ */
+export const getPublicRunSpecContract = withMinScope('read', defineApiContract({
+    method: 'get',
+    requestPathParamsSchema: singleStringParam('runId'),
+    pathResolver: ({ runId }) => `/api/v1/runs/${runId}/spec`,
+    responsesByStatusCode: { 200: publicRunSpecSchema, ...errorResponses },
+}));
 //# sourceMappingURL=public-spec.js.map

package/dist/routes/public-spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-spec.js","sourceRoot":"","sources":["../../src/routes/public-spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE9E,8EAA8E;AAC9E,kGAAkG;AAClG,mGAAmG;AACnG,oFAAoF;AACpF,EAAE;AACF,oGAAoG;AACpG,gGAAgG;AAChG,mGAAmG;AACnG,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,YAAY,CACtD,MAAM,EACN,iBAAiB,CAAC;IAChB,MAAM,EAAE,KAAK;IACb,uBAAuB,EAAE,iBAAiB,CAAC,WAAW,CAAC;IACvD,YAAY,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,oBAAoB,SAAS,OAAO;IACrE,qBAAqB,EAAE,EAAE,GAAG,EAAE,uBAAuB,EAAE,GAAG,cAAc,EAAE;CAC3E,CAAC,CACH,CAAA"}
+{"version":3,"file":"public-spec.js","sourceRoot":"","sources":["../../src/routes/public-spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAChF,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE9E,8EAA8E;AAC9E,oGAAoG;AACpG,kGAAkG;AAClG,uFAAuF;AACvF,EAAE;AACF,iGAAiG;AACjG,8FAA8F;AAC9F,+FAA+F;AAC/F,mGAAmG;AACnG,kGAAkG;AAClG,kEAAkE;AAClE,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,YAAY,CACtD,MAAM,EACN,iBAAiB,CAAC;IAChB,MAAM,EAAE,KAAK;IACb,uBAAuB,EAAE,iBAAiB,CAAC,WAAW,CAAC;IACvD,YAAY,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,oBAAoB,SAAS,OAAO;IACrE,qBAAqB,EAAE,EAAE,GAAG,EAAE,uBAAuB,EAAE,GAAG,cAAc,EAAE;CAC3E,CAAC,CACH,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAClD,MAAM,EACN,iBAAiB,CAAC;IAChB,MAAM,EAAE,KAAK;IACb,uBAAuB,EAAE,iBAAiB,CAAC,OAAO,CAAC;IACnD,YAAY,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,gBAAgB,KAAK,OAAO;IACzD,qBAAqB,EAAE,EAAE,GAAG,EAAE,mBAAmB,EAAE,GAAG,cAAc,EAAE;CACvE,CAAC,CACH,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/contracts",
-  "version": "0.286.0",
+  "version": "0.287.0",
   "description": "Valibot wire contract shared between the Agent Architecture Board frontend and backend.",
   "repository": {
     "type": "git",