@company-semantics/contracts 9.0.0 → 9.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -113,13 +113,13 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^22.19.19",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.7",
     "markdownlint-cli2": "^0.22.1",
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.22.4",
-    "typescript": "^5",
+    "typescript": "^5.8.3",
     "vitest": "^4.1.8",
     "yaml": "^2.9.0"
   },

package/src/generated/openapi-routes.ts

@@ -47,6 +47,7 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/summary': ['GET'],
   '/api/executions/{executionId}/timeline': ['GET'],
   '/api/executions/{executionId}/undo': ['POST'],
+  '/api/factory/floor': ['GET'],
   '/api/internal-admin/impersonate/end': ['POST'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],

package/src/mcp/index.ts

@@ -209,6 +209,19 @@ export interface MCPToolDescriptor {
    * 'integration.connection' can only run after a tool that produces it.
    */
   consumes?: ResourceType[]
+  /**
+   * Mutation-capability gate (ADR-BE-241). When present, the tool is locked
+   * unless the viewer's resolved capabilities permit it — the SINGLE source of
+   * truth consumed by BOTH the backend execution gate and the frontend tool-lock
+   * UI (replacing the previously triplicated ACTION_TOOL_GATES / FIELD_GATES /
+   * ACTION_GATES maps).
+   * - kind 'field': `path` addresses a FieldCapability in CapabilitiesResponse
+   *   (e.g. 'org.name', 'profile.fullName'); locked unless state === 'editable'.
+   * - kind 'action': `path` addresses an ActionCapability under `.actions`
+   *   (e.g. 'members.invite', 'orgAdmins.manage'); locked unless 'allowed'.
+   * Absent ⇒ ungated (gating is additive).
+   */
+  capabilityGate?: { kind: 'field' | 'action'; path: string }
 }
 
 /**

package/src/org/index.ts

@@ -288,6 +288,10 @@ export {
   CreateDelegationRequestSchema,
   UpdateDelegationRequestSchema,
   DelegationListResponseSchema,
+  // Mutation capabilities (GET /api/capabilities) — ADR-BE-241
+  FieldCapabilitySchema,
+  ActionCapabilitySchema,
+  CapabilitiesResponseSchema,
 } from './schemas';
 export type {
   AuthoritySource,
@@ -303,4 +307,7 @@ export type {
   CreateDelegationRequest,
   UpdateDelegationRequest,
   DelegationListResponse,
+  FieldCapability,
+  ActionCapability,
+  CapabilitiesResponse,
 } from './schemas';

package/src/org/schemas.ts

@@ -1147,3 +1147,66 @@ export type OrgUnitPermissionsEntry = z.infer<typeof OrgUnitPermissionsEntrySche
 export type ListOrgUnitPermissionsResponse = z.infer<typeof ListOrgUnitPermissionsResponseSchema>;
 export type UpdateOrgUnitRequest = z.infer<typeof UpdateOrgUnitRequestSchema>;
 export type UpdateOrgUnitResponse = z.infer<typeof UpdateOrgUnitResponseSchema>;
+
+// =============================================================================
+// Mutation Capabilities (GET /api/capabilities) — ADR-BE-241 / PRD-00707 F4
+// =============================================================================
+// Canonical home for the viewer's resolved mutation-capability projection. The
+// backend derives it (src/capabilities/derive.ts) and validates the response
+// against CapabilitiesResponseSchema via sendValidated; the frontend reads the
+// inferred types to render lock/allow affordances. Previously duplicated as a
+// backend-local Zod + hand-written frontend interfaces — unified here.
+
+/** Scope identifiers are dot-namespaced strings (see backend trust/scopes.ts). */
+const RequiredScopeSchema = z.string();
+
+/** A mutable field's gate: editable, or locked with attribution (sso vs rbac). */
+export const FieldCapabilitySchema = z.object({
+  state: z.enum(['editable', 'locked']),
+  reason: z.enum(['sso', 'rbac']).optional(),
+  requiredScope: RequiredScopeSchema.optional(),
+});
+
+/** An action's gate: allowed, or blocked with the scope that would unlock it. */
+export const ActionCapabilitySchema = z.object({
+  state: z.enum(['allowed', 'blocked']),
+  requiredScope: RequiredScopeSchema.optional(),
+});
+
+/**
+ * The single validated capability surface the UI reads. Every sub-object is
+ * optional, matching the partial derivation in deriveCapabilities() (actions/org
+ * are present only when scopes resolved).
+ */
+export const CapabilitiesResponseSchema = z.object({
+  profile: z
+    .object({
+      fullName: FieldCapabilitySchema,
+      preferredName: FieldCapabilitySchema,
+    })
+    .optional(),
+  org: z
+    .object({
+      name: FieldCapabilitySchema,
+    })
+    .optional(),
+  actions: z
+    .object({
+      members: z.object({
+        invite: ActionCapabilitySchema,
+        remove: ActionCapabilitySchema,
+        changeRole: ActionCapabilitySchema,
+      }),
+      orgAdmins: z.object({
+        manage: ActionCapabilitySchema,
+      }),
+      orgUnit: z.object({
+        manage: ActionCapabilitySchema,
+      }),
+    })
+    .optional(),
+});
+
+export type FieldCapability = z.infer<typeof FieldCapabilitySchema>;
+export type ActionCapability = z.infer<typeof ActionCapabilitySchema>;
+export type CapabilitiesResponse = z.infer<typeof CapabilitiesResponseSchema>;