@company-semantics/contracts 100.0.0 → 101.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "100.0.0",
+  "version": "101.0.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 = '7e0143b235a3' as const;
-export const SPEC_HASH_FULL = '7e0143b235a3cc79cc020305bc8e4cf82c7784774cff280504fe70c0e9ee9a81' as const;
+export const SPEC_HASH = '2a364932e5ca' as const;
+export const SPEC_HASH_FULL = '2a364932e5ca5fb988423a06d4c58a57c255317be05c842237ce045260d2dd93' as const;

package/src/api/generated.ts

@@ -7469,11 +7469,13 @@ export interface components {
                 /** @enum {string} */
                 kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
                 /** @enum {string} */
-                reason: "updates_ready" | "updates_ready_partial" | "updates_applied" | "stopped_by_user" | "paused_billing" | "run_ceiling_reached" | "pricing_unconfigured" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                reason: "updates_ready" | "updates_ready_partial" | "updates_applied" | "updates_applied_partial" | "apply_refused" | "stopped_by_user" | "paused_billing" | "run_ceiling_reached" | "pricing_unconfigured" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
                 facts: {
                     scopeCount: number;
                     violationCount: number;
                     notLandedCount: number;
+                    appliedDocCount: number | null;
+                    notAppliedDocCount: number | null;
                 } | null;
                 disposition: {
                     /** @constant */
@@ -10850,7 +10852,7 @@ export interface components {
                 } | null;
                 approvedAt: string | null;
                 approvable: boolean;
-                blockedReason: "needs_doc_access" | null;
+                blockedReason: ("needs_approval_authority" | "needs_doc_access") | null;
             }[];
             discovery: {
                 foundThisRun: number;
@@ -10916,7 +10918,7 @@ export interface components {
                 } | null;
                 approvedAt: string | null;
                 approvable: boolean;
-                blockedReason: "needs_doc_access" | null;
+                blockedReason: ("needs_approval_authority" | "needs_doc_access") | null;
             }[];
             /** Format: uuid */
             workflowId: string;
@@ -11045,7 +11047,7 @@ export interface components {
                 } | null;
                 approvedAt: string | null;
                 approvable: boolean;
-                blockedReason: "needs_doc_access" | null;
+                blockedReason: ("needs_approval_authority" | "needs_doc_access") | null;
             }[];
         };
         SourceSyncApplyResponse: {
@@ -11106,7 +11108,7 @@ export interface components {
                 } | null;
                 approvedAt: string | null;
                 approvable: boolean;
-                blockedReason: "needs_doc_access" | null;
+                blockedReason: ("needs_approval_authority" | "needs_doc_access") | null;
             }[];
         };
         SourceSyncRulesResponse: {
@@ -11547,7 +11549,12 @@ export interface components {
                 grantedByLabel: string | null;
                 /** Format: date-time */
                 grantedAt: string;
-                suspendedReason: ("grantor_lost_authority" | "spend_cap_reached" | "connection_lost") | null;
+                suspendedReason: ("grantor_lost_authority" | "grantor_lost_doc_access" | "spend_cap_reached" | "connection_lost") | null;
+            }[];
+            grantability: {
+                scopeKey: string;
+                grantable: boolean;
+                blockedReason: ("needs_approval_authority" | "needs_doc_access") | null;
             }[];
         };
         SourceSyncStandingOrder: {
@@ -11560,7 +11567,7 @@ export interface components {
             grantedByLabel: string | null;
             /** Format: date-time */
             grantedAt: string;
-            suspendedReason: ("grantor_lost_authority" | "spend_cap_reached" | "connection_lost") | null;
+            suspendedReason: ("grantor_lost_authority" | "grantor_lost_doc_access" | "spend_cap_reached" | "connection_lost") | null;
         };
         SourceSyncPutStandingOrderRequest: {
             /** @enum {string} */
@@ -21463,6 +21470,13 @@ export interface operations {
                 };
                 content?: never;
             };
+            /** @description A scope the caller may not approve (SOURCE_SYNC_SCOPE_NOT_YOURS), or one whose document the caller cannot upload to and edit (SOURCE_SYNC_SCOPE_DOC_ACCESS_DENIED) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
             /** @description The set is not the org’s */
             404: {
                 headers: {

package/src/index.ts

@@ -57,67 +57,9 @@ export type {
   AggregatedCapabilities,
 } from "./system/index";
 
-// Guard types (CI guard vocabulary)
-// @see schemas/guard-result.schema.json for JSON Schema
-export type {
-  GuardMessage,
-  GuardTierResult,
-  GuardTier,
-  GuardResults,
-  CheckResult,
-  GuardOutput,
-  RoleLimit,
-  GuardConfig,
-  GuardCheck,
-  GuardCheckFactory,
-  BoundGuardCheck,
-  GuardCheckRegistry,
-  StructuralBaselines,
-  ScriptsDepsBaseline,
-  EvolutionBaselines,
-  ContractsFreshnessBaseline,
-  MetaBaselines,
-  // Aggregate evolution types
-  DomainAggregateBaseline,
-  AggregateEvolutionConfig,
-  // SOC 2 Compliance types
-  Soc2ControlArea,
-  Soc2ControlStatus,
-  Soc2ControlResult,
-  Soc2ComplianceOutput,
-  // SOC 2 Guard Configuration types
-  SecretsDetectionConfig,
-  StructuredLoggingConfig,
-  AlertsConfigGuardConfig,
-  BackupConfigGuardConfig,
-  Soc2Baselines,
-} from "./guards/index";
-
-export {
-  GUARD_SCHEMA_VERSION,
-  GUARD_TIERS,
-  DEFAULT_SKIP_DIRECTORIES,
-  DEFAULT_DOMAIN_SECTIONS,
-  DEFAULT_INFRA_SECTIONS,
-  // SOC 2 Compliance constants
-  SOC2_CONTROL_NAMES,
-  REQUIRED_SOC2_CONTROLS,
-  BLOCKING_SOC2_CONTROLS,
-  SOC2_SCHEMA_VERSION,
-} from "./guards/index";
-
-// Cross-repo CI aggregation vocabulary
-// @see ADR-CONT-033 for contracts boundary rationale
-// Note: GuardTier is already exported above from './guards/index' (structurally
-// identical); not re-exported here to avoid a duplicate-identifier collision.
-export type { GuardResultPayload, RepoCiResult } from "./ci-results/index";
-
-export { assertRepoCiResultConsistent } from "./ci-results/index";
-
-// Compatibility manifest (CI guard vocabulary)
-// @see ADR-2025-12-011 for design rationale
-export { COMPATIBILITY } from "./compatibility";
-export type { Compatibility, Deprecation } from "./compatibility";
+// CI guard, CI aggregation and compatibility vocabulary — see
+// ./root-exports/ci-governance.ts.
+export * from "./root-exports/ci-governance";
 
 // User identity types and functions
 // @see ADR-CONT-032 for design rationale
@@ -232,21 +174,13 @@ export {
 export type { PrincipalRef } from "./identity/index";
 
 // Auth domain types
+// Named, not starred: identity/index re-exports AuthStartResponse, and the
+// export guard reads the identity names from this file's named lists.
 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";
+export * from "./dispatch/index";
 
 // Named re-export lists for the rest of the root surface live in
 // ./root-exports/, one slice per theme, each re-exported whole below. A slice

package/src/org/capability-schemas.ts

@@ -0,0 +1,118 @@
+/**
+ * Capability Schemas
+ *
+ * Zod schemas for the viewer's mutation capabilities (GET /api/capabilities).
+ * Re-exported from `./schemas`, the one import path for every org schema.
+ */
+import { z } from "zod";
+import { AI_PAUSE_REASONS } from "../billing/vocabulary";
+
+// =============================================================================
+// 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,
+      }),
+      // Entity ownership-transfer overrides (backend ADR-BE-259) +
+      // sharing-management custody (backend ADR-BE-288). Optional so older
+      // backends that don't derive them still validate. manageSharing gates the
+      // admin Share affordance on content the admin may not be able to view.
+      companyMd: z
+        .object({
+          transferOwnership: ActionCapabilitySchema,
+          manageSharing: ActionCapabilitySchema,
+        })
+        .optional(),
+      workItem: z
+        .object({
+          transferOwnership: ActionCapabilitySchema,
+          manageSharing: ActionCapabilitySchema,
+        })
+        .optional(),
+      meetingRecording: z
+        .object({
+          manageSharing: ActionCapabilitySchema,
+        })
+        .optional(),
+    })
+    .optional(),
+  // Gates the chat composer's mention affordance (PRD-00988). Optional for the
+  // same rollout symmetry as the action sub-objects above: a backend that does
+  // not yet derive the flag must still validate its own response, and the spec
+  // already carried the field before this schema did.
+  chatMentions: z.boolean().optional(),
+  // Gates the multi-party chat affordances — the participant header, the invite
+  // flow, speaker labels (PRD-00990/00991). Optional for the same rollout
+  // symmetry as `chatMentions` directly above, and it REQUIRES `chatMentions`:
+  // inviting someone is a mention, so multi-party without mentions is not a
+  // state the backend derives. The two are resolved from ONE flag read, not
+  // two — the capabilities route holds a hard 4-query budget for a P0 own-data
+  // read, and `chatMentions` already took the fourth slot.
+  chatMultiParty: z.boolean().optional(),
+  // Gates every AI affordance at once (PRD-01002). Optional for the same
+  // rollout symmetry as the flags above. It is deliberately a CAPABILITY and
+  // not a billing read: the UI needs to know whether to offer AI and what to
+  // say when it cannot, and nothing more — the balance, the ledger and the
+  // recovery live behind the billing endpoints, which an ordinary member has
+  // no right to. `reason` is the one AiPauseReason a human can act on, and it
+  // is null exactly when `aiPaused` is false.
+  billing: z
+    .object({
+      aiPaused: z.boolean(),
+      reason: z.enum(AI_PAUSE_REASONS).nullable(),
+    })
+    .optional(),
+});
+
+export type FieldCapability = z.infer<typeof FieldCapabilitySchema>;
+export type ActionCapability = z.infer<typeof ActionCapabilitySchema>;
+export type CapabilitiesResponse = z.infer<typeof CapabilitiesResponseSchema>;

package/src/org/reporting-write-schemas.ts

@@ -0,0 +1,71 @@
+/**
+ * Reporting Write Schemas
+ *
+ * Zod response schemas for setting a seat's manager (PUT
+ * /api/reporting/positions/:positionId/manager) and for submitting the
+ * interactive chat task surface that drives such writes. Re-exported from
+ * `./schemas`, the one import path for every org schema.
+ */
+import { z } from "zod";
+import { PositionRefSchema } from "../identity/position-ref";
+
+// ---------------------------------------------------------------------------
+// PUT /api/reporting/positions/:positionId/manager
+// ---------------------------------------------------------------------------
+
+/**
+ * Response for the one idempotent set-or-clear of a seat's solid-line manager —
+ * the reporting edge the org chart is built from. Position-keyed at BOTH ends
+ * (ADR-CONTRACTS-131): `reportPositionId` is the seat whose edge moved and
+ * `manager` is the POSITION it now reports to, null after a clear. A position
+ * names a vacant seat and an accountless occupant's seat just as well as a
+ * filled one, which the retired member-or-open-role union could not.
+ *
+ * `relationshipType` is a literal rather than the identity-domain
+ * `ReportingRelationshipTypeSchema`: importing that here would invert the
+ * existing people-org-chart → org/schemas dependency and recreate the
+ * module-init cycle. This route only ever writes solid edges, so the narrower
+ * literal is also the truthful shape. (`PositionReportingRelationshipTypeSchema`
+ * in ./position-reporting carries the open {solid, dotted} vocabulary for the
+ * read model.)
+ *
+ * Distinct from team membership (RBAC scopes) and `primary_unit_id` (home
+ * unit): neither of those places a person in the reporting hierarchy.
+ * See ADR-BE-253.
+ */
+export const SetSeatManagerResponseSchema = z.object({
+  success: z.boolean(),
+  reportPositionId: z.string().uuid(),
+  manager: PositionRefSchema.nullable(),
+  relationshipType: z.literal("solid"),
+  message: z.string(),
+});
+
+export type SetSeatManagerResponse = z.infer<
+  typeof SetSeatManagerResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// POST /api/chat/interactive-tasks/submit
+// ---------------------------------------------------------------------------
+
+/**
+ * Response for submitting a filled-in interactive chat task surface (e.g. the
+ * editable "change reporting manager" form). The submit endpoint runs the
+ * Deterministic Execution & Governance Engine: it creates an execution and,
+ * when no further confirmation is required, drives it to execution in the same
+ * request. The frontend then drives the surface's lifecycle card off
+ * `executionId` (the execution-lifecycle stream), exactly like a confirmation.
+ *
+ * See ADR-CONTRACTS-068.
+ */
+export const SubmitInteractiveTaskResponseSchema = z.object({
+  /** Lifecycle record id created for this submission. */
+  executionId: z.string(),
+  /** Coarse lifecycle status at the time the request returns. */
+  status: z.enum(["executing", "completed", "failed", "pending_confirmation"]),
+});
+
+export type SubmitInteractiveTaskResponse = z.infer<
+  typeof SubmitInteractiveTaskResponseSchema
+>;