@company-semantics/contracts 101.0.0 → 101.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "101.0.0",
+  "version": "101.1.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/schedules/README.md

@@ -23,6 +23,8 @@ ledger and reconciles) can never disagree about a slot.
   `contentHash` is computed over.
 - Response schemas only; request bodies live in the backend beside their routes
   (ScheduleTickRequest is a type, not a schema).
+- A re-prove grants exactly one extra attempt for a named execution; the route
+  only grants, the backend clock dispatches.
 - Pure: no clock reads, no I/O, only `zod`.
 
 ## Dependencies
@@ -64,6 +66,9 @@ ledger and reconciles) can never disagree about a slot.
 - `SCHEDULE_MODES` — off: GitHub cron only, clock ignores it. shadow: clock plans, never dispatches. live: clock dispatches…
 - `SCHEDULE_OUTPUT_VERIFIERS` — Closed catalog. v0 has one verifier.
 - `SCHEDULE_REGISTRY_SCHEMA_VERSION`
+- `SCHEDULE_REPROVE_PATH` — The operator re-prove route (control ADR slug operator-schedule-reprove).
+- `SCHEDULE_REPROVE_REASON_MAX_LENGTH` — Upper bound of a re-prove reason (operator prose, kept for audit only).
+- `SCHEDULE_REPROVE_REFUSALS` — Why a re-prove was refused.
 - `SCHEDULE_RUN_CONCLUSIONS`
 - `SCHEDULE_RUN_NAME` — The exact `run-name:` a registered workflow declares, so displaytitle = executionid#attempt.
 - `SCHEDULE_SEVERITIES`
@@ -91,6 +96,10 @@ ledger and reconciles) can never disagree about a slot.
 - `ScheduleOutputVerifier` _(type)_
 - `ScheduleRegistrySnapshot` _(type)_
 - `ScheduleRegistrySnapshotSchema`
+- `ScheduleReproveRefusal` _(type)_
+- `ScheduleReproveRequest` _(type)_ — Re-prove request body, as a TYPE only: the backend binds its zod schema to it with `satisfies…
+- `ScheduleReproveResponse` _(type)_
+- `ScheduleReproveResponseSchema` — `granted`: the clock will dispatch `<executionId>#<grantedAttempt>` on its next pass.
 - `ScheduleRunConclusion` _(type)_
 - `ScheduleSeverity` _(type)_
 - `ScheduleTickRequest` _(type)_ — Tick request body, as a TYPE only: request schemas stay in the backend beside the route (contracts…

package/src/schedules/__tests__/api.test.ts

@@ -5,9 +5,12 @@ import {
   SCHEDULE_METRIC_TICK,
   SCHEDULE_METRIC_TICK_SOURCE_DIMENSION,
   SCHEDULE_METRIC_ENVIRONMENT_DIMENSION,
+  SCHEDULE_REPROVE_PATH,
+  SCHEDULE_REPROVE_REFUSALS,
   SCHEDULE_TICK_PATH,
   ScheduleClaimResponseSchema,
   ScheduleFinishResponseSchema,
+  ScheduleReproveResponseSchema,
   ScheduleTickResponseSchema,
 } from "../api";
 
@@ -69,4 +72,52 @@ describe("schedules api responses", () => {
       "environment",
     ]);
   });
+
+  it("grants a re-prove for a named attempt", () => {
+    expect(SCHEDULE_REPROVE_PATH).toBe("/api/schedules/executions/reprove");
+    expect(
+      ScheduleReproveResponseSchema.safeParse({
+        outcome: "granted",
+        executionId: "control-pin-audit/2026-10-12T15:00:00Z",
+        grantedAttempt: 4,
+        incidentKey:
+          "schedule:execution:control-pin-audit/2026-10-12T15:00:00Z",
+        incidentNoted: true,
+      }).success,
+    ).toBe(true);
+    expect(
+      ScheduleReproveResponseSchema.safeParse({
+        outcome: "granted",
+        executionId: "control-pin-audit/2026-10-12T15:00:00Z",
+        grantedAttempt: 1,
+        incidentKey: null,
+        incidentNoted: false,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a re-prove with a closed reason", () => {
+    expect(SCHEDULE_REPROVE_REFUSALS).toEqual([
+      "unknown_execution",
+      "schedule_not_live",
+      "not_exhausted",
+      "not_reprovable",
+      "schedule_busy",
+      "grant_lost",
+    ]);
+    expect(
+      ScheduleReproveResponseSchema.safeParse({
+        outcome: "refused",
+        executionId: "x/2026-10-12T15:00:00Z",
+        refusal: "not_exhausted",
+      }).success,
+    ).toBe(true);
+    expect(
+      ScheduleReproveResponseSchema.safeParse({
+        outcome: "refused",
+        executionId: "x/2026-10-12T15:00:00Z",
+        refusal: "because",
+      }).success,
+    ).toBe(false);
+  });
 });

package/src/schedules/__tests__/schedules-exports.test.ts

@@ -19,6 +19,9 @@ describe("schedules exports", () => {
       "ScheduleClaimResponseSchema",
       "SCHEDULE_TICK_PATH",
       "SCHEDULE_METRICS_NAMESPACE",
+      "SCHEDULE_REPROVE_PATH",
+      "SCHEDULE_REPROVE_REFUSALS",
+      "ScheduleReproveResponseSchema",
     ]) {
       expect(root).toHaveProperty(name);
     }

package/src/schedules/api.ts

@@ -137,3 +137,76 @@ export const ScheduleTickResponseSchema = z
   })
   .strict();
 export type ScheduleTickResponse = z.infer<typeof ScheduleTickResponseSchema>;
+
+/**
+ * The operator re-prove route (control ADR slug operator-schedule-reprove).
+ * Its only caller is control's schedules-reprove.yml on main, authenticated by
+ * that job's GitHub OIDC token; an operator starts the workflow with
+ * `pnpm schedules:reprove <scheduleId> <slot> --reason "…"`. The route only
+ * GRANTS one extra attempt for a named execution; the backend clock dispatches
+ * it through the normal claim-before-call path.
+ */
+export const SCHEDULE_REPROVE_PATH = "/api/schedules/executions/reprove";
+
+/** Upper bound of a re-prove reason (operator prose, kept for audit only). */
+export const SCHEDULE_REPROVE_REASON_MAX_LENGTH = 500;
+
+/**
+ * Re-prove request body, as a TYPE only: the backend binds its zod schema to it
+ * with `satisfies z.ZodType<ScheduleReproveRequest>`. `executionId` names the
+ * exhausted slot (`<schedule_id>/<slot>`); `reason` (1..500 chars) says why the
+ * operator believes the cause is fixed.
+ */
+export interface ScheduleReproveRequest {
+  readonly executionId: string;
+  readonly reason: string;
+}
+
+/**
+ * Why a re-prove was refused. Closed.
+ * - unknown_execution: no ledger row for that execution id.
+ * - schedule_not_live: not in the active registry, or its mode is not live.
+ * - not_exhausted: the clock still owns the slot (attempts remain and effects
+ *   allow re-execution, a grant is unspent, or admission has not timed out).
+ * - not_reprovable: succeeded, settled, due, started, or failed only its
+ *   output verification.
+ * - schedule_busy: another execution of the same schedule is in flight.
+ * - grant_lost: a concurrent grant or dispatch changed the row first.
+ */
+export const SCHEDULE_REPROVE_REFUSALS = [
+  "unknown_execution",
+  "schedule_not_live",
+  "not_exhausted",
+  "not_reprovable",
+  "schedule_busy",
+  "grant_lost",
+] as const;
+export type ScheduleReproveRefusal = (typeof SCHEDULE_REPROVE_REFUSALS)[number];
+
+/**
+ * `granted`: the clock will dispatch `<executionId>#<grantedAttempt>` on its
+ * next pass. `incidentKey` is the open execution/admission incident naming the
+ * slot (null when none); `incidentNoted` says whether the grant was commented
+ * on its issue (a failed comment never revokes the grant).
+ */
+export const ScheduleReproveResponseSchema = z.discriminatedUnion("outcome", [
+  z
+    .object({
+      outcome: z.literal("granted"),
+      executionId: z.string(),
+      grantedAttempt: z.number().int().min(2),
+      incidentKey: z.string().nullable(),
+      incidentNoted: z.boolean(),
+    })
+    .strict(),
+  z
+    .object({
+      outcome: z.literal("refused"),
+      executionId: z.string(),
+      refusal: z.enum(SCHEDULE_REPROVE_REFUSALS),
+    })
+    .strict(),
+]);
+export type ScheduleReproveResponse = z.infer<
+  typeof ScheduleReproveResponseSchema
+>;

package/src/schedules/index.ts

@@ -108,6 +108,10 @@ export {
   ScheduleFinishResponseSchema,
   ScheduleTickResponseSchema,
   SCHEDULE_TICK_PATH,
+  SCHEDULE_REPROVE_PATH,
+  SCHEDULE_REPROVE_REASON_MAX_LENGTH,
+  SCHEDULE_REPROVE_REFUSALS,
+  ScheduleReproveResponseSchema,
   SCHEDULE_METRICS_NAMESPACE,
   SCHEDULE_METRIC_TICK,
   SCHEDULE_METRIC_TICK_SOURCE_DIMENSION,
@@ -121,4 +125,7 @@ export type {
   ScheduleFinishResponse,
   ScheduleTickResponse,
   ScheduleTickRequest,
+  ScheduleReproveRequest,
+  ScheduleReproveRefusal,
+  ScheduleReproveResponse,
 } from "./api";