@company-semantics/contracts 99.2.0 → 100.0.0

package/package.json

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

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'bdfe41ff343f' as const;
-export const SPEC_HASH_FULL = 'bdfe41ff343f7f914f93bf62144b67f3f1ff2f0cd2c53e6bb0727dff96eb543b' as const;
+export const SPEC_HASH = '7e0143b235a3' as const;
+export const SPEC_HASH_FULL = '7e0143b235a3cc79cc020305bc8e4cf82c7784774cff280504fe70c0e9ee9a81' as const;

package/src/api/generated.ts

@@ -3026,7 +3026,7 @@ export interface paths {
         get?: never;
         /**
          * Upload (replace) a user's avatar photo from an image file
-         * @description Accepts a multipart image upload (PNG/JPEG/WebP/HEIC) up to 5 MB. The caller must be the target user or hold org.manage_users. HEIC/HEIF is converted to JPEG and the bytes are re-hosted via the blob store. Returns the resolved avatar.
+         * @description Accepts a multipart image upload (PNG/JPEG/WEBP/GIF/HEIC/HEIF) up to 5 MB. The caller must be the target user or hold org.manage_users. HEIC/HEIF is converted to JPEG (GIF to its first frame as PNG) and the bytes are re-hosted via the blob store. Returns the resolved avatar.
          */
         put: operations["uploadUserAvatar"];
         post?: never;
@@ -3050,7 +3050,7 @@ export interface paths {
         get?: never;
         /**
          * Upload (replace) one of the org's two marks from an image file
-         * @description Accepts a multipart image upload (PNG/JPEG/WebP/HEIC) up to 5 MB. Requires org.settings.write. HEIC/HEIF is converted to JPEG and the bytes are re-hosted via the blob store, never hot-linked. The slot to write: `app_logo` (the square mark, also the slot the Slack workspace icon fills) or `logo` (the wordmark, which is upload-only). Returns both slots as signed URLs.
+         * @description Accepts a multipart image upload (PNG/JPEG/WEBP/GIF/HEIC/HEIF) up to 5 MB. Requires org.settings.write. HEIC/HEIF is converted to JPEG (GIF to its first frame as PNG) and the bytes are re-hosted via the blob store, never hot-linked. The slot to write: `app_logo` (the square mark, also the slot the Slack workspace icon fills) or `logo` (the wordmark, which is upload-only). Returns both slots as signed URLs.
          */
         put: operations["uploadOrgLogo"];
         post?: never;
@@ -4116,6 +4116,57 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/schedules/tick": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Run one schedule clock pass for the edge tick source */
+        post: operations["scheduleTick"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/schedules/executions/start": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Claim a scheduled execution (or admit a legacy run) for the calling workflow's run */
+        post: operations["scheduleExecutionStart"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/schedules/executions/finish": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Report a claimed execution's conclusion, fenced by its claim epoch */
+        post: operations["scheduleExecutionFinish"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/internal-admin/impersonate/start": {
         parameters: {
             query?: never;
@@ -7418,10 +7469,11 @@ export interface components {
                 /** @enum {string} */
                 kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
                 /** @enum {string} */
-                reason: "updates_ready" | "updates_applied" | "stopped_by_user" | "paused_billing" | "run_ceiling_reached" | "pricing_unconfigured" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                reason: "updates_ready" | "updates_ready_partial" | "updates_applied" | "stopped_by_user" | "paused_billing" | "run_ceiling_reached" | "pricing_unconfigured" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
                 facts: {
                     scopeCount: number;
                     violationCount: number;
+                    notLandedCount: number;
                 } | null;
                 disposition: {
                     /** @constant */
@@ -9966,6 +10018,68 @@ export interface components {
                 };
             }[];
         };
+        ScheduleTickResponse: {
+            /** @enum {string} */
+            source: "edge" | "jobqueue";
+            /** Format: date-time */
+            tickedAt: string;
+            reconcileOk: boolean;
+            registryVersion: string | null;
+            dispatched: number;
+            incidentsOpened: number;
+            incidentsResolved: number;
+        };
+        ScheduleTickRequest: {
+            /** @enum {string} */
+            source: "edge" | "jobqueue";
+            /** Format: date-time */
+            scheduledFor: string;
+            cron: string;
+        };
+        ScheduleClaimResponse: {
+            /** @constant */
+            outcome: "claimed";
+            executionId: string;
+            claimEpoch: number;
+            /** Format: date-time */
+            leaseUntil: string;
+            /** @enum {string} */
+            mode: "off" | "shadow" | "live";
+        } | {
+            /** @constant */
+            outcome: "legacy";
+            scheduleId: string;
+            /** @enum {string} */
+            mode: "off" | "shadow" | "live";
+        } | {
+            /** @constant */
+            outcome: "refused";
+            /** @enum {string} */
+            reason: "already_completed" | "lease_held" | "legacy_run_not_admitted" | "not_dispatched" | "binding_mismatch" | "schedule_off";
+        };
+        ScheduleStartRequest: {
+            executionId: string | null;
+            attempt: number | null;
+        };
+        ScheduleFinishResponse: {
+            /** @constant */
+            recorded: true;
+            executionId: string;
+            /** @enum {string} */
+            state: "due" | "dispatch_requested" | "started" | "completed" | "output_verified" | "timed_out" | "superseded" | "missed" | "acknowledged_loss";
+        } | {
+            /** @constant */
+            recorded: false;
+            /** @enum {string} */
+            reason: "stale_epoch" | "binding_mismatch" | "unknown_execution";
+        };
+        ScheduleFinishRequest: {
+            executionId: string;
+            attempt: number;
+            claimEpoch: number;
+            /** @enum {string} */
+            conclusion: "success" | "failure" | "cancelled";
+        };
         ImpersonationSessionResponse: {
             session: {
                 impersonationSessionId: string;
@@ -10735,6 +10849,8 @@ export interface components {
                     label: string;
                 } | null;
                 approvedAt: string | null;
+                approvable: boolean;
+                blockedReason: "needs_doc_access" | null;
             }[];
             discovery: {
                 foundThisRun: number;
@@ -10799,6 +10915,8 @@ export interface components {
                     label: string;
                 } | null;
                 approvedAt: string | null;
+                approvable: boolean;
+                blockedReason: "needs_doc_access" | null;
             }[];
             /** Format: uuid */
             workflowId: string;
@@ -10926,6 +11044,8 @@ export interface components {
                     label: string;
                 } | null;
                 approvedAt: string | null;
+                approvable: boolean;
+                blockedReason: "needs_doc_access" | null;
             }[];
         };
         SourceSyncApplyResponse: {
@@ -10985,6 +11105,8 @@ export interface components {
                     label: string;
                 } | null;
                 approvedAt: string | null;
+                approvable: boolean;
+                blockedReason: "needs_doc_access" | null;
             }[];
         };
         SourceSyncRulesResponse: {
@@ -16916,7 +17038,7 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Unsupported image type or bytes are not a valid image */
+            /** @description Unsupported image type (accepted: PNG/JPEG/WEBP/GIF/HEIC/HEIF) or bytes are not a valid image */
             415: {
                 headers: {
                     [name: string]: unknown;
@@ -17006,7 +17128,7 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Unsupported image type or bytes are not a valid image */
+            /** @description Unsupported image type (accepted: PNG/JPEG/WEBP/GIF/HEIC/HEIF) or bytes are not a valid image */
             415: {
                 headers: {
                     [name: string]: unknown;
@@ -18885,6 +19007,148 @@ export interface operations {
             };
         };
     };
+    scheduleTick: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ScheduleTickRequest"];
+            };
+        };
+        responses: {
+            /** @description The pass ran (reconcileOk false when it could not conclude) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ScheduleTickResponse"];
+                };
+            };
+            /** @description Payload invalid, or a source other than edge */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid edge bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The pass did not finish within its deadline */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    scheduleExecutionStart: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ScheduleStartRequest"];
+            };
+        };
+        responses: {
+            /** @description claimed, legacy (runs, counts toward no slot) or refused (skip the work) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ScheduleClaimResponse"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or rejected GitHub Actions OIDC token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The workflow is not bound to a registered schedule */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description GitHub could not confirm the run; nothing was claimed */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    scheduleExecutionFinish: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ScheduleFinishRequest"];
+            };
+        };
+        responses: {
+            /** @description recorded, or not recorded with the reason (a stale epoch is not an error) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ScheduleFinishResponse"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or rejected GitHub Actions OIDC token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The workflow is not bound to this schedule */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     startImpersonation: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -218,6 +218,9 @@ export const openApiRoutes = {
   '/api/reporting/move/apply': ['POST'],
   '/api/reporting/move/preview': ['POST'],
   '/api/reporting/positions/{positionId}/manager': ['PUT'],
+  '/api/schedules/executions/finish': ['POST'],
+  '/api/schedules/executions/start': ['POST'],
+  '/api/schedules/tick': ['POST'],
   '/api/scope/check': ['GET'],
   '/api/scope/check-batch': ['POST'],
   '/api/source-sync/candidate-sets/current': ['GET'],

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

@@ -34,6 +34,8 @@ function scope(overrides: Record<string, unknown> = {}) {
     vacantHead: false,
     approvedBy: null,
     approvedAt: null,
+    approvable: true,
+    blockedReason: null,
     ...overrides,
   };
 }
@@ -100,6 +102,28 @@ describe("SourceSyncScopeApprovalProjectionSchema", () => {
   });
 });
 
+describe("approvable and blockedReason", () => {
+  it("accepts a visible scope the caller may not approve, with its reason", () => {
+    const parsed = SourceSyncScopeApprovalProjectionSchema.safeParse(
+      scope({ approvable: false, blockedReason: "needs_doc_access" }),
+    );
+    expect(parsed.success).toBe(true);
+  });
+
+  it("refuses a reason outside the vocabulary and a missing approvable", () => {
+    expect(
+      SourceSyncScopeApprovalProjectionSchema.safeParse(
+        scope({ approvable: false, blockedReason: "not_admin" }),
+      ).success,
+    ).toBe(false);
+    const { approvable: _omit, ...withoutApprovable } = scope();
+    expect(
+      SourceSyncScopeApprovalProjectionSchema.safeParse(withoutApprovable)
+        .success,
+    ).toBe(false);
+  });
+});
+
 describe("scopes is required on every checkpoint response", () => {
   const schemas = [
     ["candidate set", SourceSyncCandidateSetResponseSchema],

package/src/source-sync/index.ts

@@ -31,6 +31,7 @@ export type {
   SourceSyncDocDisposition,
   SourceSyncScopeApprovalState,
   SourceSyncScopeApproverKind,
+  SourceSyncScopeBlockedReason,
   DocumentType,
   KnownDocumentType,
   OperatingKnowledgeFamily,
@@ -47,6 +48,7 @@ export {
   SOURCE_SYNC_DOC_DISPOSITIONS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
+  SOURCE_SYNC_SCOPE_BLOCKED_REASONS,
   DOCUMENT_TYPES,
   OPERATING_KNOWLEDGE_FAMILIES,
 } from "./vocabulary";

package/src/source-sync/schemas.ts

@@ -26,6 +26,7 @@ import {
   SOURCE_SYNC_DOC_RISKS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
+  SOURCE_SYNC_SCOPE_BLOCKED_REASONS,
 } from "./vocabulary";
 import { CandidateDiscoverySummarySchema } from "./relevance";
 import { SourceSyncCandidateItemSchema } from "./candidate-item";
@@ -45,6 +46,13 @@ const PersonLabel = z.string().min(1).max(255);
  *   still a `unit_head` scope, `assignedTo` is null, and the org's admins approve it.
  * - An approved scope reports the routing its approval RECORDED; a later head
  *   change does not rewrite it. A pending scope reports its routing as of now.
+ * - `approvable` is whether THE CALLER may approve this pending scope now. A scope
+ *   can be visible but not approvable: approving needs the caller's own upload and
+ *   edit access on the scope's document, because landing and apply act as the
+ *   approver. `blockedReason` is non-null exactly when a pending scope is not
+ *   approvable; an approved scope is never approvable and carries null. At the
+ *   synthesis checkpoint a pending scope is approvable: apply is decided per
+ *   document by the edit policy, which approving the candidate set required.
  */
 export const SourceSyncScopeApprovalProjectionSchema = z.object({
   /** 'company' or 'unit:<uuid>'. */
@@ -62,6 +70,8 @@ export const SourceSyncScopeApprovalProjectionSchema = z.object({
   /** Non-null exactly when a person's approval is recorded. */
   approvedBy: z.object({ label: PersonLabel }).nullable(),
   approvedAt: IsoDateTime.nullable(),
+  approvable: z.boolean(),
+  blockedReason: z.enum(SOURCE_SYNC_SCOPE_BLOCKED_REASONS).nullable(),
 });
 
 /** The discovery run a person started, or that upkeep started on a schedule. */

package/src/source-sync/vocabulary.ts

@@ -111,6 +111,16 @@ export const SOURCE_SYNC_SCOPE_APPROVER_KINDS = [
 export type SourceSyncScopeApproverKind =
   (typeof SOURCE_SYNC_SCOPE_APPROVER_KINDS)[number];
 
+/**
+ * Why the CALLER may not approve a scope they can see. `needs_doc_access`: the
+ * landing and the apply act as the approver, so approving needs the caller's own
+ * upload and edit access on the scope's document (an admin holds only metadata
+ * access to company.md content).
+ */
+export const SOURCE_SYNC_SCOPE_BLOCKED_REASONS = ["needs_doc_access"] as const;
+export type SourceSyncScopeBlockedReason =
+  (typeof SOURCE_SYNC_SCOPE_BLOCKED_REASONS)[number];
+
 /**
  * What a source IS — a STRUCTURAL name the model observes, never a relevance verdict
  * (control ADR source-discovery-observation-vs-policy). The set names operating

package/src/workflows/deferred-route.ts

@@ -147,6 +147,8 @@ export const SYNTHESIZE_DEFERRED_ROUTE_OF_REASON = {
   // prettier-ignore
   updates_ready: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
   // prettier-ignore
+  updates_ready_partial: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
+  // prettier-ignore
   updates_applied: { route: "covered", by: "sourceSync.docs_updated", fallback: "notice", audience: "creator" },
   stopped_by_user: STOPPED,
   paused_billing: EXPLAINED,

package/src/workflows/outcome-reasons.ts

@@ -120,6 +120,8 @@ export type DiscoverOutcomeFacts = z.infer<typeof DiscoverOutcomeFactsSchema>;
 /** Why a synthesis (landing then drafting) run ended the way it did. */
 export const SYNTHESIZE_OUTCOME_KIND_OF_REASON = {
   updates_ready: "produced",
+  /** Drafted from what landed; some approved files could not be brought in. */
+  updates_ready_partial: "partial",
   updates_applied: "produced",
   stopped_by_user: "stopped",
   paused_billing: "failed",
@@ -142,6 +144,7 @@ export type SynthesizeOutcomeReason =
 /** What each synthesis ending offers. TOTAL; an empty list is explicit. */
 export const SYNTHESIZE_AFFORDANCES_OF_REASON = {
   updates_ready: [],
+  updates_ready_partial: [],
   updates_applied: [],
   stopped_by_user: [],
   paused_billing: [OPEN_BILLING],
@@ -168,6 +171,8 @@ export const SynthesizeOutcomeFactsSchema = z
     scopeCount: Count,
     /** Authority or size violations that left the batch incomplete. */
     violationCount: Count,
+    /** Approved files to attach that did not land (refused, unreadable, gone). */
+    notLandedCount: Count,
   })
   .strict();