@cat-factory/contracts 0.279.0 → 0.281.0

package/dist/routes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/routes/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,+EAA+E;AAC/E,oDAAoD;AACpD,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,0BAA0B,CAAA;AACxC,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,yBAAyB,CAAA;AACvC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AACtC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,uBAAuB,CAAA;AACrC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,gCAAgC,CAAA;AAC9C,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,mBAAmB,CAAA;AACjC,cAAc,wBAAwB,CAAA;AACtC,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/routes/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,+EAA+E;AAC/E,oDAAoD;AACpD,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,0BAA0B,CAAA;AACxC,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,yBAAyB,CAAA;AACvC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AACtC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,kBAAkB,CAAA;AAChC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,uBAAuB,CAAA;AACrC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,gCAAgC,CAAA;AAC9C,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,mBAAmB,CAAA;AACjC,cAAc,wBAAwB,CAAA;AACtC,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA"}

package/dist/routes/pipelines.d.ts

@@ -103,7 +103,7 @@ export declare const listPipelinesContract: {
             readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-            readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+            readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
         }, undefined>, undefined>;
     };
 };
@@ -182,7 +182,7 @@ export declare const createPipelineContract: {
         }, undefined>, undefined>, undefined>, undefined>;
         readonly labels: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 40, undefined>]>, undefined>, undefined>;
         readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-        readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+        readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
     }, undefined>;
     readonly responsesByStatusCode: {
         readonly '4xx': v.ObjectSchema<{
@@ -284,7 +284,7 @@ export declare const createPipelineContract: {
             readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-            readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+            readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
         }, undefined>;
     };
 };
@@ -399,7 +399,7 @@ export declare const clonePipelineContract: {
             readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-            readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+            readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
         }, undefined>;
     };
 };
@@ -512,7 +512,7 @@ export declare const reseedPipelineContract: {
             readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-            readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+            readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
         }, undefined>;
     };
 };
@@ -698,7 +698,7 @@ export declare const updatePipelineContract: {
             readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-            readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+            readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
         }, undefined>;
     };
 };
@@ -814,7 +814,7 @@ export declare const organizePipelineContract: {
             readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-            readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+            readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
         }, undefined>;
     };
 };

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"}

package/dist/routes/workspaces.d.ts

@@ -541,7 +541,7 @@ export declare const createWorkspaceContract: {
                 readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
                 readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
                 readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-                readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+                readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
             }, undefined>, undefined>;
             readonly executions: v.ArraySchema<v.ObjectSchema<{
                 readonly id: v.StringSchema<undefined>;
@@ -3992,7 +3992,7 @@ export declare const getWorkspaceContract: {
                 readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
                 readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
                 readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-                readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+                readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
             }, undefined>, undefined>;
             readonly executions: v.ArraySchema<v.ObjectSchema<{
                 readonly id: v.StringSchema<undefined>;

package/dist/snapshot.d.ts

@@ -479,7 +479,7 @@ export declare const workspaceSnapshotSchema: v.ObjectSchema<{
         readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         readonly public: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly availability: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"one-off", undefined>, v.LiteralSchema<"recurring", undefined>, v.LiteralSchema<"both", undefined>], undefined>, undefined>;
-        readonly purpose: v.OptionalSchema<v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>, undefined>;
+        readonly purpose: v.PicklistSchema<readonly ["build", "document", "review", "research", "planning"], undefined>;
     }, undefined>, undefined>;
     readonly executions: v.ArraySchema<v.ObjectSchema<{
         readonly id: v.StringSchema<undefined>;

package/dist/spec.d.ts

@@ -1,4 +1,12 @@
 import * as v from 'valibot';
+/**
+ * The two length bounds a READER has to honour to produce a parseable doc, exported so the
+ * reassembly clamps to the same numbers the schema enforces instead of restating them. A reader
+ * that clamps to its own constant passes its own tests and serves a `200` that fails the published
+ * schema the moment either number moves.
+ */
+export declare const SPEC_NAME_MAX = 120;
+export declare const SPEC_SUMMARY_MAX = 2000;
 /** MoSCoW priority — how essential a requirement is. */
 export declare const requirementPrioritySchema: v.PicklistSchema<["must", "should", "could"], undefined>;
 export type RequirementPriority = v.InferOutput<typeof requirementPrioritySchema>;
@@ -229,6 +237,71 @@ export declare const specDocSchema: v.ObjectSchema<{
     }, undefined>, undefined>, readonly []>;
 }, undefined>;
 export type SpecDoc = v.InferOutput<typeof specDocSchema>;
+/**
+ * The same document as a READER reassembles it, as opposed to as a producer must author it.
+ *
+ * Derived from {@link specDocSchema} rather than restated, so the two cannot drift, with exactly
+ * one field relaxed: `service` may be the empty string. The anchor (`spec/service.json`) is a file
+ * in somebody's repository and can be half-written, so a read has to be able to say "this spec
+ * names no service" (every consumer falls back to the board frame's own title). The STRICT schema
+ * stays the ingestion boundary `parseSpecDoc` guards, so nothing can AUTHOR a nameless spec; this
+ * one exists because refusing to describe one that already exists is the worse answer.
+ *
+ * Both infer the same TypeScript type. The difference is entirely in what each will PARSE, which
+ * is the difference that matters: a view typed `SpecDoc` while carrying `service: ''` is a value
+ * that fails the schema its own type names, and on `/api/v1` that is a published contract the
+ * response violates.
+ */
+export declare const readSpecDocSchema: v.ObjectSchema<{
+    /** One-paragraph product intent for the service overall. */
+    readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+    /** Modules (domains), each grouping its feature groups; the two-level taxonomy. */
+    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<{
+                /** Stable slug, e.g. `req-login-rate-limit`. */
+                readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+                /** Short headline. */
+                readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+                /** The requirement itself, as `The system SHALL …` prose. */
+                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>;
+                /**
+                 * Whether the service is already known to honour this requirement. Defaults to
+                 * `aspirational` — a requirement nobody has observed to hold is not standing behaviour, and
+                 * a spec written before the code is the normal case rather than the exceptional one. See
+                 * {@link requirementStateSchema}.
+                 */
+                readonly state: v.OptionalSchema<v.PicklistSchema<["aspirational", "established"], undefined>, "aspirational">;
+                /** Ids of the board task/block(s) this requirement was aggregated from (provenance). */
+                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 []>;
+                /** Structured acceptance criteria → the seed for this requirement's Gherkin scenarios. */
+                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 []>;
+            /** Domain rules / invariants scoped to this feature (rendered into its `<group>.md`). */
+            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>]>;
+                /** The invariant, e.g. `An order may never have a negative total.` */
+                readonly rule: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+                /** Why the rule exists (optional). */
+                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>;
+export type ReadSpecDoc = v.InferOutput<typeof readSpecDocSchema>;
 /** Folder, relative to the repo root, that holds the persisted spec. */
 export declare const SPEC_DIR = "spec";
 /** Tiny file carrying only the service name + one-paragraph summary. */
@@ -251,6 +324,72 @@ export declare const specFeatureFileSchema: v.ObjectSchema<{
     readonly content: v.StringSchema<undefined>;
 }, undefined>;
 export type SpecFeatureFile = v.InferOutput<typeof specFeatureFileSchema>;
+/**
+ * What became of ONE file the reader touched. The reader is deliberately total and salvaging
+ * (a flaky read or a malformed shard degrades to a partial tree rather than a thrown error), and
+ * a salvage that reports nothing is indistinguishable from a repo that genuinely holds less:
+ *
+ *  - `read_failed`: the provider answered with something other than "absent" (rate limit, 5xx,
+ *    a permission the installation lost). The file may well exist; we cannot say.
+ *  - `unparsed`:    the file was read and NOTHING could be recovered from it (unreadable JSON,
+ *    or a shard whose own identity is missing), so its whole subtree is missing from the view.
+ *  - `partial`:     the file was read and salvaged item by item; `dropped` says how many
+ *    requirements/rules failed validation and are therefore absent from an otherwise valid group.
+ *  - `unread`:      the pass ran out of its read budget before reaching this path, so it was never
+ *    fetched. `dropped` counts the files left unread. Reported against the `spec` root, once per
+ *    pass: a per-file row would make the budget's own report the largest thing in the response.
+ */
+export declare const specReadIssueKindSchema: v.PicklistSchema<["read_failed", "unparsed", "partial", "unread"], undefined>;
+export type SpecReadIssueKind = v.InferOutput<typeof specReadIssueKindSchema>;
+/** One file the reader could not fully account for, named rather than silently dropped. */
+export declare const specReadIssueSchema: v.ObjectSchema<{
+    /** Repo-relative path of the file (or directory, for a failed listing). */
+    readonly path: v.StringSchema<undefined>;
+    readonly kind: v.PicklistSchema<["read_failed", "unparsed", "partial", "unread"], undefined>;
+    /**
+     * How much this row cost the tree: items lost from a `partial` file, files left unread by an
+     * exhausted budget, 0 on the kinds that lose nothing countable.
+     *
+     * NULL means content was lost here and NO count describes it. A salvage reaches that state
+     * honestly: a shard whose `requirements` is an object rather than a list has requirements that
+     * are structurally unreadable, so there is nothing to count, and answering `0` would report the
+     * rebuilt group as a complete one that simply declares nothing. An unknown loss and no loss are
+     * different facts, and only a distinct value states the first.
+     */
+    readonly dropped: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, 0>;
+}, undefined>;
+export type SpecReadIssue = v.InferOutput<typeof specReadIssueSchema>;
+/**
+ * How the PRESENCE ANCHOR (`spec/service.json`) resolved. Four states rather than the boolean
+ * `present` beside it, because three of them produce the same empty tree and demand different
+ * reactions: a branch with no spec is a normal answer, a provider outage is a retry, and a corrupt
+ * anchor is a repo somebody has to fix. Collapsing them is how "this service has no requirements"
+ * comes to be reported during every VCS incident.
+ */
+export declare const specAnchorStateSchema: v.PicklistSchema<["present", "absent", "read_failed", "unparsed"], undefined>;
+export type SpecAnchorState = v.InferOutput<typeof specAnchorStateSchema>;
+/** What the reader could and could not account for on this pass. */
+export declare const specReadDiagnosticsSchema: v.ObjectSchema<{
+    readonly anchor: v.PicklistSchema<["present", "absent", "read_failed", "unparsed"], undefined>;
+    /** Every file the pass could not fully account for. Empty on a clean read. */
+    readonly issues: v.ArraySchema<v.ObjectSchema<{
+        /** Repo-relative path of the file (or directory, for a failed listing). */
+        readonly path: v.StringSchema<undefined>;
+        readonly kind: v.PicklistSchema<["read_failed", "unparsed", "partial", "unread"], undefined>;
+        /**
+         * How much this row cost the tree: items lost from a `partial` file, files left unread by an
+         * exhausted budget, 0 on the kinds that lose nothing countable.
+         *
+         * NULL means content was lost here and NO count describes it. A salvage reaches that state
+         * honestly: a shard whose `requirements` is an object rather than a list has requirements that
+         * are structurally unreadable, so there is nothing to count, and answering `0` would report the
+         * rebuilt group as a complete one that simply declares nothing. An unknown loss and no loss are
+         * different facts, and only a distinct value states the first.
+         */
+        readonly dropped: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, 0>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type SpecReadDiagnostics = v.InferOutput<typeof specReadDiagnosticsSchema>;
 /**
  * The service-spec view served to the SPA: the reassembled prescriptive spec tree read
  * from the service repo's default branch, plus its rendered Gherkin feature files.
@@ -260,10 +399,13 @@ export type SpecFeatureFile = v.InferOutput<typeof specFeatureFileSchema>;
 export declare const serviceSpecViewSchema: v.ObjectSchema<{
     /** Whether a spec exists on the service repo's default branch (a `spec/service.json`). */
     readonly present: v.BooleanSchema<undefined>;
-    /** The reassembled spec tree, or null when none is present. */
+    /**
+     * The reassembled spec tree, or null when none is present.
+     *
+     * {@link readSpecDocSchema}, not the strict authoring schema: this is what a READER got back
+     * out of a repository, and an anchor that names no service is a state a repository can be in.
+     */
     readonly spec: v.NullableSchema<v.ObjectSchema<{
-        /** Service / frame name (defaults to the repo name). */
-        readonly service: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
         /** One-paragraph product intent for the service overall. */
         readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
         /** Modules (domains), each grouping its feature groups; the two-level taxonomy. */
@@ -310,6 +452,7 @@ export declare const serviceSpecViewSchema: v.ObjectSchema<{
                 }, 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 feature files (empty when none present). The producer always
      * sends this field (`[]` when there are none), and the SPA dereferences it unguarded, so
@@ -324,6 +467,32 @@ export declare const serviceSpecViewSchema: v.ObjectSchema<{
         /** The raw Gherkin content. */
         readonly content: v.StringSchema<undefined>;
     }, undefined>, undefined>;
+    /**
+     * What the READ itself could account for, as distinct from what the spec says. Optional
+     * because absent means "this producer diagnosed nothing", which is a different fact from a
+     * clean pass and is the honest answer for the callers that assemble a view by hand (a memo, a
+     * test fixture). `readServiceSpec` always sets it.
+     */
+    readonly diagnostics: v.OptionalSchema<v.ObjectSchema<{
+        readonly anchor: v.PicklistSchema<["present", "absent", "read_failed", "unparsed"], undefined>;
+        /** Every file the pass could not fully account for. Empty on a clean read. */
+        readonly issues: v.ArraySchema<v.ObjectSchema<{
+            /** Repo-relative path of the file (or directory, for a failed listing). */
+            readonly path: v.StringSchema<undefined>;
+            readonly kind: v.PicklistSchema<["read_failed", "unparsed", "partial", "unread"], undefined>;
+            /**
+             * How much this row cost the tree: items lost from a `partial` file, files left unread by an
+             * exhausted budget, 0 on the kinds that lose nothing countable.
+             *
+             * NULL means content was lost here and NO count describes it. A salvage reaches that state
+             * honestly: a shard whose `requirements` is an object rather than a list has requirements that
+             * are structurally unreadable, so there is nothing to count, and answering `0` would report the
+             * rebuilt group as a complete one that simply declares nothing. An unknown loss and no loss are
+             * different facts, and only a distinct value states the first.
+             */
+            readonly dropped: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, 0>;
+        }, undefined>, undefined>;
+    }, undefined>, undefined>;
 }, undefined>;
 export type ServiceSpecView = v.InferOutput<typeof serviceSpecViewSchema>;
 /** The canonical "no spec" view — GitHub not connected, or no spec on the default branch. */

package/dist/spec.d.ts.map

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