@company-semantics/contracts 1.15.0 → 1.17.0

package/package.json

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

package/src/admin/authz-simulate.ts

@@ -0,0 +1,40 @@
+/**
+ * Admin What-If Simulator — request/response schemas.
+ *
+ * Mirrors the Fastify schema for `POST /api/admin/authz/simulate`. The endpoint
+ * is read-only and returns the full structured AuthDecision verbatim, so that
+ * admins can debug denials by reading evaluator name + reason rather than
+ * guessing. See PRD-00544 and feedback_decision_logic_must_be_visible.md.
+ */
+import { z } from 'zod';
+
+export const SimulateRequest = z.object({
+  actor: z.object({
+    type: z.enum(['user', 'agent']),
+    id: z.string().uuid(),
+  }),
+  scope: z.string(),
+  resource_kind: z.enum(['system', 'org', 'team', 'member', 'doc']),
+  resource_id: z.string().uuid().optional(),
+});
+
+export type SimulateRequest = z.infer<typeof SimulateRequest>;
+
+export const SimulateResponse = z.discriminatedUnion('allow', [
+  z.object({
+    allow: z.literal(true),
+    matched_grant: z.unknown(),
+    evaluator_name: z.string().optional(),
+    evaluator_reason: z.string().optional(),
+  }),
+  z.object({
+    allow: z.literal(false),
+    deny_reasons: z.array(z.unknown()),
+    missing: z.object({
+      scope: z.string().optional(),
+      suggested_role: z.string().optional(),
+    }),
+  }),
+]);
+
+export type SimulateResponse = z.infer<typeof SimulateResponse>;

package/src/admin/direct-grants.ts

@@ -0,0 +1,31 @@
+/**
+ * Admin Direct Grants — request/response schemas.
+ *
+ * Mirrors the Fastify schemas for `POST /api/admin/grants/direct` and the
+ * persisted grant row. `granted_by` is intentionally absent from the create
+ * body — it is set by the server from the authenticated actor (see PRD-00544
+ * direct-grant-audit-trail and the `direct-grant-audit` CI guard).
+ */
+import { z } from 'zod';
+
+export const DirectGrantCreate = z.object({
+  subject_id: z.string().uuid(),
+  scope_pattern: z.string(),
+  resource_filter: z.record(z.string(), z.unknown()).optional(),
+  expires_at: z.string().datetime().optional(),
+});
+
+export type DirectGrantCreate = z.infer<typeof DirectGrantCreate>;
+
+export const DirectGrant = z.object({
+  id: z.string().uuid(),
+  org_id: z.string().uuid(),
+  subject_id: z.string().uuid(),
+  scope_pattern: z.string(),
+  source: z.literal('direct'),
+  granted_by: z.string().uuid(),
+  granted_at: z.string().datetime(),
+  expires_at: z.string().datetime().nullable(),
+});
+
+export type DirectGrant = z.infer<typeof DirectGrant>;

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 = '6edfe6e7117c' as const;
+export const SPEC_HASH_FULL = '6edfe6e7117c49e81cd7cad51ac9cd5c6f4c9e18cf7a37ff82a5630855404a00' as const;

package/src/api/generated.ts

@@ -72,6 +72,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/auth/consent/grant": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Grant incremental consent for a write action
+         * @description Records per-(user, org, action) consent for a registered write action. Idempotent: regranting an already-active consent re-emits the audit event but does not create a duplicate row.
+         */
+        post: operations["grantIncrementalConsent"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/me": {
         parameters: {
             query?: never;
@@ -647,38 +667,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": {
@@ -2036,6 +2056,15 @@ export interface components {
             /** @constant */
             ok: true;
         };
+        ConsentGrantResponse: {
+            /** @constant */
+            ok: true;
+            /** Format: date-time */
+            grantedAt: string;
+        };
+        ConsentGrantRequest: {
+            actionId: string;
+        };
         MeResponse: {
             /** Format: uuid */
             userId: string;
@@ -2355,49 +2384,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 +2572,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 +2616,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 +2844,7 @@ export interface components {
             target: {
                 type: string;
                 workspaceId?: string;
+                service?: string;
             };
             connectionId?: string;
             returnUrl?: string;
@@ -3538,6 +3581,63 @@ export interface operations {
             };
         };
     };
+    grantIncrementalConsent: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ConsentGrantRequest"];
+            };
+        };
+        responses: {
+            /** @description Consent granted */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConsentGrantResponse"];
+                };
+            };
+            /** @description Invalid or unregistered actionId */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: string;
+                        message: string;
+                    };
+                };
+            };
+            /** @description Not authenticated */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description CSRF token missing or invalid */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Rate limit exceeded */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCurrentUser: {
         parameters: {
             query?: never;
@@ -4467,48 +4567,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/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/auth/consent/grant': ['POST'],
   '/api/chats': ['GET', 'POST'],
   '/api/chats/by-interaction/{interactionId}': ['GET'],
   '/api/chats/events': ['GET'],
@@ -47,7 +48,8 @@ export const openApiRoutes = {
   '/api/internal-admin/impersonate/start': ['POST'],
   '/api/me': ['GET'],
   '/api/org-units': ['POST'],
-  '/api/org-units/{unitId}': ['GET'],
+  '/api/org-units/tree': ['GET'],
+  '/api/org-units/{unitId}': ['GET', 'PATCH'],
   '/api/org-units/{unitId}/ancestors': ['GET'],
   '/api/org-units/{unitId}/archive': ['POST'],
   '/api/org-units/{unitId}/children': ['GET'],
@@ -73,7 +75,7 @@ export const openApiRoutes = {
   '/api/orgs/{orgId}/billing': ['GET'],
   '/api/orgs/{orgId}/budget-config': ['GET', 'PUT'],
   '/api/orgs/{orgId}/level-config': ['GET', 'PUT'],
-  '/api/orgs/{orgId}/tree': ['GET'],
+  '/api/rbac/roles': ['GET'],
   '/api/scope/check': ['GET'],
   '/api/scope/check-batch': ['POST'],
   '/api/shared/{token}': ['GET'],
@@ -103,7 +105,7 @@ export const openApiRoutes = {
   '/api/workspace/invites/validate': ['GET'],
   '/api/workspace/invites/{id}': ['DELETE'],
   '/api/workspace/members': ['GET'],
-  '/api/workspace/members/{id}': ['DELETE'],
+  '/api/workspace/members/{id}': ['DELETE', 'GET'],
   '/api/workspace/members/{id}/role': ['PATCH'],
   '/api/workspace/name': ['PATCH'],
   '/api/workspace/resolve-path': ['POST'],

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 {