@company-semantics/contracts 27.0.0 → 27.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "27.0.0",
+  "version": "27.2.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 = '4471246b55aa' as const;
-export const SPEC_HASH_FULL = '4471246b55aac3b38566bc16e44db735eacd94637c900db8c1727e1381539a5a' as const;
+export const SPEC_HASH = '409ce57139cd' as const;
+export const SPEC_HASH_FULL = '409ce57139cd78a8ec633efb516bc92ba81dd2cdaab0a4afe240d20c67bb6b1e' as const;

package/src/api/generated.ts

@@ -1338,6 +1338,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/integrations/bamboohr/inferences": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List the org’s pending org-structure reasoning inferences (review queue) */
+        get: operations["listBambooHrInferences"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/integrations/bamboohr/inferences/{id}/decision": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Accept or reject one pending org-structure reasoning inference */
+        post: operations["decideBambooHrInference"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/tree": {
         parameters: {
             query?: never;
@@ -1662,6 +1696,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/docs/:id/context-bank/suggestions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Suggest context docs semantically nearest to a parent the caller may view */
+        get: operations["companyMdContextDocSuggestions"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/search": {
         parameters: {
             query?: never;
@@ -4349,6 +4400,29 @@ export interface components {
                 };
             };
         };
+        OrgStructureReviewQueue: {
+            items: {
+                /** Format: uuid */
+                id: string;
+                inferenceType: string;
+                payload: unknown;
+                confidence: number;
+                reason: string;
+                /** Format: date-time */
+                createdAt: string;
+            }[];
+        };
+        OrgStructureInferenceDecisionResult: {
+            /** Format: uuid */
+            id: string;
+            /** @enum {string} */
+            status: "accepted" | "rejected";
+            applied: boolean;
+        };
+        BambooHrInferenceDecision: {
+            /** @enum {string} */
+            decision: "accept" | "reject";
+        };
         CompanyMdListResponse: {
             items: {
                 id: string;
@@ -4458,6 +4532,10 @@ export interface components {
         SearchContextDocsResponse: {
             items: components["schemas"]["ContextDocDiscoveryHit"][];
         };
+        /** @description Semantically nearest context-doc suggestions the caller may view. */
+        SuggestContextDocsResponse: {
+            items: components["schemas"]["ContextDocDiscoveryHit"][];
+        };
         /** @description Ranked retrieval hits plus the source kinds actually searched. */
         CompanyMdSearchResponse: {
             hits: {
@@ -7778,6 +7856,66 @@ export interface operations {
             };
         };
     };
+    listBambooHrInferences: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The org’s pending (review) org-structure inferences, newest first */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgStructureReviewQueue"];
+                };
+            };
+        };
+    };
+    decideBambooHrInference: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["BambooHrInferenceDecision"];
+            };
+        };
+        responses: {
+            /** @description The decision outcome (status + whether the org graph was mutated) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgStructureInferenceDecisionResult"];
+                };
+            };
+            /** @description Invalid decision value */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Inference not found or already decided */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCompanyMdTree: {
         parameters: {
             query?: {
@@ -8338,6 +8476,42 @@ export interface operations {
             };
         };
     };
+    companyMdContextDocSuggestions: {
+        parameters: {
+            query?: {
+                limit?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description ACL-admitted semantically-nearest context-doc suggestions */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestContextDocsResponse"];
+                };
+            };
+            /** @description Invalid path or query parameters */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Requires org.view_company_md scope */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     searchCompanyMd: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -24,6 +24,8 @@ export const openApiRoutes = {
   '/api/company-md/access-requests/{id}/approve': ['POST'],
   '/api/company-md/access-requests/{id}/deny': ['POST'],
   '/api/company-md/context-bank': ['POST'],
+  '/api/company-md/context-bank/search': ['GET'],
+  '/api/company-md/docs/:id/context-bank/suggestions': ['GET'],
   '/api/company-md/docs/{id}': ['GET'],
   '/api/company-md/docs/{id}/access-requests': ['GET', 'POST'],
   '/api/company-md/docs/{id}/content': ['PUT'],
@@ -60,6 +62,8 @@ export const openApiRoutes = {
   '/api/factory/kpis': ['GET'],
   '/api/factory/snapshot': ['GET'],
   '/api/ingestion/operations/{id}': ['GET'],
+  '/api/integrations/bamboohr/inferences': ['GET'],
+  '/api/integrations/bamboohr/inferences/{id}/decision': ['POST'],
   '/api/internal-admin/impersonate/end': ['POST'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],

package/src/index.ts

@@ -424,6 +424,20 @@ export type { SyncRunSummary } from "./org/index";
 export { ConflictRecordSchema } from "./org/index";
 export type { ConflictRecord } from "./org/index";
 
+// Org-structure reasoning review queue: pending structure inferences an operator
+// accepts/rejects, and the outcome of one decision. Published response shapes.
+// Provider-agnostic store; BambooHR is the first surface. (ADR-CONT-095)
+export {
+  OrgStructureReviewInferenceSchema,
+  OrgStructureReviewQueueSchema,
+  OrgStructureInferenceDecisionResultSchema,
+} from "./org/index";
+export type {
+  OrgStructureReviewInference,
+  OrgStructureReviewQueue,
+  OrgStructureInferenceDecisionResult,
+} from "./org/index";
+
 // Canonical facts: the adapter-seam ingestion batch — external-keyed Canonical*
 // facts (each with provenance) plus a CanonicalFacts envelope. The reconciler
 // consumes the batch into the internal org graph. (ADR-CONT-085 / ADR-CTRL-183)

package/src/org/README.md

@@ -159,6 +159,12 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgOwnerIcon` _(type)_
 - `OrgOwnerIconSchema` — Icon options for the `owner` org-chart role.
 - `OrgScopedContext` _(type)_ — Validated organization-scoped context for policy implementations.
+- `OrgStructureInferenceDecisionResult` _(type)_
+- `OrgStructureInferenceDecisionResultSchema`
+- `OrgStructureReviewInference` _(type)_
+- `OrgStructureReviewInferenceSchema`
+- `OrgStructureReviewQueue` _(type)_
+- `OrgStructureReviewQueueSchema`
 - `OrgSystemEventsList` _(type)_
 - `OrgSystemEventsListSchema`
 - `OrgTreeResponse` _(type)_

package/src/org/index.ts

@@ -136,6 +136,20 @@ export type { SyncRunSummary } from "./sync-run";
 export { ConflictRecordSchema } from "./conflict-record";
 export type { ConflictRecord } from "./conflict-record";
 
+// Org-structure reasoning review queue: pending structure inferences an operator
+// accepts/rejects, and the outcome of one decision. Published response shapes;
+// provider-agnostic store, BambooHR is the first surface. (ADR-CONT-095)
+export {
+  OrgStructureReviewInferenceSchema,
+  OrgStructureReviewQueueSchema,
+  OrgStructureInferenceDecisionResultSchema,
+} from "./reasoning-review";
+export type {
+  OrgStructureReviewInference,
+  OrgStructureReviewQueue,
+  OrgStructureInferenceDecisionResult,
+} from "./reasoning-review";
+
 // Canonical facts: the adapter-seam ingestion batch. Each fact is keyed by
 // external identity (externalSourceId/externalSourceSystem) and carries a
 // FactProvenance envelope; the reconciler consumes the batch. (ADR-CONT-085 / ADR-CTRL-183)

package/src/org/reasoning-review.ts

@@ -0,0 +1,85 @@
+/**
+ * Org-structure reasoning review vocabulary — the operator review queue for
+ * proposed structure changes and the outcome of deciding one.
+ *
+ * An org-structure reasoning pass (the adapter → reasoning-engine pipeline,
+ * BambooHR being the guinea-pig source — control ADR-CTRL-159, backend
+ * ADR-BE-345) emits structure INFERENCES (nest a unit, place a report, ...) that
+ * are held in `review` rather than applied blindly. The review queue is the set
+ * of an org's pending inferences; an operator with integration-management
+ * authority ACCEPTS one (re-applying it to the live org graph) or REJECTS it.
+ *
+ * These are published RESPONSE shapes (ADR-CONT-029: response/published shapes
+ * live in contracts; the `decision` request body stays backend-local). They are
+ * provider-agnostic — the underlying store (`org_structure_inferences`) is not
+ * BambooHR-specific even though the first surface that reads it is the BambooHR
+ * integration route. `inferenceType` is an OPEN string (no enum) so new
+ * inference kinds need no schema change, mirroring the sibling org schemas
+ * ({@link ConflictRecordSchema}, {@link SyncRunSummarySchema}). `payload` is the
+ * inference-kind-specific body, modeled as unknown — its shape is keyed off
+ * `inferenceType` and is not part of the stable contract surface.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// OrgStructureReviewInference — one pending ('review') structure inference
+// ---------------------------------------------------------------------------
+
+export const OrgStructureReviewInferenceSchema = z.object({
+  /** Identifier of this inference within the org graph. */
+  id: z.string().uuid(),
+  /**
+   * Kind of structure inference (e.g. "NestOrgUnit", "PlaceReport"). An OPEN
+   * string so new inference kinds need no schema change.
+   */
+  inferenceType: z.string().min(1),
+  /**
+   * The inference-kind-specific body. Its shape is keyed off `inferenceType`
+   * and is intentionally unmodeled here — not part of the stable contract.
+   */
+  payload: z.unknown(),
+  /** Engine confidence in this inference, 0..1. */
+  confidence: z.number(),
+  /** Human-meaningful WHY the engine proposed this change. */
+  reason: z.string(),
+  /** ISO timestamp the inference was created. */
+  createdAt: z.string().datetime(),
+});
+
+export type OrgStructureReviewInference = z.infer<
+  typeof OrgStructureReviewInferenceSchema
+>;
+
+// ---------------------------------------------------------------------------
+// OrgStructureReviewQueue — an org's pending review inferences (newest first)
+// ---------------------------------------------------------------------------
+
+export const OrgStructureReviewQueueSchema = z.object({
+  /** The org's pending ('review') inferences, newest first. */
+  items: z.array(OrgStructureReviewInferenceSchema),
+});
+
+export type OrgStructureReviewQueue = z.infer<
+  typeof OrgStructureReviewQueueSchema
+>;
+
+// ---------------------------------------------------------------------------
+// OrgStructureInferenceDecisionResult — outcome of accepting/rejecting one
+// ---------------------------------------------------------------------------
+
+export const OrgStructureInferenceDecisionResultSchema = z.object({
+  /** Identifier of the decided inference. */
+  id: z.string().uuid(),
+  /** The terminal status the inference was moved to. */
+  status: z.enum(["accepted", "rejected"]),
+  /**
+   * Whether the decision mutated the live org graph. True on an accept that
+   * re-applied the inference; false on a reject (and on an accept that resolved
+   * to a no-op).
+   */
+  applied: z.boolean(),
+});
+
+export type OrgStructureInferenceDecisionResult = z.infer<
+  typeof OrgStructureInferenceDecisionResultSchema
+>;