@company-semantics/contracts 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -115,7 +115,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^22.19.19",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.5",
     "markdownlint-cli2": "^0.22.1",

package/src/api/generated.ts

@@ -3234,7 +3234,7 @@ export interface components {
                 level: "none" | "viewer" | "commenter" | "editor";
                 reasons: {
                     /** @enum {string} */
-                    source: "org_rbac" | "sharing_policy" | "unit_baseline" | "acl_grant" | "doc_ownership";
+                    source: "org_rbac" | "sharing_policy" | "unit_baseline" | "unit_delegation" | "acl_grant" | "doc_ownership";
                     detail: string;
                 }[];
                 canShare: boolean;

package/src/generated/openapi-routes.ts

@@ -57,14 +57,19 @@ export const openApiRoutes = {
   '/api/org-units/{unitId}/ancestors': ['GET'],
   '/api/org-units/{unitId}/archive': ['POST'],
   '/api/org-units/{unitId}/children': ['GET'],
+  '/api/org-units/{unitId}/delegations': ['POST'],
+  '/api/org-units/{unitId}/delegations/{id}': ['DELETE', 'PATCH'],
   '/api/org-units/{unitId}/descendants': ['GET'],
   '/api/org-units/{unitId}/memberships': ['GET', 'POST'],
   '/api/org-units/{unitId}/memberships/{userId}': ['DELETE'],
   '/api/org-units/{unitId}/memberships/{userId}/role': ['PUT'],
+  '/api/org-units/{unitId}/owners': ['GET'],
   '/api/org-units/{unitId}/permissions': ['GET'],
   '/api/org-units/{unitId}/relationships': ['GET', 'POST'],
   '/api/org-units/{unitId}/reorder': ['POST'],
   '/api/org-units/{unitId}/reparent': ['POST'],
+  '/api/org-units/{unitId}/structural-leaders': ['POST'],
+  '/api/org-units/{unitId}/structural-leaders/{userId}': ['DELETE'],
   '/api/org/cancel-deletion': ['POST'],
   '/api/org/delete': ['POST'],
   '/api/org/deletion-eligibility': ['GET'],
@@ -75,6 +80,8 @@ export const openApiRoutes = {
   '/api/org/transfer-ownership/accept': ['POST'],
   '/api/org/transfer-ownership/preview': ['POST'],
   '/api/org/transfer-ownership/status': ['GET'],
+  '/api/orgs/{orgId}/admins': ['POST'],
+  '/api/orgs/{orgId}/admins/{userId}': ['DELETE'],
   '/api/orgs/{orgId}/ai-usage': ['GET'],
   '/api/orgs/{orgId}/billing': ['GET'],
   '/api/orgs/{orgId}/budget-config': ['GET', 'PUT'],
@@ -93,6 +100,8 @@ export const openApiRoutes = {
   '/api/user/profile': ['PATCH'],
   '/api/user/resync-slack-avatar': ['POST'],
   '/api/users/org-chart': ['GET'],
+  '/api/users/org-chart/import': ['POST'],
+  '/api/users/org-chart/import/{operationId}/retry': ['POST'],
   '/api/work-items/{id}': ['GET'],
   '/api/work-items/{id}/content': ['PUT'],
   '/api/work-items/{id}/title': ['PUT'],

package/src/index.ts

@@ -663,7 +663,8 @@ export { openApiRoutes, type OpenApiRoute, type OpenApiMethod } from './generate
 export type { Secret } from './security/index'
 export { wrapSecret, unwrapSecret } from './security/index'
 
-// Org Secrets DTO schemas (PRD-00629) — masked-prefix-only, no value field
+// Org secrets DTO schemas (PRD-00629)
+// @see src/security/org-secrets.ts for invariants (no value field on summary)
 export {
   UsageClassSchema,
   OrgSecretsActionSchema,
@@ -672,7 +673,7 @@ export {
   CreateSecretRequestSchema,
   RotateSecretRequestSchema,
   DisableSecretRequestSchema,
-} from './security/org-secrets'
+} from './security/index'
 export type {
   UsageClass,
   OrgSecretsAction,
@@ -681,7 +682,7 @@ export type {
   CreateSecretRequest,
   RotateSecretRequest,
   DisableSecretRequest,
-} from './security/org-secrets'
+} from './security/index'
 
 // Analytics response metadata (shared vocabulary for OLTP/OLAP separation)
 // @see ADR-CTRL-053 for design rationale
@@ -742,3 +743,7 @@ export type {
   ControllerInput,
   ControllerOutput,
 } from './autotune'
+
+// Meeting recorder vocabulary (PRD-00651)
+// @see ./meetings/schemas.ts for invariants
+export * from './meetings'

package/src/meetings/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Meeting recorder vocabulary barrel (PRD-00651).
+ *
+ * @see ./schemas.ts for the full schema definitions and invariants.
+ */
+export {
+  RecordingIdSchema,
+  RecordingSourceSchema,
+  DetectedMeetingAppSchema,
+  TranscriptionProviderSchema,
+  RecordingStatusSchema,
+  RecordingQualitySchema,
+  MeetingVisibilitySchema,
+  SourceSegmentSchema,
+  TranscriptChunkSchema,
+  RecordingEventSchema,
+  TranscriptionSessionGrantSchema,
+  MeetingMetadataProjectionSchema,
+} from './schemas';
+
+export type {
+  RecordingId,
+  RecordingSource,
+  DetectedMeetingApp,
+  TranscriptionProvider,
+  RecordingStatus,
+  RecordingQuality,
+  MeetingVisibility,
+  SourceSegment,
+  TranscriptChunk,
+  RecordingEvent,
+  TranscriptionSessionGrant,
+  MeetingMetadataProjection,
+} from './schemas';

package/src/meetings/schemas.ts

@@ -0,0 +1,276 @@
+/**
+ * Meeting recorder shared vocabulary (PRD-00651).
+ *
+ * Zod schemas for the meeting capture / transcription pipeline. Consumed by
+ * the mac shell (capture runtime), backend (persistence + event projection),
+ * and app (UI surfaces). Lives in contracts because the boundary crosses
+ * three independent repos and breaking it would require coordinated releases
+ * (see CONTRACTS_POLICY.md promotion rule).
+ *
+ * INVARIANTS this vocabulary enforces:
+ *   - RecordingId is the unified trace key (INV-MTG-7) — ULID, sortable,
+ *     opaque to consumers.
+ *   - The transcription grant is provider-agnostic (INV-MTG-15): the mac
+ *     shell never sees a provider name; only `connectUrl` + `authHeaders` +
+ *     audio config.
+ *   - Visibility is meeting-scoped by default (`meeting_only`) and only
+ *     widens via explicit policy decisions.
+ *
+ * Per the durable user preference `feedback_structured_metadata_not_json_strings`,
+ * descriptions live in `.meta({ description })` — structured metadata, not
+ * stringified JSON blobs on the schema.
+ */
+import { z } from 'zod';
+
+// =============================================================================
+// Recording identity
+// =============================================================================
+
+/**
+ * ULID (Crockford base32, 26 chars). Used as the unified trace key spanning
+ * mac → backend → app per INV-MTG-7. Sortable by encoded timestamp prefix so
+ * recordings can be ordered without a separate `createdAt` column read.
+ */
+export const RecordingIdSchema = z
+  .string()
+  .regex(/^[0-9A-HJKMNP-TV-Z]{26}$/, 'ULID required')
+  .meta({ description: 'ULID; unified trace key for the recording (INV-MTG-7).' });
+export type RecordingId = z.infer<typeof RecordingIdSchema>;
+
+// =============================================================================
+// Enums (vocabulary)
+// =============================================================================
+
+/** Which capture stream a chunk came from. Two channels: mic (channel 0) and system (channel 1). */
+export const RecordingSourceSchema = z.enum(['mic', 'system']).meta({
+  description: 'Capture stream identity. Mic = channel 0, system audio = channel 1.',
+});
+export type RecordingSource = z.infer<typeof RecordingSourceSchema>;
+
+/**
+ * Which meeting app the system audio is coming from. `manual` covers the
+ * "user started a recording with no detected app" debug path. The
+ * `meet-browser` variant covers Google Meet running inside a browser tab,
+ * which the BrowserAudioDetector heuristic identifies (PRD-00655).
+ */
+export const DetectedMeetingAppSchema = z
+  .enum(['zoom', 'teams', 'meet-browser', 'slack-huddle', 'manual'])
+  .meta({ description: 'Auto-detected meeting app that owns the system audio stream.' });
+export type DetectedMeetingApp = z.infer<typeof DetectedMeetingAppSchema>;
+
+/**
+ * Transcription provider class. The mac shell never sees this — it's a
+ * backend / app concern for routing + billing visibility (INV-MTG-15 ensures
+ * the mac side stays provider-opaque).
+ */
+export const TranscriptionProviderSchema = z
+  .enum(['deepgram', 'assemblyai', 'whisper-local'])
+  .meta({ description: 'Server-side selection of transcription provider; never crosses to mac.' });
+export type TranscriptionProvider = z.infer<typeof TranscriptionProviderSchema>;
+
+/**
+ * Lifecycle states for a recording entity. `partial-transcript-network` is
+ * the explicit non-binary state for "audio captured but the transcript
+ * stream dropped mid-session" — keeping it distinct from `failed` lets the
+ * UI surface a remediation hint without losing the captured artifact.
+ */
+export const RecordingStatusSchema = z
+  .enum([
+    'draft',
+    'recording',
+    'processing',
+    'finalized',
+    'failed',
+    'partial-transcript-network',
+    'cancelled',
+  ])
+  .meta({ description: 'Coarse lifecycle state for a recording entity.' });
+export type RecordingStatus = z.infer<typeof RecordingStatusSchema>;
+
+/** Quality signal emitted by the capture runtime. Used to surface degradation in the UI. */
+export const RecordingQualitySchema = z.enum(['clean', 'degraded']).meta({
+  description: 'Capture-runtime quality signal. `degraded` triggers a UI hint.',
+});
+export type RecordingQuality = z.infer<typeof RecordingQualitySchema>;
+
+/**
+ * Visibility band for the finalized meeting projection. `meeting_only` is the
+ * default — captured material stays visible only to attendees of the meeting
+ * itself. `shared` opens it to anyone the owner explicitly shares with;
+ * `org` opens it to the org; `finalized_private` is the explicit "private
+ * even after finalization" lock per the participant-only constraint
+ * (`feedback_retrieval_default_off_for_noisy_sources`).
+ */
+export const MeetingVisibilitySchema = z
+  .enum(['meeting_only', 'shared', 'org', 'finalized_private'])
+  .meta({
+    description:
+      'Visibility band for the finalized meeting projection. Default `meeting_only`.',
+  });
+export type MeetingVisibility = z.infer<typeof MeetingVisibilitySchema>;
+
+// =============================================================================
+// Source segments (the per-capture-stream view of a recording)
+// =============================================================================
+
+/**
+ * A continuous segment captured from a single stream within a recording.
+ * One recording has at least one segment per active source. New segments
+ * are emitted when the upstream signal pauses and resumes.
+ */
+export const SourceSegmentSchema = z
+  .object({
+    recordingId: RecordingIdSchema,
+    source: RecordingSourceSchema,
+    sequence: z.number().int().nonnegative(),
+    startedAtMs: z.number().int().nonnegative(),
+    endedAtMs: z.number().int().nonnegative().nullable(),
+    sampleRateHz: z.literal(16000),
+    channels: z.literal(1),
+  })
+  .meta({ description: 'Per-source continuous capture segment within a recording.' });
+export type SourceSegment = z.infer<typeof SourceSegmentSchema>;
+
+// =============================================================================
+// Transcript chunks (the per-window result of transcription)
+// =============================================================================
+
+/**
+ * A single transcript window from the provider. `final = true` means the
+ * provider has committed to this text; `false` is an interim hypothesis.
+ * The mac shell forwards both kinds — the UI is responsible for collapsing
+ * interim results on top of the latest commit.
+ */
+export const TranscriptChunkSchema = z
+  .object({
+    recordingId: RecordingIdSchema,
+    source: RecordingSourceSchema,
+    sequence: z.number().int().nonnegative(),
+    startedAtMs: z.number().int().nonnegative(),
+    endedAtMs: z.number().int().nonnegative(),
+    text: z.string(),
+    final: z.boolean(),
+    speakerLabel: z.string().nullable().optional(),
+    confidence: z.number().min(0).max(1).optional(),
+  })
+  .meta({ description: 'A single transcript window (interim or final) from the provider.' });
+export type TranscriptChunk = z.infer<typeof TranscriptChunkSchema>;
+
+// =============================================================================
+// Recording events (the event stream that drives backend persistence)
+// =============================================================================
+
+const SessionOpenedEventSchema = z.object({
+  kind: z.literal('session_opened'),
+  recordingId: RecordingIdSchema,
+  atMs: z.number().int().nonnegative(),
+});
+
+const ChunkBatchEventSchema = z.object({
+  kind: z.literal('chunk_batch'),
+  recordingId: RecordingIdSchema,
+  chunks: z.array(TranscriptChunkSchema).min(1),
+});
+
+const QualityDegradedEventSchema = z.object({
+  kind: z.literal('quality_degraded'),
+  recordingId: RecordingIdSchema,
+  reason: z.string().min(1),
+  atMs: z.number().int().nonnegative(),
+});
+
+const SessionStoppedEventSchema = z.object({
+  kind: z.literal('session_stopped'),
+  recordingId: RecordingIdSchema,
+  atMs: z.number().int().nonnegative(),
+  expectedLastSequence: z.number().int().nonnegative(),
+});
+
+/**
+ * Discriminated union of events emitted by the mac shell during a recording
+ * session. The backend consumes these and projects them onto the
+ * `MeetingMetadataProjection` row.
+ *
+ * Ordering invariant: `session_opened` is always the first event for a
+ * recordingId; `session_stopped` is always the last. `chunk_batch` and
+ * `quality_degraded` may interleave.
+ */
+export const RecordingEventSchema = z
+  .discriminatedUnion('kind', [
+    SessionOpenedEventSchema,
+    ChunkBatchEventSchema,
+    QualityDegradedEventSchema,
+    SessionStoppedEventSchema,
+  ])
+  .meta({
+    description:
+      'Event emitted by the capture runtime during a recording session (INV-MTG ordering).',
+  });
+export type RecordingEvent = z.infer<typeof RecordingEventSchema>;
+
+// =============================================================================
+// Transcription session grant (provider-agnostic handshake)
+// =============================================================================
+
+/**
+ * Server-issued grant that authorizes the mac shell to open a WebSocket to
+ * the transcription provider. Per INV-MTG-15 the mac never sees a provider
+ * name — only `connectUrl`, `authHeaders`, and the audio config it must
+ * speak. `authHeaders` carries an ephemeral token; rotation is the server's
+ * job, and the grant has a short `expiresAt`.
+ */
+export const TranscriptionSessionGrantSchema = z
+  .object({
+    sessionId: RecordingIdSchema,
+    connectUrl: z.string().url(),
+    authHeaders: z.record(z.string(), z.string()),
+    expiresAt: z.string().datetime(),
+    audioConfig: z.object({
+      sampleRateHz: z.literal(16000),
+      channels: z.literal(2),
+      encoding: z.literal('linear16'),
+      chunkMs: z.literal(200),
+    }),
+    capabilities: z.object({
+      interimResults: z.boolean(),
+      multichannelDiarization: z.boolean(),
+      reconnectionTokens: z.boolean(),
+    }),
+  })
+  .meta({
+    description:
+      'Provider-agnostic grant the mac shell consumes. Mac never sees provider name (INV-MTG-15).',
+  });
+export type TranscriptionSessionGrant = z.infer<typeof TranscriptionSessionGrantSchema>;
+
+// =============================================================================
+// Meeting metadata projection (finalized read model)
+// =============================================================================
+
+/**
+ * Finalized projection row for a completed recording. This is what the app
+ * reads for the meeting list / detail views. Drafts and in-flight recordings
+ * are excluded from this projection per
+ * `feedback_live_document_semantics` — indexers filter on `status` to
+ * suppress drafts from the search authority.
+ */
+export const MeetingMetadataProjectionSchema = z
+  .object({
+    recordingId: RecordingIdSchema,
+    ownerUserId: z.string().uuid(),
+    orgId: z.string().uuid(),
+    title: z.string().nullable(),
+    detectedApp: DetectedMeetingAppSchema,
+    visibility: MeetingVisibilitySchema,
+    status: RecordingStatusSchema,
+    quality: RecordingQualitySchema,
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime().nullable(),
+    durationMs: z.number().int().nonnegative(),
+    participantUserIds: z.array(z.string().uuid()),
+    transcriptAvailable: z.boolean(),
+  })
+  .meta({
+    description: 'Finalized read projection for a recording (excludes drafts).',
+  });
+export type MeetingMetadataProjection = z.infer<typeof MeetingMetadataProjectionSchema>;

package/src/org/__tests__/org-units.test.ts

@@ -98,7 +98,7 @@ describe('OrgUnitMembershipSchema', () => {
       orgId: UUID_B,
       unitId: UUID_C,
       userId: UUID_A,
-      membershipRole: 'manager',
+      membershipRole: 'l1_unit_owner',
       status: 'active',
       source: 'google_groups',
       sourceRef: 'eng@example.com',
@@ -226,7 +226,7 @@ describe('Enum exhaustiveness', () => {
 describe('OrgUnitPermissionsEntrySchema', () => {
   const entry = {
     userId: UUID_A,
-    membershipRole: 'manager' as const,
+    membershipRole: 'l1_unit_owner' as const,
     inheritedFromUnitId: UUID_C,
     inheritedFromUnitName: 'Engineering',
   };

package/src/security/org-secrets.ts

@@ -1,27 +1,30 @@
 /**
- * Org Secrets — DTO schemas
+ * Org Secrets DTO schemas (PRD-00629).
  *
- * Zod schemas for the org_secrets surface (PRD-00629). The contracts package
- * defines what admin clients may observe and submit. The decrypted credential
- * value is intentionally absent from every surface here — the only
- * credential-derived field exposed is `maskedPrefix`.
+ * Wire shapes for the `org_secrets` admin surface. The decrypted credential
+ * value never crosses this boundary — `OrgSecretSummarySchema` exposes only a
+ * masked prefix derived from the plaintext (e.g. the first few characters of
+ * `sk-...`), never the value itself. Plaintext travels INTO the server through
+ * `CreateSecretRequestSchema` / `RotateSecretRequestSchema` via
+ * `SecretValueStringSchema`, which is a branded bounded string so accidental
+ * propagation through logs / template literals is obvious in code review.
  *
- * Servers receiving plaintext (CreateSecretRequest / RotateSecretRequest)
- * are expected to wrap it with {@link Secret} from `./secret` before storage,
- * and never re-emit it to clients.
+ * Server is expected to wrap incoming `plaintext` in `Secret<T>` (see
+ * `./secret.ts`) before storage / encryption.
  */
 import { z } from 'zod';
 
 /**
- * Classification of how a credential is consumed at runtime. Drives downstream
- * authorization and audit categorization.
+ * Usage class of an org secret. Drives which resolver layer is allowed to read
+ * the value (AI provider keys, webhook signing secrets, generic credentials).
  */
 export const UsageClassSchema = z.enum(['AI_PROVIDER', 'WEBHOOK_SIGNING', 'GENERIC']);
 export type UsageClass = z.infer<typeof UsageClassSchema>;
 
 /**
- * Auditable lifecycle and access events for an org secret. Used by the audit
- * trail and observability surfaces; the schema is the closed enumeration.
+ * Audit-log action vocabulary for `org_secrets_audit_log`. Includes both
+ * lifecycle events (`created`, `rotated`, `disabled`, `enabled`) and access
+ * signals (`access_denied`, `explicit_export`, `unusual_access`).
  */
 export const OrgSecretsActionSchema = z.enum([
   'created',
@@ -34,30 +37,34 @@ export const OrgSecretsActionSchema = z.enum([
 ]);
 export type OrgSecretsAction = z.infer<typeof OrgSecretsActionSchema>;
 
+declare const SecretValueStringBrand: unique symbol;
+
 /**
- * Branded plaintext credential string. Bounded so accidental logs do not leak
- * megabytes; branded to discourage propagation through generic string flows.
- * Servers must wrap with Secret<T> before storage and never echo it back.
+ * Plaintext credential string. Bounded (min 1, max 8192 chars) so accidental
+ * logs cannot leak megabytes, and branded so propagation outside the secrets
+ * domain is visible at the type level. Server MUST wrap in `Secret<T>` before
+ * storage so the multi-surface redaction protection applies.
  */
 export const SecretValueStringSchema = z
   .string()
   .min(1)
   .max(8192)
-  .brand<'SecretValueString'>();
+  .brand<typeof SecretValueStringBrand>();
 export type SecretValueString = z.infer<typeof SecretValueStringSchema>;
 
 /**
- * Admin-visible summary of an `org_secrets` row. The decrypted value is
- * intentionally absent — `maskedPrefix` is the only credential-derived field
- * exposed by this surface (INV-PRD-00629: no value in summary).
+ * Admin-facing summary of an `org_secrets` row.
  *
- * `usageCount` is serialized as a string for cross-driver bigint safety.
+ * INVARIANT: this schema MUST NOT contain the decrypted `value`. The only
+ * credential-derived field exposed is `maskedPrefix`, a short, lossy preview.
+ * Adding a `value` field here would defeat the purpose of the whole subsystem;
+ * the secrets API never decrypts to clients.
  */
 export const OrgSecretSummarySchema = z.object({
   id: z.string().uuid(),
   orgId: z.string().uuid().nullable(),
   usageClass: UsageClassSchema,
-  secretName: z.string().min(1).max(128),
+  secretName: z.string().min(1),
   maskedPrefix: z.string().min(1).max(64),
   version: z.number().int().positive(),
   enabled: z.boolean(),
@@ -69,8 +76,9 @@ export const OrgSecretSummarySchema = z.object({
 export type OrgSecretSummary = z.infer<typeof OrgSecretSummarySchema>;
 
 /**
- * Request to create a new org secret. Server-side handlers must wrap
- * `plaintext` in Secret<T> immediately on receipt.
+ * Request body for `POST /api/admin/secrets`. `orgId` is nullable so global
+ * (platform-wide) secrets are expressible. `plaintext` is the only field that
+ * carries credential material; everything else is metadata.
  */
 export const CreateSecretRequestSchema = z.object({
   orgId: z.string().uuid().nullable(),
@@ -82,7 +90,9 @@ export const CreateSecretRequestSchema = z.object({
 export type CreateSecretRequest = z.infer<typeof CreateSecretRequestSchema>;
 
 /**
- * Request to rotate an existing secret to a new plaintext value.
+ * Request body for `POST /api/admin/secrets/:id/rotate`. Re-supplies the
+ * plaintext under a new version; the previous version is retained per the
+ * rotation policy documented in the schema migration.
  */
 export const RotateSecretRequestSchema = z.object({
   newPlaintext: SecretValueStringSchema,
@@ -91,8 +101,9 @@ export const RotateSecretRequestSchema = z.object({
 export type RotateSecretRequest = z.infer<typeof RotateSecretRequestSchema>;
 
 /**
- * Request to disable an existing secret. A non-empty `reason` is required so
- * the audit trail always captures why a credential was taken out of service.
+ * Request body for `POST /api/admin/secrets/:id/disable`. A non-empty reason
+ * is required so the audit trail records WHY the secret was disabled, not just
+ * that it was.
  */
 export const DisableSecretRequestSchema = z.object({
   reason: z.string().min(1).max(512),