@company-semantics/contracts 1.14.0 → 1.16.0

package/package.json

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

package/src/api/generated.ts

@@ -636,7 +636,8 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /** Get workspace member detail (roles, units, effective scopes, recent actions) */
+        get: operations["getWorkspaceMemberDetail"];
         put?: never;
         post?: never;
         /** Remove workspace member */
@@ -663,6 +664,23 @@ export interface paths {
         patch: operations["changeMemberRole"];
         trace?: never;
     };
+    "/api/rbac/roles": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: 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;
+        patch?: never;
+        trace?: never;
+    };
     "/api/user/orgs": {
         parameters: {
             query?: never;
@@ -2344,7 +2362,18 @@ export interface components {
                 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;
@@ -2514,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;
@@ -2532,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;
@@ -2750,6 +2815,7 @@ export interface components {
             target: {
                 type: string;
                 workspaceId?: string;
+                service?: string;
             };
             connectionId?: string;
             returnUrl?: string;
@@ -4371,6 +4437,28 @@ export interface operations {
             };
         };
     };
+    getWorkspaceMemberDetail: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Workspace member detail */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkspaceMemberDetail"];
+                };
+            };
+        };
+    };
     removeMember: {
         parameters: {
             query?: never;
@@ -4419,6 +4507,26 @@ export interface operations {
             };
         };
     };
+    getRbacRoles: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Role catalog */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RoleCatalogResponse"];
+                };
+            };
+        };
+    };
     listUserOrgs: {
         parameters: {
             query?: never;

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 {

package/src/org/index.ts

@@ -15,6 +15,11 @@ export type {
   WorkspaceRole,
   WorkspaceOverview,
   WorkspaceMember,
+  WorkspaceMemberUnitSummary,
+  WorkspaceMemberInviteStatus,
+  WorkspaceMemberDetail,
+  MemberRecentAction,
+  RoleCatalogEntry,
   AuthMethodConfig,
   WorkspaceAuthConfig,
   // SSO self-service setup types (PRD-00193)
@@ -120,6 +125,9 @@ export {
   WorkspaceAccessResponseSchema,
   WorkspaceOverviewSchema,
   WorkspaceMembersResponseSchema,
+  WorkspaceMemberDetailSchema,
+  RoleCatalogEntrySchema,
+  RoleCatalogResponseSchema,
   WorkspaceAuthConfigSchema,
   WorkspaceAuditEventSchema,
   WorkspaceAuditResponseSchema,

package/src/org/schemas.ts

@@ -17,12 +17,48 @@ import { CursorPageSchema } from '../api/primitives';
 // Sub-schemas
 // ---------------------------------------------------------------------------
 
+const WorkspaceMemberUnitSummarySchema = z.object({
+  unitId: z.string(),
+  unitName: z.string(),
+  unitPath: z.string(),
+  role: z.enum(['owner', 'manager', 'member']),
+});
+
 const WorkspaceMemberSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string(),
   role: z.enum(['owner', 'admin', 'member', 'auditor']),
+  roleNames: z.array(z.string()),
   joinedAt: z.string(),
+  lastActiveAt: z.string().nullable(),
+  unitMemberships: z.array(WorkspaceMemberUnitSummarySchema),
+  unitMembershipsTruncated: z.boolean(),
+  inviteStatus: z.enum(['active', 'pending', 'expired']).nullable(),
+});
+
+const MemberRecentActionSchema = z.object({
+  id: z.string(),
+  timestamp: z.string(),
+  action: z.string(),
+  summary: z.string(),
+});
+
+export const WorkspaceMemberDetailSchema = WorkspaceMemberSchema.extend({
+  effectiveScopes: z.array(z.string()),
+  recentActions: z.array(MemberRecentActionSchema),
+});
+
+export const RoleCatalogEntrySchema = z.object({
+  name: z.string(),
+  type: z.enum(['system', 'custom']),
+  description: z.string(),
+  scopes: z.array(z.string()),
+  memberCount: z.number().int().nonnegative(),
+});
+
+export const RoleCatalogResponseSchema = z.object({
+  roles: z.array(RoleCatalogEntrySchema),
 });
 
 const WorkspaceOwnerSchema = z.object({

package/src/org/types.ts

@@ -92,6 +92,24 @@ export interface WorkspaceOverview {
   claimable: boolean;
 }
 
+/**
+ * Single OrgUnit membership summary attached to a WorkspaceMember row.
+ * See ADR-BE-120 for the canonical OrgUnit tree model.
+ */
+export interface WorkspaceMemberUnitSummary {
+  unitId: string;
+  unitName: string;
+  /** Human-readable path from the OrgUnit tree (e.g. "Sales / Enterprise"). */
+  unitPath: string;
+  role: 'owner' | 'manager' | 'member';
+}
+
+/**
+ * Invite status for a workspace member row. `null` for members that have no
+ * associated invite record (joined pre-invite system).
+ */
+export type WorkspaceMemberInviteStatus = 'active' | 'pending' | 'expired';
+
 /**
  * Workspace member for the members list.
  * Human users only (no agent actors).
@@ -100,8 +118,56 @@ export interface WorkspaceMember {
   id: string;
   name: string;
   email: string;
+  /** Display role — derived collapse of RBAC into {owner,admin,member,auditor}. */
   role: WorkspaceRole;
+  /** Raw RBAC role names (e.g. 'org_owner', 'org_admin', 'auditor'). Superset of `role`. */
+  roleNames: string[];
   joinedAt: string;
+  /** ISO timestamp of last activity; null if never recorded. */
+  lastActiveAt: string | null;
+  /** OrgUnit memberships for this member, capped at a small number server-side. */
+  unitMemberships: WorkspaceMemberUnitSummary[];
+  /** True when server truncated `unitMemberships`; detail endpoint returns the full list. */
+  unitMembershipsTruncated: boolean;
+  /** Invite lifecycle status. `null` for members without an invite record. */
+  inviteStatus: WorkspaceMemberInviteStatus | null;
+}
+
+/**
+ * Recent audit action attached to a member-detail response.
+ * Lighter projection than WorkspaceAuditEvent — no actor block (implied by caller).
+ */
+export interface MemberRecentAction {
+  id: string;
+  timestamp: string;
+  action: string;
+  summary: string;
+}
+
+/**
+ * Full member detail, returned by GET /api/workspace/members/:userId and also
+ * the shape projected from /api/me for self-view.
+ */
+export interface WorkspaceMemberDetail extends WorkspaceMember {
+  /** Full resolved scope patterns — union of grants from all assigned roles. */
+  effectiveScopes: string[];
+  /** Up to N most recent audit actions attributed to this member. */
+  recentActions: MemberRecentAction[];
+}
+
+/**
+ * Entry in the RBAC roles catalog (GET /api/rbac/roles).
+ */
+export interface RoleCatalogEntry {
+  /** Canonical role name, e.g. 'org_owner'. */
+  name: string;
+  type: 'system' | 'custom';
+  /** One-line description sourced from system-roles.ts (or org-provided for custom). */
+  description: string;
+  /** Scope patterns granted by this role. May contain wildcards (e.g. 'org.view_*'). */
+  scopes: string[];
+  /** Number of active assignments in the current org. */
+  memberCount: number;
 }
 
 /**