@company-semantics/contracts 100.0.0 → 101.0.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/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`.

package/src/source-sync/__tests__/README.md

@@ -37,8 +37,10 @@ Locks the closed Source Sync vocabularies.
 - `upkeep.test.ts` — locks staleness findings and standing orders: the six
   finding kinds, the open/resolved/dismissed lifecycle, a required-but-nullable
   dismissal, a ceiling of `none` or `low` and nothing higher, a suspended order
-  that says why, and a strict standing-order request that may not name its own
-  grantor.
+  that says why (including `grantor_lost_doc_access`), a strict standing-order
+  request that may not name its own grantor, grantability whose blocked reason
+  is non-null exactly when a scope is not grantable, and a list that always
+  carries the caller's grantability.
 - `reach.test.ts` — locks the Drive-reach wire: reach is user or domain, the
   probe may be unknown, `lastChange: null` parses while an absent key does
   not, an upgrade is exactly `{ confirm: true }`, the upgrade response is the

package/src/source-sync/__tests__/barrel.test.ts

@@ -70,6 +70,8 @@ import type {
   SourceSyncReachUpgradeRequest,
   SourceSyncReachUpgradeResponse,
   SourceSyncStandingOrder,
+  SourceSyncStandingOrderGrantability,
+  SourceSyncStandingOrderSuspendedReason,
   SourceSyncStandingOrdersResponse,
 } from "../../index";
 import * as attentionEvidence from "../attention-evidence";
@@ -162,7 +164,9 @@ const RELEASE_D_RUNTIME_NAMES: ReadonlyArray<
   ["SourceSyncFindingsResponseSchema", upkeep],
   ["SourceSyncDismissFindingRequestSchema", upkeep],
   ["SOURCE_SYNC_AUTO_APPLY_CEILINGS", upkeep],
+  ["SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS", upkeep],
   ["SourceSyncStandingOrderSchema", upkeep],
+  ["SourceSyncStandingOrderGrantabilitySchema", upkeep],
   ["SourceSyncStandingOrdersResponseSchema", upkeep],
   ["SourceSyncPutStandingOrderRequestSchema", upkeep],
   ["SOURCE_SYNC_REACHES", reach],
@@ -180,7 +184,9 @@ type ReleaseDTypes = [
   SourceSyncFindingsResponse,
   SourceSyncDismissFindingRequest,
   SourceSyncAutoApplyCeiling,
+  SourceSyncStandingOrderSuspendedReason,
   SourceSyncStandingOrder,
+  SourceSyncStandingOrderGrantability,
   SourceSyncStandingOrdersResponse,
   SourceSyncPutStandingOrderRequest,
   SourceSyncReach,
@@ -197,7 +203,9 @@ const RELEASE_D_TYPE_NAMES = [
   "SourceSyncFindingsResponse",
   "SourceSyncDismissFindingRequest",
   "SourceSyncAutoApplyCeiling",
+  "SourceSyncStandingOrderSuspendedReason",
   "SourceSyncStandingOrder",
+  "SourceSyncStandingOrderGrantability",
   "SourceSyncStandingOrdersResponse",
   "SourceSyncPutStandingOrderRequest",
   "SourceSyncReach",

package/src/source-sync/__tests__/scope-projection.test.ts

@@ -110,6 +110,14 @@ describe("approvable and blockedReason", () => {
     expect(parsed.success).toBe(true);
   });
 
+  it("a projection may say the caller lacks approval authority", () => {
+    expect(
+      SourceSyncScopeApprovalProjectionSchema.safeParse(
+        scope({ approvable: false, blockedReason: "needs_approval_authority" }),
+      ).success,
+    ).toBe(true);
+  });
+
   it("refuses a reason outside the vocabulary and a missing approvable", () => {
     expect(
       SourceSyncScopeApprovalProjectionSchema.safeParse(

package/src/source-sync/__tests__/upkeep.test.ts

@@ -8,14 +8,20 @@
  * - A standing order's auto-apply ceiling is none or low; nothing higher parses.
  * - A standing-order request is strict: it may not name a grantor, a user or
  *   an actor, because the grantor is the authenticated caller.
- * - A suspended order says why, from a closed set.
+ * - A suspended order says why, from a closed set that includes the grantor
+ *   losing access to the scope's document.
  * - Money is an integer micro-USD string.
+ * - Grantability names a blocked reason exactly when a scope is not grantable,
+ *   from the scope blocked-reason vocabulary.
+ * - The standing-orders list always carries the caller's grantability.
  */
 
 import { describe, expect, it } from "vitest";
 import {
   SOURCE_SYNC_AUTO_APPLY_CEILINGS,
   SOURCE_SYNC_FINDING_KINDS,
+  SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS,
+  SourceSyncStandingOrderGrantabilitySchema,
   SourceSyncDismissFindingRequestSchema,
   SourceSyncFindingSchema,
   SourceSyncFindingsResponseSchema,
@@ -198,9 +204,94 @@ describe("standing orders", () => {
         ).success,
       ).toBe(false);
     }
+    expect(
+      SourceSyncStandingOrdersResponseSchema.safeParse({
+        orders: [order()],
+        grantability: [],
+      }).success,
+    ).toBe(true);
+  });
+
+  it("a suspended order may say its grantor lost access to the document", () => {
+    expect([...SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS]).toEqual([
+      "grantor_lost_authority",
+      "grantor_lost_doc_access",
+      "spend_cap_reached",
+      "connection_lost",
+    ]);
+    expect(
+      SourceSyncStandingOrderSchema.safeParse(
+        order({
+          state: "suspended",
+          suspendedReason: "grantor_lost_doc_access",
+        }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("grantability names why a scope cannot be granted", () => {
+    for (const blockedReason of [
+      "needs_approval_authority",
+      "needs_doc_access",
+    ]) {
+      expect(
+        SourceSyncStandingOrderGrantabilitySchema.safeParse({
+          scopeKey: "company",
+          grantable: false,
+          blockedReason,
+        }).success,
+        blockedReason,
+      ).toBe(true);
+    }
+    expect(
+      SourceSyncStandingOrderGrantabilitySchema.safeParse({
+        scopeKey: "company",
+        grantable: false,
+        blockedReason: null,
+      }).success,
+    ).toBe(false);
+    expect(
+      SourceSyncStandingOrderGrantabilitySchema.safeParse({
+        scopeKey: "company",
+        grantable: false,
+        blockedReason: "felt_like_it",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("a grantable scope carries no blocked reason", () => {
+    expect(
+      SourceSyncStandingOrderGrantabilitySchema.safeParse({
+        scopeKey: "company",
+        grantable: true,
+        blockedReason: null,
+      }).success,
+    ).toBe(true);
+    expect(
+      SourceSyncStandingOrderGrantabilitySchema.safeParse({
+        scopeKey: "company",
+        grantable: true,
+        blockedReason: "needs_doc_access",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("the standing-orders list carries the caller's grantability", () => {
     expect(
       SourceSyncStandingOrdersResponseSchema.safeParse({ orders: [order()] })
         .success,
+    ).toBe(false);
+    expect(
+      SourceSyncStandingOrdersResponseSchema.safeParse({
+        orders: [order()],
+        grantability: [
+          {
+            scopeKey: "company",
+            grantable: false,
+            blockedReason: "needs_approval_authority",
+          },
+        ],
+      }).success,
     ).toBe(true);
   });
 });

package/src/source-sync/index.ts

@@ -192,7 +192,9 @@ export type {
   SourceSyncFindingsResponse,
   SourceSyncDismissFindingRequest,
   SourceSyncAutoApplyCeiling,
+  SourceSyncStandingOrderSuspendedReason,
   SourceSyncStandingOrder,
+  SourceSyncStandingOrderGrantability,
   SourceSyncStandingOrdersResponse,
   SourceSyncPutStandingOrderRequest,
 } from "./upkeep";
@@ -203,7 +205,9 @@ export {
   SourceSyncFindingsResponseSchema,
   SourceSyncDismissFindingRequestSchema,
   SOURCE_SYNC_AUTO_APPLY_CEILINGS,
+  SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS,
   SourceSyncStandingOrderSchema,
+  SourceSyncStandingOrderGrantabilitySchema,
   SourceSyncStandingOrdersResponseSchema,
   SourceSyncPutStandingOrderRequestSchema,
 } from "./upkeep";