overseer-testing-protocol 0.1.0

data/protocol/testing-control/v3/fixtures/error-response.json

@@ -0,0 +1,20 @@
+{
+  "protocol": {
+    "name": "overseer-testing-control",
+    "version": "3"
+  },
+  "meta": {
+    "runId": "run-2026-07-31-001",
+    "correlationId": "1ccafac8-0f96-4277-a2d1-21fa4300ec16",
+    "stepId": "setup-active-user"
+  },
+  "errors": [
+    {
+      "code": "schema-validation-failed",
+      "title": "State input is invalid",
+      "detail": "The requested state input does not satisfy its advertised schema.",
+      "pointer": "/data/input/email",
+      "retryable": false
+    }
+  ]
+}

data/protocol/testing-control/v3/fixtures/manifest.json

@@ -0,0 +1,13 @@
+{
+  "capabilities-response": "capabilities-response.json",
+  "reset-response": "reset-response.json",
+  "state-request": "state-request.json",
+  "state-response": "state-response.json",
+  "probe-request": "probe-request.json",
+  "probe-response": "probe-response.json",
+  "sink-query-request": "sink-query-request.json",
+  "sink-query-response": "sink-query-response.json",
+  "error-response": "error-response.json",
+  "conformance-case": "conformance-case.json",
+  "conformance-report": "conformance-report.json"
+}

data/protocol/testing-control/v3/fixtures/probe-request.json

@@ -0,0 +1,20 @@
+{
+  "protocol": {
+    "name": "overseer-testing-control",
+    "version": "3"
+  },
+  "meta": {
+    "runId": "run-2026-07-31-001",
+    "correlationId": "e4508a64-0177-4941-a55c-a94402a83765",
+    "stepId": "deactivate-user"
+  },
+  "data": {
+    "capability": {
+      "id": "user-projection",
+      "version": "1"
+    },
+    "input": {
+      "userId": "user-001"
+    }
+  }
+}

data/protocol/testing-control/v3/fixtures/probe-response.json

@@ -0,0 +1,22 @@
+{
+  "protocol": {
+    "name": "overseer-testing-control",
+    "version": "3"
+  },
+  "meta": {
+    "runId": "run-2026-07-31-001",
+    "correlationId": "e4508a64-0177-4941-a55c-a94402a83765",
+    "stepId": "deactivate-user"
+  },
+  "data": {
+    "capability": {
+      "id": "user-projection",
+      "version": "1"
+    },
+    "observedAt": "2026-07-31T10:01:00.000Z",
+    "projection": {
+      "id": "user-001",
+      "status": "inactive"
+    }
+  }
+}

data/protocol/testing-control/v3/fixtures/reset-response.json

@@ -0,0 +1,15 @@
+{
+  "protocol": {
+    "name": "overseer-testing-control",
+    "version": "3"
+  },
+  "meta": {
+    "runId": "run-2026-07-31-001",
+    "correlationId": "3ad2eb88-1eba-4fe2-802d-88caff52a87e"
+  },
+  "data": {
+    "resetAt": "2026-07-31T10:00:00.000Z",
+    "strategy": "in-process",
+    "sinksCleared": true
+  }
+}

data/protocol/testing-control/v3/fixtures/sink-query-request.json

@@ -0,0 +1,26 @@
+{
+  "protocol": {
+    "name": "overseer-testing-control",
+    "version": "3"
+  },
+  "meta": {
+    "runId": "run-2026-07-31-001",
+    "correlationId": "f2e6bc89-3e8d-4cb5-b49b-7151c798a249",
+    "stepId": "deactivate-user"
+  },
+  "data": {
+    "capability": {
+      "id": "transactional-email",
+      "version": "1"
+    },
+    "filter": {
+      "correlationId": "public-request-001",
+      "stepId": "deactivate-user",
+      "effectKinds": ["email"]
+    },
+    "input": {
+      "template": "user-deactivated"
+    },
+    "limit": 25
+  }
+}

data/protocol/testing-control/v3/fixtures/sink-query-response.json

@@ -0,0 +1,39 @@
+{
+  "protocol": {
+    "name": "overseer-testing-control",
+    "version": "3"
+  },
+  "meta": {
+    "runId": "run-2026-07-31-001",
+    "correlationId": "f2e6bc89-3e8d-4cb5-b49b-7151c798a249",
+    "stepId": "deactivate-user"
+  },
+  "data": {
+    "capability": {
+      "id": "transactional-email",
+      "version": "1"
+    },
+    "records": [
+      {
+        "id": "effect-001",
+        "capability": {
+          "id": "transactional-email",
+          "version": "1"
+        },
+        "effectKind": "email",
+        "outcome": "success",
+        "correlationId": "public-request-001",
+        "stepId": "deactivate-user",
+        "capturedAt": "2026-07-31T10:01:01.000Z",
+        "summary": "user-deactivated email captured for synthetic recipient",
+        "metadata": {
+          "attempt": 1
+        },
+        "payload": {
+          "template": "user-deactivated",
+          "recipientAlias": "user-001"
+        }
+      }
+    ]
+  }
+}

data/protocol/testing-control/v3/fixtures/state-request.json

@@ -0,0 +1,20 @@
+{
+  "protocol": {
+    "name": "overseer-testing-control",
+    "version": "3"
+  },
+  "meta": {
+    "runId": "run-2026-07-31-001",
+    "correlationId": "33a02fd0-02e0-4df6-a309-2880a0196049",
+    "stepId": "setup-active-user"
+  },
+  "data": {
+    "capability": {
+      "id": "active-user",
+      "version": "1"
+    },
+    "input": {
+      "email": "user-001@example.invalid"
+    }
+  }
+}

data/protocol/testing-control/v3/fixtures/state-response.json

@@ -0,0 +1,23 @@
+{
+  "protocol": {
+    "name": "overseer-testing-control",
+    "version": "3"
+  },
+  "meta": {
+    "runId": "run-2026-07-31-001",
+    "correlationId": "33a02fd0-02e0-4df6-a309-2880a0196049",
+    "stepId": "setup-active-user"
+  },
+  "data": {
+    "capability": {
+      "id": "active-user",
+      "version": "1"
+    },
+    "identifiers": {
+      "userId": "user-001"
+    },
+    "output": {
+      "status": "active"
+    }
+  }
+}

data/protocol/testing-control/v3/openapi.yaml

@@ -0,0 +1,343 @@
+openapi: 3.1.0
+info:
+  title: Overseer testing-control protocol
+  version: '3'
+  description: |
+    Product-agnostic control contract for an isolated target backend.
+    Product applications own the advertised state, probe, and sink definitions
+    and implement this shared wire contract.
+jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
+servers:
+  - url: '{testingBaseUrl}'
+    variables:
+      testingBaseUrl:
+        default: http://127.0.0.1/testing
+        description: Loopback testing-control base URL verified by the test runner.
+security: []
+paths:
+  /capabilities:
+    get:
+      operationId: getTestingControlCapabilities
+      summary: Negotiate protocol and product-owned capabilities
+      parameters:
+        - $ref: '#/components/parameters/ProtocolVersion'
+        - $ref: '#/components/parameters/RunId'
+        - $ref: '#/components/parameters/CorrelationId'
+        - $ref: '#/components/parameters/StepId'
+      responses:
+        '200':
+          description: Compatible capabilities
+          headers:
+            Overseer-Testing-Control-Version:
+              $ref: '#/components/headers/ProtocolVersion'
+            Overseer-Correlation-Id:
+              $ref: '#/components/headers/CorrelationId'
+          content:
+            application/json:
+              schema:
+                $ref: './schema.json#/$defs/capabilitiesResponse'
+        '400':
+          $ref: '#/components/responses/InvalidRequest'
+        '409':
+          $ref: '#/components/responses/IncompatibleVersion'
+        '500':
+          $ref: '#/components/responses/InternalError'
+        '503':
+          $ref: '#/components/responses/RuntimeUnavailable'
+  /reset:
+    put:
+      operationId: resetTestingControlRuntime
+      summary: Reset the isolated runtime and clear fake-sink records
+      parameters:
+        - $ref: '#/components/parameters/ProtocolVersion'
+        - $ref: '#/components/parameters/RunId'
+        - $ref: '#/components/parameters/CorrelationId'
+        - $ref: '#/components/parameters/StepId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '200':
+          description: Reset completed
+          headers:
+            Overseer-Testing-Control-Version:
+              $ref: '#/components/headers/ProtocolVersion'
+            Overseer-Correlation-Id:
+              $ref: '#/components/headers/CorrelationId'
+          content:
+            application/json:
+              schema:
+                $ref: './schema.json#/$defs/resetResponse'
+        '400':
+          $ref: '#/components/responses/InvalidRequest'
+        '409':
+          description: Protocol is incompatible or the runtime must be restarted
+          headers:
+            Overseer-Testing-Control-Version:
+              $ref: '#/components/headers/ProtocolVersion'
+            Overseer-Correlation-Id:
+              $ref: '#/components/headers/CorrelationId'
+          content:
+            application/json:
+              schema:
+                $ref: './schema.json#/$defs/errorResponse'
+        '413':
+          $ref: '#/components/responses/PayloadTooLarge'
+        '500':
+          $ref: '#/components/responses/InternalError'
+        '503':
+          $ref: '#/components/responses/RuntimeUnavailable'
+  /states:
+    post:
+      operationId: arrangeTestingControlState
+      summary: Arrange one allowlisted product-owned precondition
+      parameters:
+        - $ref: '#/components/parameters/ProtocolVersion'
+        - $ref: '#/components/parameters/RunId'
+        - $ref: '#/components/parameters/CorrelationId'
+        - $ref: '#/components/parameters/StepId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: './schema.json#/$defs/stateRequest'
+      responses:
+        '200':
+          description: State arranged
+          headers:
+            Overseer-Testing-Control-Version:
+              $ref: '#/components/headers/ProtocolVersion'
+            Overseer-Correlation-Id:
+              $ref: '#/components/headers/CorrelationId'
+          content:
+            application/json:
+              schema:
+                $ref: './schema.json#/$defs/stateResponse'
+        '400':
+          $ref: '#/components/responses/InvalidRequest'
+        '404':
+          $ref: '#/components/responses/CapabilityNotFound'
+        '409':
+          $ref: '#/components/responses/IncompatibleVersion'
+        '413':
+          $ref: '#/components/responses/PayloadTooLarge'
+        '422':
+          $ref: '#/components/responses/ValidationFailed'
+        '500':
+          $ref: '#/components/responses/InternalError'
+        '503':
+          $ref: '#/components/responses/RuntimeUnavailable'
+  /probes:
+    post:
+      operationId: evaluateTestingControlProbe
+      summary: Evaluate one allowlisted read-only product-owned projection
+      parameters:
+        - $ref: '#/components/parameters/ProtocolVersion'
+        - $ref: '#/components/parameters/RunId'
+        - $ref: '#/components/parameters/CorrelationId'
+        - $ref: '#/components/parameters/StepId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: './schema.json#/$defs/probeRequest'
+      responses:
+        '200':
+          description: Probe evaluated
+          headers:
+            Overseer-Testing-Control-Version:
+              $ref: '#/components/headers/ProtocolVersion'
+            Overseer-Correlation-Id:
+              $ref: '#/components/headers/CorrelationId'
+          content:
+            application/json:
+              schema:
+                $ref: './schema.json#/$defs/probeResponse'
+        '400':
+          $ref: '#/components/responses/InvalidRequest'
+        '404':
+          $ref: '#/components/responses/CapabilityNotFound'
+        '409':
+          $ref: '#/components/responses/IncompatibleVersion'
+        '413':
+          $ref: '#/components/responses/PayloadTooLarge'
+        '422':
+          $ref: '#/components/responses/ValidationFailed'
+        '500':
+          $ref: '#/components/responses/InternalError'
+        '503':
+          $ref: '#/components/responses/RuntimeUnavailable'
+  /sinks/query:
+    post:
+      operationId: queryTestingControlSink
+      summary: Query bounded sanitized records from one fake sink
+      parameters:
+        - $ref: '#/components/parameters/ProtocolVersion'
+        - $ref: '#/components/parameters/RunId'
+        - $ref: '#/components/parameters/CorrelationId'
+        - $ref: '#/components/parameters/StepId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: './schema.json#/$defs/sinkQueryRequest'
+      responses:
+        '200':
+          description: Matching sanitized effect records
+          headers:
+            Overseer-Testing-Control-Version:
+              $ref: '#/components/headers/ProtocolVersion'
+            Overseer-Correlation-Id:
+              $ref: '#/components/headers/CorrelationId'
+          content:
+            application/json:
+              schema:
+                $ref: './schema.json#/$defs/sinkQueryResponse'
+        '400':
+          $ref: '#/components/responses/InvalidRequest'
+        '404':
+          $ref: '#/components/responses/CapabilityNotFound'
+        '409':
+          $ref: '#/components/responses/IncompatibleVersion'
+        '413':
+          $ref: '#/components/responses/PayloadTooLarge'
+        '422':
+          $ref: '#/components/responses/ValidationFailed'
+        '500':
+          $ref: '#/components/responses/InternalError'
+        '503':
+          $ref: '#/components/responses/RuntimeUnavailable'
+components:
+  schemas:
+    Identifier:
+      type: string
+      minLength: 1
+      maxLength: 128
+      pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
+  parameters:
+    ProtocolVersion:
+      name: Overseer-Testing-Control-Version
+      in: header
+      required: true
+      description: Exact protocol major version. Version negotiation never silently downgrades.
+      schema:
+        const: '3'
+    RunId:
+      name: Overseer-Run-Id
+      in: header
+      required: true
+      description: Opaque identifier for the current Overseer run.
+      schema:
+        $ref: '#/components/schemas/Identifier'
+    CorrelationId:
+      name: Overseer-Correlation-Id
+      in: header
+      required: true
+      description: Opaque identifier echoed in the response and propagated to effects.
+      schema:
+        $ref: '#/components/schemas/Identifier'
+    StepId:
+      name: Overseer-Step-Id
+      in: header
+      required: false
+      description: Opaque setup or public-step identifier when the call is attributable to one.
+      schema:
+        $ref: '#/components/schemas/Identifier'
+    IdempotencyKey:
+      name: Overseer-Idempotency-Key
+      in: header
+      required: false
+      description: Stable key for safely retrying reset or a state that advertises idempotency.
+      schema:
+        $ref: '#/components/schemas/Identifier'
+  headers:
+    ProtocolVersion:
+      required: true
+      description: Exact protocol major version used by the response.
+      schema:
+        const: '3'
+    CorrelationId:
+      required: true
+      description: Echo of the request correlation identifier.
+      schema:
+        $ref: '#/components/schemas/Identifier'
+  responses:
+    InvalidRequest:
+      description: Headers or request envelope are malformed
+      headers:
+        Overseer-Testing-Control-Version:
+          $ref: '#/components/headers/ProtocolVersion'
+        Overseer-Correlation-Id:
+          $ref: '#/components/headers/CorrelationId'
+      content:
+        application/json:
+          schema:
+            $ref: './schema.json#/$defs/errorResponse'
+    CapabilityNotFound:
+      description: The requested capability ID and version are not advertised
+      headers:
+        Overseer-Testing-Control-Version:
+          $ref: '#/components/headers/ProtocolVersion'
+        Overseer-Correlation-Id:
+          $ref: '#/components/headers/CorrelationId'
+      content:
+        application/json:
+          schema:
+            $ref: './schema.json#/$defs/errorResponse'
+    IncompatibleVersion:
+      description: The requested protocol version is not supported
+      headers:
+        Overseer-Testing-Control-Version:
+          $ref: '#/components/headers/ProtocolVersion'
+        Overseer-Correlation-Id:
+          $ref: '#/components/headers/CorrelationId'
+      content:
+        application/json:
+          schema:
+            $ref: './schema.json#/$defs/errorResponse'
+    PayloadTooLarge:
+      description: The request exceeds an advertised or server limit
+      headers:
+        Overseer-Testing-Control-Version:
+          $ref: '#/components/headers/ProtocolVersion'
+        Overseer-Correlation-Id:
+          $ref: '#/components/headers/CorrelationId'
+      content:
+        application/json:
+          schema:
+            $ref: './schema.json#/$defs/errorResponse'
+    ValidationFailed:
+      description: Input violates the advertised product-owned JSON Schema or a limit
+      headers:
+        Overseer-Testing-Control-Version:
+          $ref: '#/components/headers/ProtocolVersion'
+        Overseer-Correlation-Id:
+          $ref: '#/components/headers/CorrelationId'
+      content:
+        application/json:
+          schema:
+            $ref: './schema.json#/$defs/errorResponse'
+    RuntimeUnavailable:
+      description: The isolated runtime cannot currently service the request
+      headers:
+        Overseer-Testing-Control-Version:
+          $ref: '#/components/headers/ProtocolVersion'
+        Overseer-Correlation-Id:
+          $ref: '#/components/headers/CorrelationId'
+      content:
+        application/json:
+          schema:
+            $ref: './schema.json#/$defs/errorResponse'
+    InternalError:
+      description: A sanitized internal failure
+      headers:
+        Overseer-Testing-Control-Version:
+          $ref: '#/components/headers/ProtocolVersion'
+        Overseer-Correlation-Id:
+          $ref: '#/components/headers/CorrelationId'
+      content:
+        application/json:
+          schema:
+            $ref: './schema.json#/$defs/errorResponse'