@company-semantics/contracts 100.0.0 → 101.1.0

package/src/org/workspace-member-schemas.ts

@@ -0,0 +1,221 @@
+/**
+ * Workspace Member Schemas
+ *
+ * Zod schemas for the workspace member list and detail, the role catalog, and
+ * the member mutation responses (GET /api/workspace/members, DELETE/PATCH
+ * /api/workspace/members/:id). Re-exported from `./schemas`, the one import
+ * path for every org schema.
+ */
+import { z } from "zod";
+import { CursorPageSchema } from "../api/primitives";
+import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
+import { AuthorityMutabilitySchema } from "./authority-schemas";
+
+// ---------------------------------------------------------------------------
+// Sub-schemas
+// ---------------------------------------------------------------------------
+
+const WorkspaceMemberUnitSummarySchema = z.object({
+  unitId: z.string(),
+  unitName: z.string(),
+  unitPath: z.string(),
+  role: z.enum(["owner", "manager", "member"]),
+});
+
+/**
+ * Designation a member holds over a unit they manage (ADR-CTRL-112).
+ *
+ * Precedence, highest-first: whole_org > admin > unit_owner > delegate > member.
+ * The org-wide designations (`whole_org`, `admin`) anchor to the org root
+ * unit. This vocabulary is DISPLAY-ONLY — it summarizes management reach for
+ * UI surfaces and is NEVER an authorization input (authority resolution uses
+ * the orthogonal membership/delegation axes, not this enum).
+ */
+export const OrgUnitDesignationSchema = z.enum([
+  "whole_org",
+  "admin",
+  "unit_owner",
+  "delegate",
+  "member",
+]);
+export type OrgUnitDesignation = z.infer<typeof OrgUnitDesignationSchema>;
+
+export const WorkspaceMemberUnitDesignationEntrySchema = z.object({
+  unitId: z.string(),
+  unitName: z.string(),
+  designation: OrgUnitDesignationSchema,
+  /**
+   * Whether this designation is REMOVABLE in place (`user_managed` — an explicit
+   * overlay grant or `l{N}_unit_owner` membership) or DERIVED from reporting
+   * topology (`derived` — the senior person homed in a unit with no manager
+   * inside it, ADR-BE-267/294). A `derived` owner can't be revoked: the holder
+   * must relinquish it (recorded as a higher-provenance suppression that the
+   * structural projection honors) or the upstream chart must change. Display +
+   * affordance gating only; never an authorization input.
+   */
+  mutability: AuthorityMutabilitySchema,
+});
+export type WorkspaceMemberUnitDesignationEntry = z.infer<
+  typeof WorkspaceMemberUnitDesignationEntrySchema
+>;
+
+const WorkspaceMemberSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+  /**
+   * Resolved avatar photo URL for the member, or `null`/absent when none is
+   * stored. SOURCE-AGNOSTIC: today the backend resolves this from the Slack
+   * profile photo cached on the user record, but the field name deliberately
+   * does not encode the origin so future sources (in-app upload, etc.) slot in
+   * behind the backend avatar resolver without a contract change. UI MUST fall
+   * back to initials when this is absent. Optional because it is an additive
+   * display-only enrichment (see ADR-CONTRACTS-055).
+   */
+  avatarUrl: z.string().nullable().optional(),
+  /** The occupant's Position seat title (org-scoped). Null when the seat is untitled. */
+  jobTitle: z.string().nullable(),
+  /**
+   * The member's Position seat in the org graph — the id every reporting write
+   * is keyed on (ADR-CONTRACTS-131). Present here so a user-ADDRESSED surface
+   * (the members table, a person picker) can resolve a seat by READ and hand
+   * the position straight to `PUT /api/reporting/positions/{positionId}/manager`,
+   * instead of a write path minting one with `resolveSeat(create: true)`.
+   *
+   * Nullable: a member with no materialized seat is a legitimate state, and a
+   * read must report that honestly rather than force the server to create one.
+   */
+  seatPositionId: z.string().uuid().nullable(),
+  /**
+   * Display role — the member's highest org-chart standing, or `null` for a
+   * plain member with no org-chart authority. Render via `orgChartRoleLabel`.
+   */
+  role: OrgChartRoleSchema.nullable(),
+  /** Raw RBAC role names (e.g. 'owner', 'admin', 'delegate'). Superset of `role`. */
+  roleNames: z.array(z.string()),
+  joinedAt: z.string(),
+  /** ISO timestamp of last activity; null if never recorded. */
+  lastActiveAt: z.string().nullable(),
+  /**
+   * Home org-unit (`users.primary_unit_id`). Null for org-scoped users
+   * (no level-2 home assignment). Used by the unit-detail Members table to
+   * roll up "people in this org-unit" across the subtree.
+   */
+  primaryUnitId: z.string().uuid().nullable(),
+  /** OrgUnit memberships for this member, capped at a small number server-side. */
+  unitMemberships: z.array(WorkspaceMemberUnitSummarySchema),
+  /**
+   * Per-unit org-chart designations the member holds (ADR-CTRL-112). Carries
+   * BOTH management-reach entries (whole_org/admin/unit_owner/delegate) and
+   * plain contributor entries (`member`); consumers split by designation.
+   * Display-only summary; never an authorization input. Empty array when the
+   * member holds no per-unit designation.
+   */
+  unitDesignations: z.array(WorkspaceMemberUnitDesignationEntrySchema),
+  /** True when server truncated `unitMemberships`; detail endpoint returns the full list. */
+  unitMembershipsTruncated: z.boolean(),
+  /** Invite lifecycle status. `null` for members without an invite record. */
+  inviteStatus: z.enum(["active", "pending", "expired"]).nullable(),
+});
+
+const MemberRecentActionSchema = z.object({
+  id: z.string(),
+  timestamp: z.string(),
+  action: z.string(),
+  summary: z.string(),
+});
+
+/**
+ * Which bundle or role contributed a resolved scope (ADR-CTRL-360).
+ *
+ * `member_default` / `admin` / `account_owner` are the static actor-class
+ * bundles AUTH-011C re-homed the deleted role scope lists onto (ADR-BE-184);
+ * `role:<name>` is a surviving RBAC role assignment. Open string rather than an
+ * enum because `rbac_roles` is data, not a closed vocabulary.
+ *
+ * A scope carries EVERY band that granted it — composition is a union, not a
+ * ladder, so an owner who also holds admin authority legitimately shows both.
+ * Display/audit only; `effectiveScopes` remains the authorization surface.
+ */
+const ScopeProvenanceEntrySchema = z.object({
+  scope: z.string(),
+  bands: z.array(z.string()).min(1),
+});
+
+export const WorkspaceMemberDetailSchema = WorkspaceMemberSchema.extend({
+  effectiveScopes: z.array(z.string()),
+  /**
+   * Per-scope provenance for {@link WorkspaceMemberDetailSchema.shape.effectiveScopes}.
+   * Optional: absence means the server did not compute it (legacy callsite, or a
+   * non-user actor), never that the scopes were granted by nothing.
+   */
+  scopeProvenance: z.array(ScopeProvenanceEntrySchema).optional(),
+  recentActions: z.array(MemberRecentActionSchema),
+});
+
+/**
+ * Workspace member for the members list. Human users only (no agent actors).
+ * Canonical type — inferred from {@link WorkspaceMemberSchema} so the runtime
+ * schema is the single source of truth (no parallel hand-written interface).
+ */
+export type WorkspaceMember = z.infer<typeof WorkspaceMemberSchema>;
+
+/**
+ * Full member detail (GET /api/workspace/members/:userId and /api/me self-view).
+ * Inferred from {@link WorkspaceMemberDetailSchema}.
+ */
+export type WorkspaceMemberDetail = z.infer<typeof WorkspaceMemberDetailSchema>;
+
+export const RoleCatalogEntrySchema = z.object({
+  name: z.string(),
+  type: z.enum(["system", "custom"]),
+  description: z.string(),
+  scopes: z.array(z.string()),
+  memberCount: z.number().int().nonnegative(),
+});
+
+export const RoleCatalogResponseSchema = z.object({
+  roles: z.array(RoleCatalogEntrySchema),
+});
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/members
+// ---------------------------------------------------------------------------
+
+export const WorkspaceMembersResponseSchema = CursorPageSchema(
+  WorkspaceMemberSchema,
+);
+
+export type WorkspaceMembersResponse = z.infer<
+  typeof WorkspaceMembersResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// DELETE /api/workspace/members/:id
+// ---------------------------------------------------------------------------
+
+export const RemoveMemberResponseSchema = z.object({
+  success: z.boolean(),
+  memberId: z.string(),
+  memberEmail: z.string(),
+  message: z.string(),
+});
+
+export type RemoveMemberResponse = z.infer<typeof RemoveMemberResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// PATCH /api/workspace/members/:id/role
+// ---------------------------------------------------------------------------
+
+export const ChangeMemberRoleResponseSchema = z.object({
+  success: z.boolean(),
+  memberId: z.string(),
+  memberEmail: z.string(),
+  previousRole: z.string(),
+  newRole: z.string(),
+  message: z.string(),
+});
+
+export type ChangeMemberRoleResponse = z.infer<
+  typeof ChangeMemberRoleResponseSchema
+>;

package/src/org/workspace-overview-schemas.ts

@@ -0,0 +1,92 @@
+/**
+ * Workspace Overview Schemas
+ *
+ * Zod schemas for GET /api/workspace (the overview, its marks and owner icon)
+ * and GET /api/workspace/access. Re-exported from `./schemas`, the one import
+ * path for every org schema.
+ */
+import { z } from "zod";
+
+const WorkspaceOwnerSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+});
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/access
+// ---------------------------------------------------------------------------
+
+export const WorkspaceAccessResponseSchema = z.object({
+  hasAccess: z.boolean(),
+});
+
+export type WorkspaceAccessResponse = z.infer<
+  typeof WorkspaceAccessResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace
+// PATCH /api/workspace/name (returns WorkspaceOverview)
+// ---------------------------------------------------------------------------
+
+/**
+ * Icon options for the `owner` org-chart role (ADR-CONT-070). Selected
+ * alongside the owner title in the Organization structure editor; `crown` is
+ * the default. Presentation only — never an authorization input.
+ */
+export const OrgOwnerIconSchema = z.enum([
+  "crown",
+  "crown-cross",
+  "person-simple-run",
+  "person",
+  "medal-military",
+  "dog",
+  "cat",
+  "steering-wheel",
+]);
+
+/**
+ * An org's stored marks. See `OrgLogos` for what each slot means and
+ * `resolveOrgMark` for the order the square tile prefers them in.
+ */
+export const OrgLogosSchema = z.object({
+  appLogoUrl: z.string().nullable(),
+  logoUrl: z.string().nullable(),
+});
+
+export type OrgLogosShape = z.infer<typeof OrgLogosSchema>;
+
+export const WorkspaceOverviewSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  type: z.enum(["personal", "shared"]),
+  /**
+   * The org's two marks. See `OrgLogos` for what each slot means and
+   * `resolveOrgMark` for the order the square tile prefers them in.
+   */
+  logos: OrgLogosSchema,
+  owner: WorkspaceOwnerSchema,
+  /**
+   * Org-configured display title for the `owner` org-chart role
+   * (ADR-CONTRACTS-061). Server-resolved: `orgs.owner_title` when set,
+   * otherwise the default "CEO". Always present; pass to
+   * `orgChartRoleLabel(role, { ownerTitle })` wherever the owner badge or
+   * section heading renders. Presentation only — never an authorization input.
+   */
+  ownerTitle: z.string(),
+  /**
+   * Org-configured icon for the `owner` org-chart role (ADR-CONT-070).
+   * Server-resolved: `orgs.owner_icon` when set, otherwise the default
+   * "crown". Always present. Presentation only — never an authorization input.
+   */
+  ownerIcon: OrgOwnerIconSchema,
+  createdAt: z.string(),
+  memberCount: z.number(),
+  claimable: z.boolean(),
+});
+
+export type OrgOwnerIcon = z.infer<typeof OrgOwnerIconSchema>;
+
+export type WorkspaceOverview = z.infer<typeof WorkspaceOverviewSchema>;

package/src/root-exports/README.md

@@ -18,6 +18,7 @@ guard's thresholds; `src/index.ts` re-exports every slice here with
 | `org-structure.ts` | sync runs, conflicts, reconciliation, structure findings, transformations, canonical facts, inference, authority |
 | `agent-runtime.ts` | MCP tool discovery, message parts, execution kinds, Ralph, internal admin, rate limits                           |
 | `platform.ts`      | impersonation, usage telemetry, resource keys, errors, the generated OpenAPI surface, security, request tiers    |
+| `ci-governance.ts` | guard results and config, SOC 2 compliance, cross-repo CI aggregation, the compatibility manifest                |
 
 ## Invariants
 
@@ -52,10 +53,13 @@ documented in its owning domain (`src/org/`, `src/chat/`, `src/comments/`, …).
 - `api`
 - `autotune`
 - `chat`
+- `ci-results`
 - `comments`
+- `compatibility`
 - `errors`
 - `execution`
 - `generated`
+- `guards`
 - `impersonation`
 - `impersonation-events`
 - `internal-admin`

package/src/root-exports/ci-governance.ts

@@ -0,0 +1,73 @@
+/**
+ * Package root exports — CI governance
+ *
+ * Guard result and configuration vocabulary, SOC 2 compliance types, cross-repo
+ * CI aggregation, and the compatibility manifest.
+ *
+ * A slice of the `@company-semantics/contracts` root entry, moved here verbatim
+ * from `src/index.ts`, which re-exports it with `export *`. Each list is the
+ * exact subset of its domain the root exposes. Import from the package root,
+ * never from this file.
+ */
+
+// Guard types (CI guard vocabulary)
+// @see schemas/guard-result.schema.json for JSON Schema
+export type {
+  GuardMessage,
+  GuardTierResult,
+  GuardTier,
+  GuardResults,
+  CheckResult,
+  GuardOutput,
+  RoleLimit,
+  GuardConfig,
+  GuardCheck,
+  GuardCheckFactory,
+  BoundGuardCheck,
+  GuardCheckRegistry,
+  StructuralBaselines,
+  ScriptsDepsBaseline,
+  EvolutionBaselines,
+  ContractsFreshnessBaseline,
+  MetaBaselines,
+  // Aggregate evolution types
+  DomainAggregateBaseline,
+  AggregateEvolutionConfig,
+  // SOC 2 Compliance types
+  Soc2ControlArea,
+  Soc2ControlStatus,
+  Soc2ControlResult,
+  Soc2ComplianceOutput,
+  // SOC 2 Guard Configuration types
+  SecretsDetectionConfig,
+  StructuredLoggingConfig,
+  AlertsConfigGuardConfig,
+  BackupConfigGuardConfig,
+  Soc2Baselines,
+} from "../guards/index";
+
+export {
+  GUARD_SCHEMA_VERSION,
+  GUARD_TIERS,
+  DEFAULT_SKIP_DIRECTORIES,
+  DEFAULT_DOMAIN_SECTIONS,
+  DEFAULT_INFRA_SECTIONS,
+  // SOC 2 Compliance constants
+  SOC2_CONTROL_NAMES,
+  REQUIRED_SOC2_CONTROLS,
+  BLOCKING_SOC2_CONTROLS,
+  SOC2_SCHEMA_VERSION,
+} from "../guards/index";
+
+// Cross-repo CI aggregation vocabulary
+// @see ADR-CONT-033 for contracts boundary rationale
+// Note: GuardTier is already exported above from './guards/index' (structurally
+// identical); not re-exported here to avoid a duplicate-identifier collision.
+export type { GuardResultPayload, RepoCiResult } from "../ci-results/index";
+
+export { assertRepoCiResultConsistent } from "../ci-results/index";
+
+// Compatibility manifest (CI guard vocabulary)
+// @see ADR-2025-12-011 for design rationale
+export { COMPATIBILITY } from "../compatibility";
+export type { Compatibility, Deprecation } from "../compatibility";

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

package/src/source-sync/README.md

@@ -92,9 +92,17 @@ way. This directory holds that shared spelling.
   A named person's pre-authorized instruction to keep one scope current, with
   an auto-apply ceiling of `none` or `low` — there is deliberately no higher
   member — a monthly spend cap in integer micro-USD and, when suspended, a
-  closed reason. The request that sets one is strict and carries no grantor:
-  the grantor is the authenticated caller, and the row's grantor label is
-  display-only.
+  closed reason (`SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS`, including
+  `grantor_lost_doc_access`: the grantor kept the authority but lost upload and
+  edit access on the scope's document). The request that sets one is strict
+  and carries no grantor: the grantor is the authenticated caller, and the
+  row's grantor label is display-only. The list carries the caller's
+  grantability per scope (required); granting uses the same rule, and the same
+  blocked-reason vocabulary, as approving a scope.
+- **One blocked-reason vocabulary.** Why the caller may not approve a scope or
+  grant its standing order: `needs_approval_authority` (no approval authority —
+  an org admin coordinates and never approves) or `needs_doc_access`. Authority
+  is checked first, so a caller lacking both reads `needs_approval_authority`.
 - **Drive reach names no credential and no person.** The reach status and the
   confirmed upgrade carry no key material, no delegated identity and no
   address; `hostedDomain` is a Workspace domain, and who changed reach is an
@@ -273,6 +281,9 @@ in `attention-evidence.ts`.
   `pending`, `approved` or `rejected` (no verb writes `rejected` yet).
 - `SOURCE_SYNC_SCOPE_APPROVER_KINDS` / `SourceSyncScopeApproverKind` —
   `org_admin` or `unit_head`.
+- `SOURCE_SYNC_SCOPE_BLOCKED_REASONS` / `SourceSyncScopeBlockedReason` — why
+  the caller may not approve a scope or grant its standing order:
+  `needs_approval_authority` (checked first) or `needs_doc_access`.
 - `DOCUMENT_TYPES` / `DocumentType` / `KnownDocumentType` — what a source is,
   structurally; `KnownDocumentType` excludes `unknown` (see Document type).
 - `OPERATING_KNOWLEDGE_FAMILIES` / `OperatingKnowledgeFamily` — what kind of
@@ -369,8 +380,17 @@ in `attention-evidence.ts`.
 - `SourceSyncStandingOrderSchema` / `SourceSyncStandingOrder` — one standing
   order: scope, state, ceiling, monthly spend cap, grantor label, when granted
   and, if suspended, why.
+- `SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS` /
+  `SourceSyncStandingOrderSuspendedReason` — why an order stopped acting:
+  `grantor_lost_authority`, `grantor_lost_doc_access`, `spend_cap_reached` or
+  `connection_lost`.
+- `SourceSyncStandingOrderGrantabilitySchema` /
+  `SourceSyncStandingOrderGrantability` — whether the caller may grant one
+  scope's order; `blockedReason` (from `SOURCE_SYNC_SCOPE_BLOCKED_REASONS`) is
+  non-null exactly when it is not grantable. Advisory: the grant re-decides.
 - `SourceSyncStandingOrdersResponseSchema` /
-  `SourceSyncStandingOrdersResponse` — the org's standing orders.
+  `SourceSyncStandingOrdersResponse` — the org's standing orders and the
+  caller's required `grantability`.
 - `SourceSyncPutStandingOrderRequestSchema` /
   `SourceSyncPutStandingOrderRequest` — set a scope's order: the ceiling and
   the spend cap, nothing else.
@@ -394,7 +414,8 @@ in `attention-evidence.ts`.
 - `../api/primitives` — the pinned `IsoDateTime`.
 
 `rules.ts` imports only `zod`, `../api/primitives` and `./vocabulary`.
-`upkeep.ts` and `reach.ts` import only `zod` and `../api/primitives`.
+`upkeep.ts` imports only `zod`, `../api/primitives` and `./vocabulary`.
+`reach.ts` imports only `zod` and `../api/primitives`.
 `candidate-item.ts` imports only `zod`, `../api/primitives`, `./vocabulary`,
 `./relevance` and `./attention-evidence`.
 `relevance.ts` imports only `zod` and `./enumeration`.