@company-semantics/contracts 1.15.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "1.15.0",
+  "version": "1.16.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 = 'b15100bf7771' as const;
-export const SPEC_HASH_FULL = 'b15100bf7771682644b63942432a672ffee7d4fdb1237201f491b4d8d3c6b238' as const;
+export const SPEC_HASH = 'e337542ea39d' as const;
+export const SPEC_HASH_FULL = 'e337542ea39de6f11b03f87d300e3e4c842825267c6918b1a37f2f86502124f8' as const;

package/src/api/generated.ts

@@ -647,38 +647,38 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/rbac/roles": {
+    "/api/workspace/members/{id}/role": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        /** List RBAC roles catalog (system + custom) with scopes and member counts */
-        get: operations["getRbacRoles"];
+        get?: never;
         put?: never;
         post?: never;
         delete?: never;
         options?: never;
         head?: never;
-        patch?: never;
+        /** Change member role */
+        patch: operations["changeMemberRole"];
         trace?: never;
     };
-    "/api/workspace/members/{id}/role": {
+    "/api/rbac/roles": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /** List RBAC roles catalog (system + custom) with scopes and member counts */
+        get: operations["getRbacRoles"];
         put?: never;
         post?: never;
         delete?: never;
         options?: never;
         head?: never;
-        /** Change member role */
-        patch: operations["changeMemberRole"];
+        patch?: never;
         trace?: never;
     };
     "/api/user/orgs": {
@@ -2355,49 +2355,26 @@ export interface components {
         WorkspaceHandleRequest: {
             handle: string;
         };
-        WorkspaceMemberUnitSummary: {
-            unitId: string;
-            unitName: string;
-            unitPath: string;
-            /** @enum {string} */
-            role: "owner" | "manager" | "member";
-        };
-        WorkspaceMember: {
-            id: string;
-            name: string;
-            email: string;
-            /** @enum {string} */
-            role: "owner" | "admin" | "member" | "auditor";
-            roleNames: string[];
-            joinedAt: string;
-            lastActiveAt: string | null;
-            unitMemberships: components["schemas"]["WorkspaceMemberUnitSummary"][];
-            unitMembershipsTruncated: boolean;
-            inviteStatus: ("active" | "pending" | "expired") | null;
-        };
-        MemberRecentAction: {
-            id: string;
-            timestamp: string;
-            action: string;
-            summary: string;
-        };
-        WorkspaceMemberDetail: components["schemas"]["WorkspaceMember"] & {
-            effectiveScopes: string[];
-            recentActions: components["schemas"]["MemberRecentAction"][];
-        };
-        RoleCatalogEntry: {
-            name: string;
-            /** @enum {string} */
-            type: "system" | "custom";
-            description: string;
-            scopes: string[];
-            memberCount: number;
-        };
-        RoleCatalogResponse: {
-            roles: components["schemas"]["RoleCatalogEntry"][];
-        };
         WorkspaceMembersResponse: {
-            items: components["schemas"]["WorkspaceMember"][];
+            items: {
+                id: string;
+                name: string;
+                email: string;
+                /** @enum {string} */
+                role: "owner" | "admin" | "member" | "auditor";
+                roleNames: string[];
+                joinedAt: string;
+                lastActiveAt: string | null;
+                unitMemberships: {
+                    unitId: string;
+                    unitName: string;
+                    unitPath: string;
+                    /** @enum {string} */
+                    role: "owner" | "manager" | "member";
+                }[];
+                unitMembershipsTruncated: boolean;
+                inviteStatus: ("active" | "pending" | "expired") | null;
+            }[];
             nextCursor: string | null;
             hasMore: boolean;
         };
@@ -2566,6 +2543,32 @@ export interface components {
             /** @enum {string} */
             errorCode?: "IDENTITY_CONFLICT" | "DOMAIN_MISMATCH" | "ISSUER_MISMATCH" | "CALLBACK_ERROR";
         };
+        WorkspaceMemberDetail: {
+            id: string;
+            name: string;
+            email: string;
+            /** @enum {string} */
+            role: "owner" | "admin" | "member" | "auditor";
+            roleNames: string[];
+            joinedAt: string;
+            lastActiveAt: string | null;
+            unitMemberships: {
+                unitId: string;
+                unitName: string;
+                unitPath: string;
+                /** @enum {string} */
+                role: "owner" | "manager" | "member";
+            }[];
+            unitMembershipsTruncated: boolean;
+            inviteStatus: ("active" | "pending" | "expired") | null;
+            effectiveScopes: string[];
+            recentActions: {
+                id: string;
+                timestamp: string;
+                action: string;
+                summary: string;
+            }[];
+        };
         RemoveMemberResponse: {
             success: boolean;
             memberId: string;
@@ -2584,6 +2587,16 @@ export interface components {
             /** @enum {string} */
             newRole: "admin" | "member";
         };
+        RoleCatalogResponse: {
+            roles: {
+                name: string;
+                /** @enum {string} */
+                type: "system" | "custom";
+                description: string;
+                scopes: string[];
+                memberCount: number;
+            }[];
+        };
         UserOrgsResponse: {
             orgs: {
                 userId: string;
@@ -2802,6 +2815,7 @@ export interface components {
             target: {
                 type: string;
                 workspaceId?: string;
+                service?: string;
             };
             connectionId?: string;
             returnUrl?: string;
@@ -4467,48 +4481,48 @@ export interface operations {
             };
         };
     };
-    getRbacRoles: {
+    changeMemberRole: {
         parameters: {
             query?: never;
             header?: never;
-            path?: never;
+            path: {
+                id: string;
+            };
             cookie?: never;
         };
-        requestBody?: never;
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ChangeMemberRoleRequest"];
+            };
+        };
         responses: {
-            /** @description Role catalog */
+            /** @description Role changed successfully */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["RoleCatalogResponse"];
+                    "application/json": components["schemas"]["ChangeMemberRoleResponse"];
                 };
             };
         };
     };
-    changeMemberRole: {
+    getRbacRoles: {
         parameters: {
             query?: never;
             header?: never;
-            path: {
-                id: string;
-            };
+            path?: never;
             cookie?: never;
         };
-        requestBody: {
-            content: {
-                "application/json": components["schemas"]["ChangeMemberRoleRequest"];
-            };
-        };
+        requestBody?: never;
         responses: {
-            /** @description Role changed successfully */
+            /** @description Role catalog */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ChangeMemberRoleResponse"];
+                    "application/json": components["schemas"]["RoleCatalogResponse"];
                 };
             };
         };

package/src/dispatch/index.ts

@@ -0,0 +1,99 @@
+/**
+ * Dispatch-deny vocabulary.
+ *
+ * The four deny paths on the agent-action dispatch flow — consent missing,
+ * write-tier disabled, per-provider kill switch, and execution-budget
+ * exhausted — all return the canonical `ErrorResponse` envelope with one of
+ * the codes defined below plus a per-code `meta` payload. The shapes are
+ * shared between the backend (which emits) and the app (which renders a
+ * recovery affordance), so they live in contracts per the promotion rule.
+ *
+ * HTTP status is carried by the envelope, not duplicated here; conventional
+ * mapping in the backend:
+ *   - `incremental_consent_required` → 402 (grant required to proceed)
+ *   - `write_tier_disabled`          → 403
+ *   - `provider_access_denied`       → 403
+ *   - `execution_budget_exceeded`    → 429
+ *
+ * @see ../errors/index.ts for the `ErrorResponse` envelope.
+ * @see PRD-00519/00521/00522 — the PRDs that introduced these denies.
+ */
+
+export const DISPATCH_DENY_CODES = [
+  'incremental_consent_required',
+  'write_tier_disabled',
+  'provider_access_denied',
+  'execution_budget_exceeded',
+] as const;
+
+export type DispatchDenyCode = (typeof DISPATCH_DENY_CODES)[number];
+
+export type ActionTier = 'SAFE' | 'EXTERNAL' | 'DESTRUCTIVE';
+
+/**
+ * The user has no active grant row in `incremental_consents` for the
+ * `(user_id, org_id, action_id)` triple. Recoverable by the user: they
+ * POST `grantPath` to create the grant, then retry the original action.
+ */
+export interface IncrementalConsentRequiredMeta {
+  actionId: string;
+  tier: ActionTier;
+  requiredScopes: string[];
+  /** HTTP path the app can POST to with `{ actionId }` to create the grant. */
+  grantPath: string;
+}
+
+/**
+ * The global `WRITE_TIER_ENABLED[tier]` kill switch is off. Recoverable
+ * only by an operator flipping the config — not user-actionable.
+ */
+export interface WriteTierDisabledMeta {
+  actionId: string;
+  tier: ActionTier;
+}
+
+/**
+ * Distinct reasons `ProviderAccessGate.canDispatchAction` can deny.
+ * Kept separate from the global `WRITE_TIER_ENABLED` codes so the app
+ * can phrase the message by cause (provider paused vs. org override vs.
+ * tier paused for this provider).
+ */
+export type ProviderAccessDenyReason =
+  | 'provider-disabled'
+  | 'org-override'
+  | 'tier-SAFE-disabled'
+  | 'tier-EXTERNAL-disabled'
+  | 'tier-DESTRUCTIVE-disabled'
+  | 'write-tier-SAFE-globally-disabled'
+  | 'write-tier-EXTERNAL-globally-disabled'
+  | 'write-tier-DESTRUCTIVE-globally-disabled';
+
+export interface ProviderAccessDeniedMeta {
+  reason: ProviderAccessDenyReason;
+  provider: string;
+  tier: ActionTier;
+  actionType: string;
+}
+
+/**
+ * The signed execution has hit one of its atomic per-run caps. `kind` tells
+ * the app which cap tripped so it can phrase the message correctly; the
+ * recovery is always "start a new session / execution".
+ */
+export interface ExecutionBudgetExceededMeta {
+  kind: 'token_uses' | 'time_window' | 'provider_calls' | 'rows_returned';
+  executionId: string;
+}
+
+/** Type-level map: deny code → meta shape. Drives the app's deny renderer. */
+export interface DispatchDenyMetaByCode {
+  incremental_consent_required: IncrementalConsentRequiredMeta;
+  write_tier_disabled: WriteTierDisabledMeta;
+  provider_access_denied: ProviderAccessDeniedMeta;
+  execution_budget_exceeded: ExecutionBudgetExceededMeta;
+}
+
+/** Narrow `unknown` to a `DispatchDenyCode` for error-code dispatch switches. */
+export function isDispatchDenyCode(code: unknown): code is DispatchDenyCode {
+  return typeof code === 'string' && (DISPATCH_DENY_CODES as readonly string[]).includes(code);
+}

package/src/index.ts

@@ -166,6 +166,22 @@ export type {
 export type { AuthStartMode, AuthStartResponse } from './auth/index'
 export { OTPErrorCode } from './auth/index'
 
+// Dispatch deny vocabulary (PRD-00519/00521/00522)
+export {
+  DISPATCH_DENY_CODES,
+  isDispatchDenyCode,
+} from './dispatch/index'
+export type {
+  ActionTier,
+  DispatchDenyCode,
+  DispatchDenyMetaByCode,
+  ExecutionBudgetExceededMeta,
+  IncrementalConsentRequiredMeta,
+  ProviderAccessDenyReason,
+  ProviderAccessDeniedMeta,
+  WriteTierDisabledMeta,
+} from './dispatch/index'
+
 // Email domain types
 // @see ADR-CONT-034 for design rationale
 export type {