@opensoftware/contracts 1.4.0 → 1.5.0

package/README.md

@@ -42,8 +42,17 @@ Each format has one schema, generated from `typespec/`, and fixtures that CONTRA
 | run record | `run-record/run-record.schema.json` | `RunRecord` | OTel resource and root-span attributes; pins in `typespec/run-record.tsp`. |
 | evidence bundle | `evidence-bundle/evidence-bundle.schema.json` | `EvidenceManifest` | `evidence.json` at the bundle root. |
 | score | `score/score.schema.json` | `Score` | Subset of Langfuse's create-score request; factory fields in `metadata`. |
+| gate record | `gate-record/gate-record.schema.json` | `GateRecord` | gatekeeper's signed approval record (ADR 0047). |
 | events | `events/<event>/<event>.schema.json`, `events/asyncapi.yaml` | `WorkReceived` … `PrClosed` | CloudEvents 1.0, structured JSON. |
 
+## HTTP APIs
+
+`openapi/openapi.json` also holds the paths of the module APIs, from the operations in `typespec/` (ADR 0048). The
+first is gatekeeper's: `POST /v1/gates` and `GET /v1/gates/{gateId}` with the models `GateRequest`, `GateView` and
+`ApiProblem` (RFC 9457). `pnpm build` compiles the operations with the TypeSpec OpenAPI 3 emitter and copies their
+paths next to the named models; an operation that uses a type that is no model fails the build. The package exports
+the type `paths`, which types a client such as openapi-fetch.
+
 Wire formats (everything but the factory definition) are open: readers ignore fields they do not know, so a minor
 version may add optional fields. Read `factory.yaml` with a YAML 1.2 parser: YAML 1.1 parsers turn the key `on`
 into `true`.
@@ -71,8 +80,9 @@ release-please opens a release pull request from the Conventional Commits under
 the tag `contracts-v<version>`. The release pull request also sets the version in `openapi/openapi.json`, which
 `pnpm build` copies from `package.json`, so the generated file stays current. The workflow `.github/workflows/publish-contracts.yml` then builds the package and
 publishes it to npm as `@opensoftware/contracts`. npm accepts a provenance statement only from a public
-repository, so the workflow adds one only when this repository is public. To publish a tag again, run the
-workflow by hand with the tag. The CONTRACT check and `osf-contracts breaking` compare with the newest `contracts-v*` tag.
+repository, so the workflow adds one only when this repository is public. When the newest tag is missing on npm,
+for example after a failed upload, the next run of the workflow on `main` publishes it. To publish a tag again, run
+the workflow by hand with the tag. The CONTRACT check and `osf-contracts breaking` compare with the newest `contracts-v*` tag.
 
 Only the TypeScript package exists (ADR 0012). A client for another language can be generated from
 `openapi/openapi.json` with any OpenAPI generator when someone needs one.

package/dist/formats.js

@@ -6,6 +6,7 @@ export const FORMATS = [
     format("run-record", "RunRecord"),
     format("evidence-bundle", "EvidenceManifest"),
     format("score", "Score"),
+    format("gate-record", "GateRecord"),
     format("events/work-received", "WorkReceived"),
     format("events/run-completed", "RunCompleted"),
     format("events/gate-requested", "GateRequested"),

package/dist/formats.js.map

@@ -1 +1 @@
-{"version":3,"file":"formats.js","sourceRoot":"","sources":["../src/formats.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAW3G,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAY,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAEjH,MAAM,CAAC,MAAM,OAAO,GAAsB;IACxC,MAAM,CAAC,oBAAoB,EAAE,mBAAmB,CAAC;IACjD,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC;IAC/B,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC;IACjC,MAAM,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IAC7C,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,sBAAsB,EAAE,cAAc,CAAC;IAC9C,MAAM,CAAC,sBAAsB,EAAE,cAAc,CAAC;IAC9C,MAAM,CAAC,uBAAuB,EAAE,eAAe,CAAC;IAChD,MAAM,CAAC,qBAAqB,EAAE,aAAa,CAAC;IAC5C,MAAM,CAAC,uBAAuB,EAAE,eAAe,CAAC;IAChD,MAAM,CAAC,kBAAkB,EAAE,UAAU,CAAC;IACtC,MAAM,CAAC,oBAAoB,EAAE,YAAY,CAAC;IAC1C,MAAM,CAAC,kBAAkB,EAAE,UAAU,CAAC;CACvC,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"formats.js","sourceRoot":"","sources":["../src/formats.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAW3G,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAY,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAEjH,MAAM,CAAC,MAAM,OAAO,GAAsB;IACxC,MAAM,CAAC,oBAAoB,EAAE,mBAAmB,CAAC;IACjD,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC;IAC/B,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC;IACjC,MAAM,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IAC7C,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,aAAa,EAAE,YAAY,CAAC;IACnC,MAAM,CAAC,sBAAsB,EAAE,cAAc,CAAC;IAC9C,MAAM,CAAC,sBAAsB,EAAE,cAAc,CAAC;IAC9C,MAAM,CAAC,uBAAuB,EAAE,eAAe,CAAC;IAChD,MAAM,CAAC,qBAAqB,EAAE,aAAa,CAAC;IAC5C,MAAM,CAAC,uBAAuB,EAAE,eAAe,CAAC;IAChD,MAAM,CAAC,kBAAkB,EAAE,UAAU,CAAC;IACtC,MAAM,CAAC,oBAAoB,EAAE,YAAY,CAAC;IAC1C,MAAM,CAAC,kBAAkB,EAAE,UAAU,CAAC;CACvC,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC9D,CAAC"}

package/dist/generated/types.d.ts

@@ -1,4 +1,39 @@
-export type paths = Record<string, never>;
+export type paths = {
+    "/v1/gates": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Ask the policy's approver groups for a decision. The same request again answers the gate it made before. */
+        post: operations["GatekeeperApi_requestGate"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/gates/{gateId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description A gate: its state, and its record once it is decided. */
+        get: operations["GatekeeperApi_getGate"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+};
 export type webhooks = Record<string, never>;
 export type components = {
     schemas: {
@@ -33,6 +68,15 @@ export type components = {
             /** @description Runtime of the agent. */
             sandbox?: components["schemas"]["Sandbox"];
         };
+        /** @description An error of an HTTP API (RFC 9457). */
+        ApiProblem: {
+            /** @description A short summary, the same for every occurrence of the problem. */
+            title: string;
+            /** @description The HTTP status code. */
+            status: number;
+            /** @description What went wrong this time, for example the field that is missing. */
+            detail?: string;
+        };
         Artifact: {
             path: components["schemas"]["BundlePath"];
             kind: components["schemas"]["ArtifactKind"];
@@ -172,6 +216,47 @@ export type components = {
         };
         /** @enum {string} */
         GateDecision: "approved" | "rejected" | "expired";
+        /** @description gatekeeper: who decided what and when, signed with Ed25519 (ADR 0047). */
+        GateRecord: {
+            gate: string;
+            workItem: string;
+            stage: components["schemas"]["Name"];
+            summary: string;
+            /** @description SHA-256 of the canonical request: what was approved. */
+            request: string;
+            /** @description The policy file. */
+            policy: string;
+            /** @description SHA-256 of the policy's text: the rules that picked the approvers. */
+            policyDigest: string;
+            risk?: string;
+            approvers: components["schemas"]["Name"][];
+            channel: string;
+            /** Format: date-time */
+            requestedAt: string;
+            decision: components["schemas"]["GateDecision"];
+            /** @description Who decided. Absent only when the gate expired. A policy that names no group decides as a trigger. */
+            decidedBy?: components["schemas"]["Actor"];
+            /** Format: date-time */
+            decidedAt: string;
+            /** @description The reason of a rejection. */
+            reason?: string;
+            /** @description Ed25519 over the canonical JSON of the rest of the record. Absent when the record is unsigned. */
+            signature?: components["schemas"]["RecordSignature"];
+        };
+        /** @description gatekeeper: what a person is asked to approve, and the facts the policy decides on (ADR 0047). */
+        GateRequest: {
+            /** @description What waits: a work item ID or a URL. */
+            workItem: string;
+            /** @description The stage that waits, for example "merge". */
+            stage: components["schemas"]["Name"];
+            /** @description What the approvers decide, shown in the channel. */
+            summary: string;
+            links?: components["schemas"]["Link"][];
+            /** @description Any facts the policy needs, such as changed paths, labels or the author. */
+            change?: {
+                [key: string]: unknown;
+            };
+        };
         /** @description gatekeeper: a decision is needed before a stage starts. */
         GateRequested: {
             /** @constant */
@@ -210,6 +295,39 @@ export type components = {
             /** Format: date-time */
             expiresAt?: string;
         };
+        /**
+         * @description A gate's state: waiting, or how it was decided.
+         * @enum {string}
+         */
+        GateState: "pending" | "approved" | "rejected" | "expired";
+        /** @description gatekeeper: a gate as the HTTP API shows it (ADR 0048). */
+        GateView: {
+            /** @description "g" and 16 hex digits of the SHA-256 of the work item, the stage and the change. */
+            id: string;
+            workItem: string;
+            stage: components["schemas"]["Name"];
+            summary: string;
+            /** @description The risk the policy named, for example "high". */
+            risk?: string;
+            /** @description The groups whose members may decide. Empty when the policy approved without a person. */
+            approvers: components["schemas"]["Name"][];
+            /** @description The groups asked after the escalation time. */
+            escalateTo?: components["schemas"]["Name"][];
+            /** @description Where people decide, for example "slack:C0GATES". */
+            channel: string;
+            state: components["schemas"]["GateState"];
+            /** @description The groups that may decide now. Only while the gate is pending. */
+            waitingFor?: components["schemas"]["Name"][];
+            /** Format: date-time */
+            requestedAt: string;
+            /**
+             * Format: date-time
+             * @description When the gate expires without a decision.
+             */
+            expiresAt?: string;
+            /** @description The record, once the gate is decided. */
+            record?: components["schemas"]["GateRecord"];
+        };
         /** @description An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque. */
         Identifier: string;
         Link: {
@@ -367,6 +485,14 @@ export type components = {
                 [key: string]: components["schemas"]["VersionRange"];
             };
         };
+        RecordSignature: {
+            /** @constant */
+            algorithm: "Ed25519";
+            /** @description SHA-256 of the public key in DER, like "sha256:…". */
+            key: string;
+            /** @description The signature in base64. */
+            value: string;
+        };
         /** @enum {string} */
         ReviewState: "approved" | "changes_requested" | "commented";
         /** @description foreman: a run ended. */
@@ -633,4 +759,96 @@ export type components = {
     pathItems: never;
 };
 export type $defs = Record<string, never>;
-export type operations = Record<string, never>;
+export interface operations {
+    GatekeeperApi_requestGate: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["GateRequest"];
+            };
+        };
+        responses: {
+            /** @description The request has succeeded. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GateView"];
+                };
+            };
+            /** @description The request has succeeded and a new resource has been created as a result. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GateView"];
+                };
+            };
+            /** @description The server could not understand the request due to invalid syntax. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiProblem"];
+                };
+            };
+            /** @description Access is unauthorized. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiProblem"];
+                };
+            };
+        };
+    };
+    GatekeeperApi_getGate: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                gateId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The request has succeeded. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GateView"];
+                };
+            };
+            /** @description Access is unauthorized. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiProblem"];
+                };
+            };
+            /** @description The server cannot find the requested resource. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiProblem"];
+                };
+            };
+        };
+    };
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { type Format } from "./formats.ts";
 import type { components } from "./generated/types.ts";
 export { diff as breakingChanges, type Schema } from "./breaking.ts";
 export { FORMATS, type Format, formatNamed } from "./formats.ts";
-export type { components } from "./generated/types.ts";
+export type { components, paths } from "./generated/types.ts";
 export { type AttributeValue, type RunSpan, runSpans, type SpanAttributes } from "./run-record.ts";
 type Schemas = components["schemas"];
 export type FactoryDefinition = Schemas["FactoryDefinition"];
@@ -18,6 +18,10 @@ export type ScoreRecorded = Schemas["ScoreRecorded"];
 export type PrOpened = Schemas["PrOpened"];
 export type PrReviewed = Schemas["PrReviewed"];
 export type PrClosed = Schemas["PrClosed"];
+export type GateRecord = Schemas["GateRecord"];
+export type GateRequest = Schemas["GateRequest"];
+export type GateView = Schemas["GateView"];
+export type ApiProblem = Schemas["ApiProblem"];
 /** One reason a document does not match its format. `path` is a JSON Pointer into the document. */
 export interface Problem {
     path: string;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,OAAO,EAAE,EAA2C,MAAM,kBAAkB,CAAC;AACpF,OAAO,UAAU,MAAM,aAAa,CAAC;AACrC,OAAO,EAAe,WAAW,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,EAAE,IAAI,IAAI,eAAe,EAAe,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,OAAO,EAAe,WAAW,EAAE,MAAM,cAAc,CAAC;AAEjE,OAAO,EAAqC,QAAQ,EAAuB,MAAM,iBAAiB,CAAC;AA2BnG,gGAAgG;AAChG,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AACjE,MAAM,UAAU,GAAG,IAAI,GAAG,EAA4B,CAAC;AAEvD,gFAAgF;AAChF,MAAM,UAAU,QAAQ,CAAC,MAAuB;IAC9C,MAAM,KAAK,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACxE,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,cAAc,CAAC,EAAE,MAAM,CAAC,CAG1F,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,QAAQ,CAAC,MAAuB,EAAE,QAAiB;IACjE,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;IAC/D,IAAI,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,2FAA2F;QAC3F,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1F,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACxB,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACtC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,OAAO,CAAI,MAAuB,EAAE,QAAiB;IACnE,OAAO,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAEjD,iHAAiH;AACjH,SAAS,QAAQ,CAAC,MAAqB;IACrC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAClH,MAAM,iBAAiB,GAAG,CAAC,KAAkB,EAAW,EAAE,CACxD,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC;QAChC,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;QAC1C,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,KAAK,IAAI,IAAI,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;IACxG,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,SAAS;QACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACjD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,KAAkB;IAClC,MAAM,KAAK,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,GAAG,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;IACpH,QAAQ,KAAK,CAAC,OAAO,EAAE,CAAC;QACtB,KAAK,sBAAsB;YACzB,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;QAC5F,KAAK,uBAAuB;YAC1B,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;QAC7F,KAAK,UAAU;YACb,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC;QAClG,KAAK,OAAO,CAAC;QACb,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,YAAY,IAAI,GAAG,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC;QACrG;YACE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,YAAY,IAAI,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;IACxF,CAAC;AACH,CAAC"}

package/gate-record/gate-record.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/gate-record/gate-record.schema.json",
+  "title": "GateRecord",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "gate": {
+      "type": "string",
+      "pattern": "^g[0-9a-f]{16}$"
+    },
+    "workItem": {
+      "type": "string"
+    },
+    "stage": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,62}$",
+      "description": "A lowercase name: letters, digits and hyphens, starting with a letter. Agents, stages, adapters, sources."
+    },
+    "summary": {
+      "type": "string"
+    },
+    "request": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$",
+      "description": "SHA-256 of the canonical request: what was approved."
+    },
+    "policy": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The policy file."
+    },
+    "policyDigest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$",
+      "description": "SHA-256 of the policy's text: the rules that picked the approvers."
+    },
+    "risk": {
+      "type": "string"
+    },
+    "approvers": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]{0,62}$",
+        "description": "A lowercase name: letters, digits and hyphens, starting with a letter. Agents, stages, adapters, sources."
+      }
+    },
+    "channel": {
+      "type": "string"
+    },
+    "requestedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "decision": {
+      "type": "string",
+      "enum": [
+        "approved",
+        "rejected",
+        "expired"
+      ]
+    },
+    "decidedBy": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "person",
+            "trigger"
+          ],
+          "description": "Who caused something: a person, or an automated trigger such as a cron rule or an alert."
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable ID in the source system, prefixed with the source, for example \"slack:U024BE7LH\"."
+        },
+        "displayName": {
+          "type": "string",
+          "description": "Shown to people, for example \"Varun\"."
+        }
+      },
+      "required": [
+        "kind",
+        "id"
+      ],
+      "description": "Who decided. Absent only when the gate expired. A policy that names no group decides as a trigger."
+    },
+    "decidedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "reason": {
+      "type": "string",
+      "description": "The reason of a rejection."
+    },
+    "signature": {
+      "type": "object",
+      "properties": {
+        "algorithm": {
+          "type": "string",
+          "const": "Ed25519"
+        },
+        "key": {
+          "type": "string",
+          "pattern": "^sha256:",
+          "description": "SHA-256 of the public key in DER, like \"sha256:…\"."
+        },
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The signature in base64."
+        }
+      },
+      "required": [
+        "algorithm",
+        "key",
+        "value"
+      ],
+      "description": "Ed25519 over the canonical JSON of the rest of the record. Absent when the record is unsigned."
+    }
+  },
+  "required": [
+    "gate",
+    "workItem",
+    "stage",
+    "summary",
+    "request",
+    "policy",
+    "policyDigest",
+    "approvers",
+    "channel",
+    "requestedAt",
+    "decision",
+    "decidedAt"
+  ],
+  "description": "gatekeeper: who decided what and when, signed with Ed25519 (ADR 0047)."
+}

package/openapi/openapi.json

@@ -2,14 +2,127 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "1.4.0",
-    "description": "The shared formats as named models. No operations: module APIs are added per module. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+    "version": "1.5.0",
+    "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",
       "identifier": "Apache-2.0"
     }
   },
-  "paths": {},
+  "paths": {
+    "/v1/gates": {
+      "post": {
+        "operationId": "GatekeeperApi_requestGate",
+        "description": "Ask the policy's approver groups for a decision. The same request again answers the gate it made before.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GateView"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GateView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GateRequest"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/gates/{gateId}": {
+      "get": {
+        "operationId": "GatekeeperApi_getGate",
+        "description": "A gate: its state, and its record once it is decided.",
+        "parameters": [
+          {
+            "name": "gateId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GateView"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "BearerAuth": []
+    }
+  ],
   "components": {
     "schemas": {
       "Actor": {
@@ -101,6 +214,31 @@
         ],
         "additionalProperties": false
       },
+      "ApiProblem": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A short summary, the same for every occurrence of the problem."
+          },
+          "status": {
+            "type": "integer",
+            "minimum": -2147483648,
+            "maximum": 2147483647,
+            "description": "The HTTP status code."
+          },
+          "detail": {
+            "type": "string",
+            "description": "What went wrong this time, for example the field that is missing."
+          }
+        },
+        "required": [
+          "title",
+          "status"
+        ],
+        "description": "An error of an HTTP API (RFC 9457)."
+      },
       "Artifact": {
         "type": "object",
         "properties": {
@@ -489,6 +627,127 @@
           "expired"
         ]
       },
+      "GateRecord": {
+        "type": "object",
+        "properties": {
+          "gate": {
+            "type": "string",
+            "pattern": "^g[0-9a-f]{16}$"
+          },
+          "workItem": {
+            "type": "string"
+          },
+          "stage": {
+            "$ref": "#/components/schemas/Name"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "request": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$",
+            "description": "SHA-256 of the canonical request: what was approved."
+          },
+          "policy": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The policy file."
+          },
+          "policyDigest": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$",
+            "description": "SHA-256 of the policy's text: the rules that picked the approvers."
+          },
+          "risk": {
+            "type": "string"
+          },
+          "approvers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            }
+          },
+          "channel": {
+            "type": "string"
+          },
+          "requestedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "decision": {
+            "$ref": "#/components/schemas/GateDecision"
+          },
+          "decidedBy": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "Who decided. Absent only when the gate expired. A policy that names no group decides as a trigger."
+          },
+          "decidedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "reason": {
+            "type": "string",
+            "description": "The reason of a rejection."
+          },
+          "signature": {
+            "$ref": "#/components/schemas/RecordSignature",
+            "description": "Ed25519 over the canonical JSON of the rest of the record. Absent when the record is unsigned."
+          }
+        },
+        "required": [
+          "gate",
+          "workItem",
+          "stage",
+          "summary",
+          "request",
+          "policy",
+          "policyDigest",
+          "approvers",
+          "channel",
+          "requestedAt",
+          "decision",
+          "decidedAt"
+        ],
+        "description": "gatekeeper: who decided what and when, signed with Ed25519 (ADR 0047)."
+      },
+      "GateRequest": {
+        "type": "object",
+        "properties": {
+          "workItem": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "What waits: a work item ID or a URL."
+          },
+          "stage": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The stage that waits, for example \"merge\"."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What the approvers decide, shown in the channel."
+          },
+          "links": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Link"
+            }
+          },
+          "change": {
+            "type": "object",
+            "properties": {},
+            "unevaluatedProperties": {},
+            "description": "Any facts the policy needs, such as changed paths, labels or the author."
+          }
+        },
+        "required": [
+          "workItem",
+          "stage",
+          "summary"
+        ],
+        "description": "gatekeeper: what a person is asked to approve, and the facts the policy decides on (ADR 0047)."
+      },
       "GateRequested": {
         "type": "object",
         "properties": {
@@ -597,6 +856,91 @@
           "summary"
         ]
       },
+      "GateState": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "approved",
+          "rejected",
+          "expired"
+        ],
+        "description": "A gate's state: waiting, or how it was decided."
+      },
+      "GateView": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^g[0-9a-f]{16}$",
+            "description": "\"g\" and 16 hex digits of the SHA-256 of the work item, the stage and the change."
+          },
+          "workItem": {
+            "type": "string"
+          },
+          "stage": {
+            "$ref": "#/components/schemas/Name"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "risk": {
+            "type": "string",
+            "description": "The risk the policy named, for example \"high\"."
+          },
+          "approvers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The groups whose members may decide. Empty when the policy approved without a person."
+          },
+          "escalateTo": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The groups asked after the escalation time."
+          },
+          "channel": {
+            "type": "string",
+            "description": "Where people decide, for example \"slack:C0GATES\"."
+          },
+          "state": {
+            "$ref": "#/components/schemas/GateState"
+          },
+          "waitingFor": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The groups that may decide now. Only while the gate is pending."
+          },
+          "requestedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "expiresAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the gate expires without a decision."
+          },
+          "record": {
+            "$ref": "#/components/schemas/GateRecord",
+            "description": "The record, once the gate is decided."
+          }
+        },
+        "required": [
+          "id",
+          "workItem",
+          "stage",
+          "summary",
+          "approvers",
+          "channel",
+          "state",
+          "requestedAt"
+        ],
+        "description": "gatekeeper: a gate as the HTTP API shows it (ADR 0048)."
+      },
       "Identifier": {
         "type": "string",
         "minLength": 1,
@@ -997,6 +1341,30 @@
         "description": "The adapters a factory uses, per port (docs/architecture/internals.md). Keys are adapter names.",
         "additionalProperties": false
       },
+      "RecordSignature": {
+        "type": "object",
+        "properties": {
+          "algorithm": {
+            "type": "string",
+            "const": "Ed25519"
+          },
+          "key": {
+            "type": "string",
+            "pattern": "^sha256:",
+            "description": "SHA-256 of the public key in DER, like \"sha256:…\"."
+          },
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The signature in base64."
+          }
+        },
+        "required": [
+          "algorithm",
+          "key",
+          "value"
+        ]
+      },
       "ReviewState": {
         "type": "string",
         "enum": [
@@ -1710,6 +2078,12 @@
         ],
         "description": "intake: a work item was accepted."
       }
+    },
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "Bearer"
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
   "license": "Apache-2.0",
   "repository": {
@@ -39,9 +39,12 @@
   "devDependencies": {
     "@asyncapi/parser": "3.6.6",
     "@typespec/compiler": "1.17.0",
+    "@typespec/http": "1.17.0",
     "@typespec/json-schema": "1.17.0",
+    "@typespec/openapi": "1.17.0",
+    "@typespec/openapi3": "1.17.0",
     "openapi-typescript": "7.13.0",
-    "@opensoftware/testkit": "0.8.0"
+    "@opensoftware/testkit": "0.12.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",

package/typespec/gatekeeper-api.tsp

@@ -0,0 +1,39 @@
+// The HTTP API of `gatekeeper serve` (ADR 0048). `pnpm build` compiles it with the OpenAPI 3 emitter and copies its
+// paths into openapi/openapi.json; the models are the named models of the JSON Schema bundle.
+import "@typespec/http";
+import "./gatekeeper.tsp";
+
+using TypeSpec.Http;
+
+@service(#{ title: "Open Software Factory contracts" })
+@useAuth(BearerAuth)
+namespace Osf.Contracts;
+
+namespace GatekeeperApi {
+  @error
+  model Failure<Code extends int32> {
+    @statusCode statusCode: Code;
+    @header contentType: "application/problem+json";
+    @body problem: ApiProblem;
+  }
+
+  /** Ask the policy's approver groups for a decision. The same request again answers the gate it made before. */
+  @route("/v1/gates")
+  @post
+  op requestGate(@body request: GateRequest):
+    | {
+        @statusCode statusCode: 201;
+        @body gate: GateView;
+      }
+    | {
+        @statusCode statusCode: 200;
+        @body gate: GateView;
+      }
+    | Failure<400>
+    | Failure<401>;
+
+  /** A gate: its state, and its record once it is decided. */
+  @route("/v1/gates/{gateId}")
+  @get
+  op getGate(@path gateId: string): GateView | Failure<401> | Failure<404>;
+}

package/typespec/gatekeeper.tsp

@@ -0,0 +1,134 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/** gatekeeper: what a person is asked to approve, and the facts the policy decides on (ADR 0047). */
+model GateRequest {
+  /** What waits: a work item ID or a URL. */
+  @minLength(1)
+  @maxLength(128)
+  workItem: string;
+
+  /** The stage that waits, for example "merge". */
+  stage: Name;
+
+  /** What the approvers decide, shown in the channel. */
+  @minLength(1)
+  summary: string;
+
+  links?: Link[];
+
+  /** Any facts the policy needs, such as changed paths, labels or the author. */
+  change?: Record<unknown>;
+}
+
+/** A gate's state: waiting, or how it was decided. */
+enum GateState {
+  pending,
+  approved,
+  rejected,
+  expired,
+}
+
+/** gatekeeper: a gate as the HTTP API shows it (ADR 0048). */
+model GateView {
+  /** "g" and 16 hex digits of the SHA-256 of the work item, the stage and the change. */
+  @pattern("^g[0-9a-f]{16}$")
+  id: string;
+
+  workItem: string;
+  stage: Name;
+  summary: string;
+
+  /** The risk the policy named, for example "high". */
+  risk?: string;
+
+  /** The groups whose members may decide. Empty when the policy approved without a person. */
+  approvers: Name[];
+
+  /** The groups asked after the escalation time. */
+  escalateTo?: Name[];
+
+  /** Where people decide, for example "slack:C0GATES". */
+  channel: string;
+
+  state: GateState;
+
+  /** The groups that may decide now. Only while the gate is pending. */
+  waitingFor?: Name[];
+
+  requestedAt: utcDateTime;
+
+  /** When the gate expires without a decision. */
+  expiresAt?: utcDateTime;
+
+  /** The record, once the gate is decided. */
+  record?: GateRecord;
+}
+
+/** gatekeeper: who decided what and when, signed with Ed25519 (ADR 0047). */
+model GateRecord {
+  @pattern("^g[0-9a-f]{16}$")
+  gate: string;
+
+  workItem: string;
+  stage: Name;
+  summary: string;
+
+  /** SHA-256 of the canonical request: what was approved. */
+  @pattern("^sha256:[0-9a-f]{64}$")
+  request: string;
+
+  /** The policy file. */
+  @minLength(1)
+  policy: string;
+
+  /** SHA-256 of the policy's text: the rules that picked the approvers. */
+  @pattern("^sha256:[0-9a-f]{64}$")
+  policyDigest: string;
+
+  risk?: string;
+  approvers: Name[];
+  channel: string;
+  requestedAt: utcDateTime;
+  decision: GateDecision;
+
+  /** Who decided. Absent only when the gate expired. A policy that names no group decides as a trigger. */
+  decidedBy?: Actor;
+
+  decidedAt: utcDateTime;
+
+  /** The reason of a rejection. */
+  reason?: string;
+
+  /** Ed25519 over the canonical JSON of the rest of the record. Absent when the record is unsigned. */
+  signature?: RecordSignature;
+}
+
+model RecordSignature {
+  algorithm: "Ed25519";
+
+  /** SHA-256 of the public key in DER, like "sha256:…". */
+  @pattern("^sha256:")
+  key: string;
+
+  /** The signature in base64. */
+  @minLength(1)
+  value: string;
+}
+
+/** An error of an HTTP API (RFC 9457). */
+model ApiProblem {
+  /** A short summary, the same for every occurrence of the problem. */
+  @minLength(1)
+  title: string;
+
+  /** The HTTP status code. */
+  status: int32;
+
+  /** What went wrong this time, for example the field that is missing. */
+  detail?: string;
+}

package/typespec/main.tsp

@@ -8,3 +8,5 @@ import "./run-record.tsp";
 import "./evidence-bundle.tsp";
 import "./score.tsp";
 import "./events.tsp";
+import "./gatekeeper.tsp";
+import "./gatekeeper-api.tsp";