@company-semantics/contracts 91.0.0 → 92.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "91.0.0",
+  "version": "92.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -179,6 +179,7 @@
       "esbuild@<0.28.1": ">=0.28.1",
       "linkify-it@<5.0.2": ">=5.0.2",
       "postcss@<8.5.23": ">=8.5.23",
+      "source-map-js@<1.2.2": ">=1.2.2",
       "markdown-it@<14.2.0": ">=14.2.0",
       "@humanfs/node@<0.16.8": ">=0.16.8 <0.17.0"
     }
@@ -188,5 +189,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "8700b9fe36f8c948f12970ec54128e4f1955986dd9b634114f7501fdb1884267"
+  "securityRequirementsVersion": "4b88755e9a43a82b2f5eb55b953581526f1982de362da77bc579888d1f6a1bb0"
 }

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 = 'b2a6eec5dea4' as const;
-export const SPEC_HASH_FULL = 'b2a6eec5dea4f72290740a1cf16608a826ece2e3654ba64d2bc5e3794d571809' as const;
+export const SPEC_HASH = '9937d3953931' as const;
+export const SPEC_HASH_FULL = '9937d39539319f5173df9f15191c8dc5af40aca8c8cd62a9995f7221436909d2' as const;

package/src/api/generated.ts

@@ -1566,6 +1566,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/integrations/bamboohr/sync": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Run a BambooHR sync now (returns the run summary) */
+        post: operations["syncBambooHrNow"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/org/reconciliation": {
         parameters: {
             query?: never;
@@ -1666,6 +1683,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org/structure-inference/runs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Launch one org-structure reanalyze workflow and its inference run
+         * @description Mints an org-structure/reanalyze analysis workflow, opens its pending run and schedules the job, all in one transaction (ADR-BE-606, ADR-BE-703): the snapshot, the model calls and the deterministic gate execute on the worker, and the outcome is read back by polling GET /api/org/structure-inference/proposal, whose run field carries this run’s id and status, or GET /api/analysis-workflows/{workflowId} for the workflow. At most one inference is in flight per org — a second POST joins the run already under way. Explicitly operator-triggered: there is no schedule and no sync hook.
+         */
+        post: operations["runOrgStructureInference"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/analysis-workflows/{id}": {
         parameters: {
             query?: never;
@@ -1726,6 +1763,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/affordances/state": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read the live policy and availability of offered affordances
+         * @description For exactly the affordance ids named in `ids` (the ids a settled outcome offered — never the catalog), whether the viewer is shown each one (`policy`, from the same capability derivation as GET /api/capabilities) and whether the org’s current state permits it (`availability`). Entries come back in request order, deduped. NON-AUTHORITATIVE: this answer is advisory UX state; the route each affordance binds to stays the only enforcement and may still refuse. Org-scoped: requires active membership of the session org, because availability discloses org state.
+         */
+        get: operations["getAffordanceState"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/tree": {
         parameters: {
             query?: never;
@@ -4879,7 +4936,7 @@ export interface paths {
         put?: never;
         /**
          * Approve the draft candidate set as reviewed, per scope
-         * @description Approves the named scopes (or every scope still open) at the revision the person reviewed. Per scope, the items freeze, a hash binds them to that scope’s share of the spending cap, and a landing job is scheduled on one landing-and-synthesis workflow.
+         * @description Approves the named scopes (or every scope still open) at the revision the person reviewed. Per scope, the items freeze, a hash binds the approval to exactly those files and treatments, and a landing job is scheduled on one landing-and-synthesis workflow. Approval authorizes the revision only; it carries no spend.
          */
         post: operations["approveSourceCandidateSet"];
         delete?: never;
@@ -6808,6 +6865,34 @@ export interface components {
                         requiredScope?: string;
                     };
                 };
+                integrations?: {
+                    manage: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
+                sourceSync?: {
+                    manage: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
+                billing?: {
+                    view: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
+                orgStructure?: {
+                    analyze: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
             };
             chatMentions: boolean;
             chatMultiParty: boolean;
@@ -6816,6 +6901,17 @@ export interface components {
                 reason: ("BILLING_INACTIVE" | "SEAT_SUBSCRIPTION_PAST_DUE" | "AI_BALANCE_EXHAUSTED" | "AI_BUDGET_EXHAUSTED" | "BYO_KEY_INVALID") | null;
             };
         };
+        BambooHrSyncRunResponse: {
+            /** Format: uuid */
+            runId: string;
+            processed: number;
+            changed: number;
+            skipped: number;
+            conflicts: number;
+            failures: number;
+            sinceCursor: string | null;
+            status: string;
+        };
         ResolveOrgDivergenceRequest: {
             /** @constant */
             resolution: "acknowledged";
@@ -6993,6 +7089,23 @@ export interface components {
             fingerprint: string;
             note?: string;
         };
+        RunStructureInferenceRefusal: {
+            /** @constant */
+            ran: false;
+            /** @enum {string} */
+            reason: "no_sync_run" | "no_persons" | "reporting_not_keyed";
+            message: string;
+        };
+        RunStructureInferenceAccepted: {
+            /** @constant */
+            ran: true;
+            /** Format: uuid */
+            runId: string;
+            workflowId: string | null;
+            /** @enum {string} */
+            status: "pending" | "running";
+            alreadyRunning: boolean;
+        };
         AnalysisWorkflowProjectionResponse: {
             /** Format: uuid */
             id: string;
@@ -7003,7 +7116,180 @@ export interface components {
             completedAt: string | null;
             progress: unknown | null;
             result: unknown | null;
-            outcome: unknown | null;
+            outcome: ({
+                /** @constant */
+                workflowType: "source-sync/discover";
+                executionEpoch: number;
+                /** @enum {string} */
+                kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
+                /** @enum {string} */
+                reason: "candidates_found" | "nothing_found" | "nothing_relevant" | "budget_exhausted" | "file_ceiling" | "stopped_by_user" | "plan_coverage_refused" | "billing_refused" | "drive_auth" | "drive_unavailable" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                facts: {
+                    probesTotal: number;
+                    probesDone: number;
+                    filesSeen: number;
+                    filesShown: number;
+                    filesHidden: number;
+                    filesDropped: number;
+                    coveragePercent: number | null;
+                } | null;
+                disposition: {
+                    /** @constant */
+                    kind: "review";
+                    /** @enum {string} */
+                    requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                    requestId: string;
+                } | {
+                    /** @constant */
+                    kind: "narrate";
+                };
+                affordances: ({
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                })[];
+            } | {
+                /** @constant */
+                workflowType: "source-sync/synthesize";
+                executionEpoch: number;
+                /** @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";
+                facts: {
+                    scopeCount: number;
+                    violationCount: number;
+                } | null;
+                disposition: {
+                    /** @constant */
+                    kind: "review";
+                    /** @enum {string} */
+                    requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                    requestId: string;
+                } | {
+                    /** @constant */
+                    kind: "narrate";
+                };
+                affordances: ({
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                })[];
+            } | {
+                /** @constant */
+                workflowType: "org-structure/hris-connect";
+                executionEpoch: number;
+                /** @enum {string} */
+                kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
+                /** @enum {string} */
+                reason: "proposal_ready" | "directory_synced" | "analysis_already_running" | "proposal_blocked" | "no_sync_run" | "no_persons" | "reporting_not_keyed" | "stopped_by_user" | "sync_failed" | "snapshot_too_large" | "model_failed" | "run_too_large" | "placement_failed" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                facts: {
+                    departmentCount: number;
+                    teamCount: number;
+                    placedCount: number;
+                    reviewItemCount: number;
+                } | null;
+                disposition: {
+                    /** @constant */
+                    kind: "review";
+                    /** @enum {string} */
+                    requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                    requestId: string;
+                } | {
+                    /** @constant */
+                    kind: "narrate";
+                };
+                affordances: ({
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                })[];
+            } | {
+                /** @constant */
+                workflowType: "org-structure/reanalyze";
+                executionEpoch: number;
+                /** @enum {string} */
+                kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
+                /** @enum {string} */
+                reason: "proposal_ready" | "directory_synced" | "analysis_already_running" | "proposal_blocked" | "no_sync_run" | "no_persons" | "reporting_not_keyed" | "stopped_by_user" | "sync_failed" | "snapshot_too_large" | "model_failed" | "run_too_large" | "placement_failed" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                facts: {
+                    departmentCount: number;
+                    teamCount: number;
+                    placedCount: number;
+                    reviewItemCount: number;
+                } | null;
+                disposition: {
+                    /** @constant */
+                    kind: "review";
+                    /** @enum {string} */
+                    requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                    requestId: string;
+                } | {
+                    /** @constant */
+                    kind: "narrate";
+                };
+                affordances: ({
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                })[];
+            }) | null;
             error?: string;
             capabilities: {
                 canStop: boolean;
@@ -7027,6 +7313,26 @@ export interface components {
             /** @enum {string} */
             result: "delivered" | "deferred" | "busy" | "skipped" | "not_settled";
         };
+        AffordanceStateResponse: {
+            entries: {
+                /** @enum {string} */
+                id: "sourceSync.findFiles" | "integrations.connectGoogleDrive" | "sourceSync.enable" | "billing.open" | "orgStructure.reanalyze" | "hris.resyncDirectory" | "review.open";
+                /** @enum {string} */
+                policy: "allowed" | "blocked";
+                availability: {
+                    /** @constant */
+                    state: "available";
+                } | {
+                    /** @constant */
+                    state: "already_satisfied";
+                } | {
+                    /** @constant */
+                    state: "unavailable";
+                    /** @enum {string} */
+                    reason: "conflicting_operation" | "missing_dependency" | "resource_gone" | "temporarily_disabled";
+                };
+            }[];
+        };
         CompanyMdListResponse: {
             items: {
                 id: string;
@@ -9523,11 +9829,6 @@ export interface components {
                 } | null;
                 approvedAt: string | null;
             }[];
-            estimate: {
-                lowMicroUsd: string;
-                highMicroUsd: string;
-                capMicroUsd: string;
-            } | null;
             discovery: {
                 foundThisRun: number;
                 retainedDecisions: number;
@@ -9603,7 +9904,7 @@ export interface components {
                 workflowId: string;
                 batchId: string | null;
                 /** @enum {string} */
-                phase: "landing" | "drafting" | "waiting_for_review" | "paused_billing" | "applied" | "applied_partial" | "failed" | "closed";
+                phase: "landing" | "drafting" | "waiting_for_review" | "paused_billing" | "paused_ceiling" | "applied" | "applied_partial" | "failed" | "closed";
                 fileCount: number | null;
                 proposedDocumentCount: number;
                 appliedAt: string | null;
@@ -12949,6 +13250,33 @@ export interface operations {
             };
         };
     };
+    syncBambooHrNow: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Sync run summary */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BambooHrSyncRunResponse"];
+                };
+            };
+            /** @description No active BambooHR connection, or BambooHR no longer recognizes the organization */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getOrgReconciliation: {
         parameters: {
             query?: never;
@@ -13096,6 +13424,35 @@ export interface operations {
             };
         };
     };
+    runOrgStructureInference: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description A named refusal with its operator-facing next step: no directory imported yet, a sync that imported nobody, or a credential whose sync could not key reporting edges (reporting_not_keyed) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RunStructureInferenceRefusal"];
+                };
+            };
+            /** @description A run is under way — freshly launched, or already in flight (alreadyRunning: true). Carries the runId the poll surface matches against and the workflowId of the org-structure/reanalyze workflow it executes (null only when the joined run predates the workflow launch) */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RunStructureInferenceAccepted"];
+                };
+            };
+        };
+    };
     getAnalysisWorkflow: {
         parameters: {
             query?: never;
@@ -13213,6 +13570,42 @@ export interface operations {
             };
         };
     };
+    getAffordanceState: {
+        parameters: {
+            query: {
+                ids: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Policy and availability per requested affordance id, in request order */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AffordanceStateResponse"];
+                };
+            };
+            /** @description An id is not a known affordance, the list is empty, or it is too long */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The viewer is not an active member of the session org */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCompanyMdTree: {
         parameters: {
             query?: {
@@ -19586,7 +19979,6 @@ export interface operations {
             content: {
                 "application/json": {
                     revision: number;
-                    spendCapMicroUsd: string;
                     scopeKeys?: string[];
                 };
             };
@@ -19601,7 +19993,7 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncApproveResponse"];
                 };
             };
-            /** @description Invalid request, a scope with no files (SOURCE_SYNC_SCOPE_UNKNOWN), or a cap too large to hold exactly (SOURCE_SYNC_SPEND_CAP_INVALID) */
+            /** @description Invalid request (an unknown field such as a spend cap is refused by the schema), or a scope with no files (SOURCE_SYNC_SCOPE_UNKNOWN) */
             400: {
                 headers: {
                     [name: string]: unknown;

package/src/generated/openapi-routes.ts

@@ -9,6 +9,7 @@ export const openApiRoutes = {
   '/api/account/deletion-eligibility': ['GET'],
   '/api/account/sessions': ['GET'],
   '/api/account/sessions/{sessionId}': ['DELETE'],
+  '/api/affordances/state': ['GET'],
   '/api/analysis-workflows/{id}': ['GET'],
   '/api/analysis-workflows/{id}/settlement': ['POST'],
   '/api/analysis-workflows/{id}/stop': ['POST'],
@@ -101,6 +102,7 @@ export const openApiRoutes = {
   '/api/factory/quality/plans/{planId}/decision': ['GET'],
   '/api/factory/snapshot': ['GET'],
   '/api/ingestion/operations/{id}': ['GET'],
+  '/api/integrations/bamboohr/sync': ['POST'],
   '/api/internal-admin/impersonate/end': ['POST'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],
@@ -181,6 +183,7 @@ export const openApiRoutes = {
   '/api/org/structure-findings': ['GET'],
   '/api/org/structure-findings/{findingId}/dismiss': ['POST'],
   '/api/org/structure-findings/{findingId}/reopen': ['POST'],
+  '/api/org/structure-inference/runs': ['POST'],
   '/api/org/system-events': ['GET'],
   '/api/org/system-events/{id}/acknowledge': ['POST'],
   '/api/org/transfer-eligibility': ['GET'],

package/src/source-sync/README.md

@@ -305,7 +305,8 @@ in `attention-evidence.ts`.
   `attentionEvidence` (null before index-first discovery).
 - `SourceSyncCandidateSetResponseSchema` / `SourceSyncCandidateSetResponse` —
   the draft set under review: its revision, items, presented questions,
-  distinct-file `totals` and cost estimate.
+  distinct-file `totals`. No cost estimate: approval authorizes the files,
+  never a spend.
 - `SourceSyncCandidateTotalsSchema` / `SourceSyncCandidateTotals` and
   `candidateTotalsOf(items)` — THE file count: distinct `sourceId`, never lines
   (ADR-CONTRACTS-195).

package/src/source-sync/__tests__/approval-schemas.test.ts

@@ -48,7 +48,6 @@ function addCandidate(overrides: Record<string, unknown> = {}) {
 function approveRequest(overrides: Record<string, unknown> = {}) {
   return {
     revision: 7,
-    spendCapMicroUsd: "2500000",
     ...overrides,
   };
 }
@@ -112,20 +111,10 @@ describe("SourceSyncApproveRequestSchema", () => {
     expect(refused.error?.issues[0]?.path).toEqual(["revision"]);
   });
 
-  it("refuses an approval with no spend cap", () => {
-    const { spendCapMicroUsd: _cap, ...withoutCap } = approveRequest();
-    const refused = SourceSyncApproveRequestSchema.safeParse(withoutCap);
-    expect(refused.success).toBe(false);
-    expect(refused.error?.issues[0]?.path).toEqual(["spendCapMicroUsd"]);
-
-    expect(
-      SourceSyncApproveRequestSchema.safeParse(
-        approveRequest({ spendCapMicroUsd: "2.50" }),
-      ).success,
-    ).toBe(false);
+  it("refuses a spend cap: an approval authorizes files, never a spend", () => {
     expect(
       SourceSyncApproveRequestSchema.safeParse(
-        approveRequest({ spendCapMicroUsd: 2500000 }),
+        approveRequest({ spendCapMicroUsd: "2500000" }),
       ).success,
     ).toBe(false);
   });

package/src/source-sync/__tests__/current-synthesis.test.ts

@@ -43,6 +43,7 @@ describe("SOURCE_SYNC_SYNTHESIS_PHASES", () => {
       "drafting",
       "waiting_for_review",
       "paused_billing",
+      "paused_ceiling",
       "applied",
       "applied_partial",
       "failed",