@cat-factory/contracts 0.278.0 → 0.280.0

package/dist/routes/public-merge-evidence.d.ts

@@ -0,0 +1,248 @@
+/**
+ * The merge decision a RUN left behind: its change class, the merger's scores, what happened,
+ * and the effort tag if one has been recorded.
+ *
+ * The entry point of the loop for a caller that started the run and holds its id, and the read
+ * that hands it the `recordId` the tag route takes. A run whose pipeline had no `merger` step
+ * (or whose merge path never got far enough to classify) has no record, and that is a `404`
+ * rather than an empty object: "this run made no merge decision" is a fact about the run.
+ */
+export declare const getPublicRunMergeRecordContract: {
+    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 recordId: import("valibot").StringSchema<undefined>;
+            readonly taskId: import("valibot").StringSchema<undefined>;
+            readonly runId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly changeClass: import("valibot").PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>;
+            readonly changedFileCount: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly complexity: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly risk: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly impact: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly mergePresetId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly mergePresetName: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly decision: import("valibot").PicklistSchema<["pending_review", "auto_merged", "human_merged", "external_merged", "rejected"], undefined>;
+            readonly reviewEffort: import("valibot").NullableSchema<import("valibot").PicklistSchema<["none", "minor", "major"], undefined>, undefined>;
+            readonly prNumber: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly prUrl: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly repoId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly provider: import("valibot").NullableSchema<import("valibot").PicklistSchema<["github", "gitlab"], undefined>, undefined>;
+            readonly createdAt: import("valibot").NumberSchema<undefined>;
+            readonly resolvedAt: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly taggedAt: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+        }, undefined>;
+    };
+} & {
+    readonly minScope: "read";
+};
+/**
+ * Every change class's accumulated track record for the key's workspace, as ONE aggregate.
+ *
+ * Registered ahead of the point read below so `rollups` cannot be taken for a record id. It
+ * cannot be one today (record ids are `mtr_*`), but the ordering is what keeps that true of a
+ * future id scheme rather than of this one.
+ */
+export declare const listPublicMergeClassRollupsContract: {
+    readonly method: "get";
+    readonly pathResolver: () => 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 rollups: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                readonly changeClass: import("valibot").PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>;
+                readonly total: import("valibot").NumberSchema<undefined>;
+                readonly merged: import("valibot").NumberSchema<undefined>;
+                readonly autoMerged: import("valibot").NumberSchema<undefined>;
+                readonly humanMerged: import("valibot").NumberSchema<undefined>;
+                readonly externalMerged: import("valibot").NumberSchema<undefined>;
+                readonly rejected: import("valibot").NumberSchema<undefined>;
+                readonly pendingReview: import("valibot").NumberSchema<undefined>;
+                readonly effort: import("valibot").ObjectSchema<{
+                    readonly none: import("valibot").NumberSchema<undefined>;
+                    readonly minor: import("valibot").NumberSchema<undefined>;
+                    readonly major: import("valibot").NumberSchema<undefined>;
+                    readonly untagged: import("valibot").NumberSchema<undefined>;
+                }, undefined>;
+            }, undefined>, undefined>;
+        }, undefined>;
+    };
+} & {
+    readonly minScope: "read";
+};
+/**
+ * One record by id: the read-back beside the tag write, so a caller holding a `recordId` (from
+ * a `merge_tag_request` card's payload, say) can see WHAT it is about to tag rather than tagging
+ * an opaque id.
+ */
+export declare const getPublicMergeRecordContract: {
+    readonly method: "get";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        recordId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/core").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ recordId }: {
+        recordId: 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 recordId: import("valibot").StringSchema<undefined>;
+            readonly taskId: import("valibot").StringSchema<undefined>;
+            readonly runId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly changeClass: import("valibot").PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>;
+            readonly changedFileCount: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly complexity: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly risk: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly impact: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly mergePresetId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly mergePresetName: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly decision: import("valibot").PicklistSchema<["pending_review", "auto_merged", "human_merged", "external_merged", "rejected"], undefined>;
+            readonly reviewEffort: import("valibot").NullableSchema<import("valibot").PicklistSchema<["none", "minor", "major"], undefined>, undefined>;
+            readonly prNumber: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly prUrl: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly repoId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly provider: import("valibot").NullableSchema<import("valibot").PicklistSchema<["github", "gitlab"], undefined>, undefined>;
+            readonly createdAt: import("valibot").NumberSchema<undefined>;
+            readonly resolvedAt: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly taggedAt: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+        }, undefined>;
+    };
+} & {
+    readonly minScope: "read";
+};
+/**
+ * Tag (or clear, with `null`) the reviewer effort a human spent on the pull request a record
+ * covers. `write`, not `admin`: this records evidence about a decision that already happened.
+ *
+ * Idempotent (the same tag applied twice leaves the same row) and orthogonal to the decision, so
+ * a record may be tagged whenever the effort becomes known, including long after the merge.
+ */
+export declare const tagPublicMergeReviewEffortContract: {
+    readonly method: "post";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        recordId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/core").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ recordId }: {
+        recordId: string;
+    }) => string;
+    readonly requestBodySchema: import("valibot").ObjectSchema<{
+        readonly reviewEffort: import("valibot").NullableSchema<import("valibot").PicklistSchema<["none", "minor", "major"], undefined>, undefined>;
+    }, undefined>;
+    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 recordId: import("valibot").StringSchema<undefined>;
+            readonly taskId: import("valibot").StringSchema<undefined>;
+            readonly runId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly changeClass: import("valibot").PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>;
+            readonly changedFileCount: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly complexity: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly risk: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly impact: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly mergePresetId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly mergePresetName: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly decision: import("valibot").PicklistSchema<["pending_review", "auto_merged", "human_merged", "external_merged", "rejected"], undefined>;
+            readonly reviewEffort: import("valibot").NullableSchema<import("valibot").PicklistSchema<["none", "minor", "major"], undefined>, undefined>;
+            readonly prNumber: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly prUrl: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly repoId: import("valibot").NullableSchema<import("valibot").StringSchema<undefined>, undefined>;
+            readonly provider: import("valibot").NullableSchema<import("valibot").PicklistSchema<["github", "gitlab"], undefined>, undefined>;
+            readonly createdAt: import("valibot").NumberSchema<undefined>;
+            readonly resolvedAt: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+            readonly taggedAt: import("valibot").NullableSchema<import("valibot").NumberSchema<undefined>, undefined>;
+        }, undefined>;
+    };
+} & {
+    readonly minScope: "write";
+};
+//# sourceMappingURL=public-merge-evidence.d.ts.map

package/dist/routes/public-merge-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-merge-evidence.d.ts","sourceRoot":"","sources":["../../src/routes/public-merge-evidence.ts"],"names":[],"mappings":"AAiCA;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQ3C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAO/C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQxC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAS9C,CAAA"}

package/dist/routes/public-merge-evidence.js

@@ -0,0 +1,80 @@
+import { defineApiContract } from '@toad-contracts/valibot';
+import { tagReviewEffortSchema } from '../mergeTrackRecord.js';
+import { publicMergeClassRollupListSchema, publicMergeRecordSchema, } from '../public-merge-evidence.js';
+import { errorResponses, singleStringParam, withMinScope } from './_shared.js';
+// ---------------------------------------------------------------------------
+// Route contracts for the public MERGE-EVIDENCE surface: absolute `/api/v1` paths,
+// authenticated in-controller by a public-API key. The wire shapes and the reasoning behind
+// them live in `../public-merge-evidence.ts`; the feature itself is
+// `backend/docs/adr/0046-merge-track-record.md`.
+//
+// The scope split is the whole point of the surface, and it is deliberately NOT the one `act`
+// carries. `POST /api/v1/notifications/:id/act` is `admin` because it MERGES a pull request for
+// real; TAGGING how much review an already-landed pull request needed performs no external
+// side-effect and cannot merge anything, so it is `write`, and the reads are `read` like every
+// other read on this API. An integration that watches a board and records review effort
+// therefore needs neither merge rights nor the ability to delete a task, where before the only
+// way to record a tag at all was through the `admin`-scoped `act`.
+//
+// The two workspace-scoped point routes are addressed by RECORD id and re-apply the key's
+// workspace to the row they load, which is the rule every point read on this API follows
+// (`/api/v1/debug/llm-calls/:callId`, `/api/v1/artifacts/:artifactId/blob`). The run-scoped read
+// is under `/api/v1/runs/:runId/*` and therefore carries that prefix's ONE access semantic
+// instead: a run this key could already reach through `GET /jobs/:id` or
+// `GET /tasks/:taskId/run`. See `PublicEvidenceController` for why a prefix may carry only one.
+// ---------------------------------------------------------------------------
+const runIdParams = singleStringParam('runId');
+const recordIdParams = singleStringParam('recordId');
+/**
+ * The merge decision a RUN left behind: its change class, the merger's scores, what happened,
+ * and the effort tag if one has been recorded.
+ *
+ * The entry point of the loop for a caller that started the run and holds its id, and the read
+ * that hands it the `recordId` the tag route takes. A run whose pipeline had no `merger` step
+ * (or whose merge path never got far enough to classify) has no record, and that is a `404`
+ * rather than an empty object: "this run made no merge decision" is a fact about the run.
+ */
+export const getPublicRunMergeRecordContract = withMinScope('read', defineApiContract({
+    method: 'get',
+    requestPathParamsSchema: runIdParams,
+    pathResolver: ({ runId }) => `/api/v1/runs/${runId}/merge-record`,
+    responsesByStatusCode: { 200: publicMergeRecordSchema, ...errorResponses },
+}));
+/**
+ * Every change class's accumulated track record for the key's workspace, as ONE aggregate.
+ *
+ * Registered ahead of the point read below so `rollups` cannot be taken for a record id. It
+ * cannot be one today (record ids are `mtr_*`), but the ordering is what keeps that true of a
+ * future id scheme rather than of this one.
+ */
+export const listPublicMergeClassRollupsContract = withMinScope('read', defineApiContract({
+    method: 'get',
+    pathResolver: () => '/api/v1/merge-records/rollups',
+    responsesByStatusCode: { 200: publicMergeClassRollupListSchema, ...errorResponses },
+}));
+/**
+ * One record by id: the read-back beside the tag write, so a caller holding a `recordId` (from
+ * a `merge_tag_request` card's payload, say) can see WHAT it is about to tag rather than tagging
+ * an opaque id.
+ */
+export const getPublicMergeRecordContract = withMinScope('read', defineApiContract({
+    method: 'get',
+    requestPathParamsSchema: recordIdParams,
+    pathResolver: ({ recordId }) => `/api/v1/merge-records/${recordId}`,
+    responsesByStatusCode: { 200: publicMergeRecordSchema, ...errorResponses },
+}));
+/**
+ * Tag (or clear, with `null`) the reviewer effort a human spent on the pull request a record
+ * covers. `write`, not `admin`: this records evidence about a decision that already happened.
+ *
+ * Idempotent (the same tag applied twice leaves the same row) and orthogonal to the decision, so
+ * a record may be tagged whenever the effort becomes known, including long after the merge.
+ */
+export const tagPublicMergeReviewEffortContract = withMinScope('write', defineApiContract({
+    method: 'post',
+    requestPathParamsSchema: recordIdParams,
+    pathResolver: ({ recordId }) => `/api/v1/merge-records/${recordId}/effort`,
+    requestBodySchema: tagReviewEffortSchema,
+    responsesByStatusCode: { 200: publicMergeRecordSchema, ...errorResponses },
+}));
+//# sourceMappingURL=public-merge-evidence.js.map

package/dist/routes/public-merge-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-merge-evidence.js","sourceRoot":"","sources":["../../src/routes/public-merge-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EACL,gCAAgC,EAChC,uBAAuB,GACxB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE9E,8EAA8E;AAC9E,mFAAmF;AACnF,4FAA4F;AAC5F,oEAAoE;AACpE,iDAAiD;AACjD,EAAE;AACF,8FAA8F;AAC9F,gGAAgG;AAChG,2FAA2F;AAC3F,+FAA+F;AAC/F,wFAAwF;AACxF,+FAA+F;AAC/F,mEAAmE;AACnE,EAAE;AACF,0FAA0F;AAC1F,yFAAyF;AACzF,iGAAiG;AACjG,2FAA2F;AAC3F,yEAAyE;AACzE,gGAAgG;AAChG,8EAA8E;AAE9E,MAAM,WAAW,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAA;AAC9C,MAAM,cAAc,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAA;AAEpD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,YAAY,CACzD,MAAM,EACN,iBAAiB,CAAC;IAChB,MAAM,EAAE,KAAK;IACb,uBAAuB,EAAE,WAAW;IACpC,YAAY,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,gBAAgB,KAAK,eAAe;IACjE,qBAAqB,EAAE,EAAE,GAAG,EAAE,uBAAuB,EAAE,GAAG,cAAc,EAAE;CAC3E,CAAC,CACH,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,YAAY,CAC7D,MAAM,EACN,iBAAiB,CAAC;IAChB,MAAM,EAAE,KAAK;IACb,YAAY,EAAE,GAAG,EAAE,CAAC,+BAA+B;IACnD,qBAAqB,EAAE,EAAE,GAAG,EAAE,gCAAgC,EAAE,GAAG,cAAc,EAAE;CACpF,CAAC,CACH,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,YAAY,CACtD,MAAM,EACN,iBAAiB,CAAC;IAChB,MAAM,EAAE,KAAK;IACb,uBAAuB,EAAE,cAAc;IACvC,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,yBAAyB,QAAQ,EAAE;IACnE,qBAAqB,EAAE,EAAE,GAAG,EAAE,uBAAuB,EAAE,GAAG,cAAc,EAAE;CAC3E,CAAC,CACH,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,YAAY,CAC5D,OAAO,EACP,iBAAiB,CAAC;IAChB,MAAM,EAAE,MAAM;IACd,uBAAuB,EAAE,cAAc;IACvC,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,yBAAyB,QAAQ,SAAS;IAC1E,iBAAiB,EAAE,qBAAqB;IACxC,qBAAqB,EAAE,EAAE,GAAG,EAAE,uBAAuB,EAAE,GAAG,cAAc,EAAE;CAC3E,CAAC,CACH,CAAA"}

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

@@ -0,0 +1,110 @@
+/**
+ * The service's in-repo specification: the structured requirement tree, the rendered Gherkin, and
+ * the ref + commit both were read at.
+ *
+ * `read` scope, like every other discovery and evidence read here. It is a read of what the
+ * service is committed to honouring, and an integration reviewing a run's outcome must be able to
+ * see the criteria it was scored against without holding a key that could also merge a pull
+ * request.
+ *
+ * Read-only by design, not by omission: see the note at the top of `../public-spec.ts`.
+ */
+export declare const getPublicServiceSpecContract: {
+    readonly method: "get";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        serviceId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/core").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ serviceId }: {
+        serviceId: 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 serviceId: import("valibot").StringSchema<undefined>;
+            readonly anchor: import("valibot").PicklistSchema<["present", "absent", "unparsed"], 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").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>;
+            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

@@ -0,0 +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"}

package/dist/routes/public-spec.js

@@ -0,0 +1,31 @@
+import { defineApiContract } from '@toad-contracts/valibot';
+import { 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`.
+//
+// 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.
+// ---------------------------------------------------------------------------
+/**
+ * The service's in-repo specification: the structured requirement tree, the rendered Gherkin, and
+ * the ref + commit both were read at.
+ *
+ * `read` scope, like every other discovery and evidence read here. It is a read of what the
+ * service is committed to honouring, and an integration reviewing a run's outcome must be able to
+ * see the criteria it was scored against without holding a key that could also merge a pull
+ * request.
+ *
+ * Read-only by design, not by omission: see the note at the top of `../public-spec.ts`.
+ */
+export const getPublicServiceSpecContract = withMinScope('read', defineApiContract({
+    method: 'get',
+    requestPathParamsSchema: singleStringParam('serviceId'),
+    pathResolver: ({ serviceId }) => `/api/v1/services/${serviceId}/spec`,
+    responsesByStatusCode: { 200: publicServiceSpecSchema, ...errorResponses },
+}));
+//# sourceMappingURL=public-spec.js.map

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

@@ -0,0 +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"}

package/dist/routes/spec.d.ts

@@ -32,7 +32,6 @@ export declare const getServiceSpecContract: {
         readonly 200: import("valibot").ObjectSchema<{
             readonly present: import("valibot").BooleanSchema<undefined>;
             readonly spec: import("valibot").NullableSchema<import("valibot").ObjectSchema<{
-                readonly service: 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 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>]>;
@@ -63,6 +62,7 @@ export declare const getServiceSpecContract: {
                         }, 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>;
@@ -70,6 +70,14 @@ export declare const getServiceSpecContract: {
                 readonly path: import("valibot").StringSchema<undefined>;
                 readonly content: import("valibot").StringSchema<undefined>;
             }, undefined>, undefined>;
+            readonly diagnostics: import("valibot").OptionalSchema<import("valibot").ObjectSchema<{
+                readonly anchor: import("valibot").PicklistSchema<["present", "absent", "read_failed", "unparsed"], 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>;
+            }, undefined>, undefined>;
         }, undefined>;
     };
 };
@@ -116,7 +124,6 @@ export declare const getRunSpecContract: {
         readonly 200: import("valibot").ObjectSchema<{
             readonly present: import("valibot").BooleanSchema<undefined>;
             readonly spec: import("valibot").NullableSchema<import("valibot").ObjectSchema<{
-                readonly service: 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 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>]>;
@@ -147,6 +154,7 @@ export declare const getRunSpecContract: {
                         }, 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>;
@@ -154,6 +162,14 @@ export declare const getRunSpecContract: {
                 readonly path: import("valibot").StringSchema<undefined>;
                 readonly content: import("valibot").StringSchema<undefined>;
             }, undefined>, undefined>;
+            readonly diagnostics: import("valibot").OptionalSchema<import("valibot").ObjectSchema<{
+                readonly anchor: import("valibot").PicklistSchema<["present", "absent", "read_failed", "unparsed"], 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>;
+            }, undefined>, undefined>;
         }, undefined>;
     };
 };

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

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/routes/spec.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKjC,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK7B,CAAA"}
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/routes/spec.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKjC,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK7B,CAAA"}