@company-semantics/contracts 2.8.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "2.8.0",
+  "version": "2.11.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 = '5639583592f3' as const;
-export const SPEC_HASH_FULL = '5639583592f37a84aa028b360d1cda28ec19a2e6bd82f053276349e646ec6809' as const;
+export const SPEC_HASH = 'ed5f74bd901b' as const;
+export const SPEC_HASH_FULL = 'ed5f74bd901b8b8cf6bfd08165b7f885e0493ca1d1f83db11ddb8df8c65d5732' as const;

package/src/api/generated.ts

@@ -1402,6 +1402,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Search Company.md knowledge across opted-in sources */
+        post: operations["searchCompanyMd"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/docs/{slug}/sharing": {
         parameters: {
             query?: never;
@@ -2313,6 +2330,91 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/me/meetings/recordings/{id}/export": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Export a transcript as markdown/JSON (sync) or PDF (async job) */
+        post: operations["exportMeetingRecording"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/meetings/recordings/{id}/export/{jobId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Download a rendered PDF export, or poll its job status */
+        get: operations["downloadMeetingRecordingExport"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/meetings/recordings/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Soft-delete a recording (30-day hard-delete grace; idempotent) */
+        delete: operations["softDeleteMeetingRecording"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/meetings/recordings/{id}/restore": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Restore a soft-deleted recording within its 30-day window */
+        post: operations["restoreMeetingRecording"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/meetings/recordings/{id}/visibility": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Change recording visibility (post-finalize only) */
+        post: operations["changeMeetingRecordingVisibility"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/internal-admin/impersonate/start": {
         parameters: {
             query?: never;
@@ -3332,6 +3434,32 @@ export interface components {
         AssociateContextDocRequest: {
             contextDocSlug: string;
         };
+        /** @description Ranked retrieval hits plus the source kinds actually searched. */
+        CompanyMdSearchResponse: {
+            hits: {
+                /** @enum {string} */
+                sourceKind: "docs" | "slack" | "meetings";
+                documentId: string;
+                recordingId: string | null;
+                title: string | null;
+                snippet: string;
+                score: number;
+                /** @enum {string} */
+                matchedVia: "fts" | "vector";
+            }[];
+            searchedSources: ("docs" | "slack" | "meetings")[];
+        };
+        /** @description A Company.md retrieval query with optional per-source opt-in. */
+        CompanyMdSearchRequest: {
+            query: string;
+            limit?: number;
+            /** @description Per-source opt-in. Server defaults: docs/slack ON, meetings OFF (INV-MTG-23) — applied even when this object or the meetings field is omitted. */
+            includeSources?: {
+                docs?: boolean;
+                slack?: boolean;
+                meetings?: boolean;
+            };
+        };
         CompanyMdShareResponse: {
             /** @enum {string} */
             sharingPolicy: "restricted" | "org_read" | "org_comment" | "org_edit";
@@ -4068,6 +4196,112 @@ export interface components {
             checksum: string;
             cancelled?: boolean;
         };
+        /** @description Synchronous markdown/JSON content, or a queued PDF job id. */
+        ExportMeetingRecordingResponse: {
+            /** @constant */
+            format: "markdown";
+            content: string;
+        } | {
+            /** @constant */
+            format: "json";
+            /** @description Finalized read projection for a recording (excludes drafts). */
+            metadata: {
+                /** @description ULID; unified trace key for the recording (INV-MTG-7). */
+                recordingId: string;
+                /** Format: uuid */
+                ownerUserId: string;
+                /** Format: uuid */
+                orgId: string;
+                title: string | null;
+                /**
+                 * @description Auto-detected meeting app that owns the system audio stream.
+                 * @enum {string}
+                 */
+                detectedApp: "zoom" | "teams" | "meet-browser" | "slack-huddle" | "manual";
+                /**
+                 * @description Visibility band for the finalized meeting projection. Default `meeting_only`.
+                 * @enum {string}
+                 */
+                visibility: "meeting_only" | "shared" | "org" | "finalized_private";
+                /**
+                 * @description Coarse lifecycle state for a recording entity.
+                 * @enum {string}
+                 */
+                status: "draft" | "recording" | "processing" | "finalized" | "failed" | "partial-transcript-network" | "cancelled";
+                /**
+                 * @description Capture-runtime quality signal. `degraded` triggers a UI hint.
+                 * @enum {string}
+                 */
+                quality: "clean" | "degraded";
+                /** Format: date-time */
+                startedAt: string;
+                endedAt: string | null;
+                durationMs: number;
+                participantUserIds: string[];
+                transcriptAvailable: boolean;
+            };
+            segments: {
+                startMs: number;
+                endMs: number;
+                /** @enum {string} */
+                source: "mic" | "remote" | "unknown";
+                speakerLabel: string | null;
+                text: string;
+                confidence: number | null;
+            }[];
+        } | {
+            /** @constant */
+            format: "pdf";
+            /** Format: uuid */
+            jobId: string;
+            /** @constant */
+            status: "queued";
+        };
+        /** @description Export a recording transcript as markdown, JSON, or PDF. */
+        ExportMeetingRecordingRequest: {
+            /** @enum {string} */
+            format: "markdown" | "json" | "pdf";
+        };
+        /** @description PDF export job not yet ready (pending) or failed. */
+        MeetingRecordingExportJobStatus: {
+            /** Format: uuid */
+            jobId: string;
+            /** @enum {string} */
+            status: "pending" | "failed";
+        };
+        /** @description Recording soft-deleted; hard-delete scheduled 30 days out. */
+        SoftDeleteMeetingRecordingResponse: {
+            /** @description ULID; unified trace key for the recording (INV-MTG-7). */
+            recordingId: string;
+            /** @constant */
+            deleted: true;
+            hardDeleteScheduledAt: string | null;
+        };
+        /** @description Restore a soft-deleted recording within its grace window. */
+        RestoreMeetingRecordingResponse: {
+            /** @description ULID; unified trace key for the recording (INV-MTG-7). */
+            recordingId: string;
+            restored: boolean;
+            status: string;
+        };
+        /** @description Result of a visibility change. */
+        ChangeMeetingRecordingVisibilityResponse: {
+            /** @description ULID; unified trace key for the recording (INV-MTG-7). */
+            recordingId: string;
+            /**
+             * @description Visibility band for the finalized meeting projection. Default `meeting_only`.
+             * @enum {string}
+             */
+            visibility: "meeting_only" | "shared" | "org" | "finalized_private";
+        };
+        /** @description Change a recording visibility (post-finalize only). */
+        ChangeMeetingRecordingVisibilityRequest: {
+            /**
+             * @description Visibility band for the finalized meeting projection. Default `meeting_only`.
+             * @enum {string}
+             */
+            visibility: "meeting_only" | "shared" | "org" | "finalized_private";
+        };
         ImpersonationSessionResponse: {
             session: {
                 impersonationSessionId: string;
@@ -6251,6 +6485,44 @@ export interface operations {
             };
         };
     };
+    searchCompanyMd: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CompanyMdSearchRequest"];
+            };
+        };
+        responses: {
+            /** @description Ranked retrieval hits plus the source kinds searched */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CompanyMdSearchResponse"];
+                };
+            };
+            /** @description Invalid query body */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Requires org.view_company_md scope */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCompanyMdDocSharing: {
         parameters: {
             query?: never;
@@ -7783,6 +8055,174 @@ export interface operations {
             };
         };
     };
+    exportMeetingRecording: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ExportMeetingRecordingRequest"];
+            };
+        };
+        responses: {
+            /** @description Markdown/JSON content inline, or a queued PDF job id */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ExportMeetingRecordingResponse"];
+                };
+            };
+            /** @description Recording not found or not owned by this user */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    downloadMeetingRecordingExport: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                jobId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The rendered PDF */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description PDF not yet ready (pending) or failed */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MeetingRecordingExportJobStatus"];
+                };
+            };
+            /** @description Recording or export job not found / not owned by this user */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    softDeleteMeetingRecording: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Recording soft-deleted */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SoftDeleteMeetingRecordingResponse"];
+                };
+            };
+            /** @description Recording not found or not owned by this user */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    restoreMeetingRecording: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Recording restored (or a no-op outside the window) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RestoreMeetingRecordingResponse"];
+                };
+            };
+            /** @description Recording not found or not owned by this user */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    changeMeetingRecordingVisibility: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ChangeMeetingRecordingVisibilityRequest"];
+            };
+        };
+        responses: {
+            /** @description Visibility changed */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ChangeMeetingRecordingVisibilityResponse"];
+                };
+            };
+            /** @description Recording not found or not owned by this user */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Cannot change visibility while recording (pre-finalize) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     startImpersonation: {
         parameters: {
             query?: never;

package/src/index.ts

@@ -747,3 +747,8 @@ export type {
 // Meeting recorder vocabulary (PRD-00651)
 // @see ./meetings/schemas.ts for invariants
 export * from './meetings'
+
+// Permission model vocabulary (PRD-00669 AUTH-001)
+// AccessLevel / OrgChartRole / AccessSource — see ADR-CTRL-084..088.
+// No consumers in this PRD; cutover starts in AUTH-002 (PRD-00670).
+export * from './permissions'

package/src/permissions/access-levels.ts

@@ -0,0 +1,40 @@
+/**
+ * Permission Access Levels
+ *
+ * Canonical four-level access vocabulary for object permissions across
+ * Company Semantics, modeled on the Google-Docs four-level scheme.
+ *
+ * Authority: ADR-CTRL-085 (Rights Table). See ADR-CTRL-084 for how these
+ * levels are materialized into `effective_acl_grants`, and ADR-CTRL-086 for
+ * the aggregation rule (most-permissive across sources).
+ *
+ * The commenter level is currently a stub — see ADR-CTRL-087.
+ */
+import { z } from 'zod';
+
+export const ACCESS_LEVELS = ['owner', 'editor', 'commenter', 'viewer'] as const;
+export type AccessLevel = (typeof ACCESS_LEVELS)[number];
+
+export const AccessLevelSchema = z.enum(ACCESS_LEVELS);
+
+/**
+ * Ordered weakest → strongest. Index = ranking.
+ * Used by `highestGrant()` in AUTH-006 (PRD-00674) to aggregate across sources.
+ */
+export const ACCESS_LEVEL_ORDER: Record<AccessLevel, number> = {
+  viewer: 0,
+  commenter: 1,
+  editor: 2,
+  owner: 3,
+};
+
+/**
+ * Returns true when `actual` is at least as strong as `required`.
+ * Examples:
+ *   isAtLeast('editor', 'viewer') === true
+ *   isAtLeast('viewer', 'editor') === false
+ *   isAtLeast('owner',  'owner')  === true
+ */
+export function isAtLeast(actual: AccessLevel, required: AccessLevel): boolean {
+  return ACCESS_LEVEL_ORDER[actual] >= ACCESS_LEVEL_ORDER[required];
+}

package/src/permissions/access-source.ts

@@ -0,0 +1,28 @@
+/**
+ * Access Source
+ *
+ * Provenance tag on rows in `effective_acl_grants`. Each row is materialized
+ * from exactly one input source; multiple rows for the same
+ * (entity, principal) pair are allowed, one per source.
+ *
+ * Authority: ADR-CTRL-084 (Permission Resolution Architecture).
+ *
+ * Sources:
+ *   - `explicit`     — direct `acl_grants` row
+ *   - `ownership`    — entity.owner_user_id column projection
+ *   - `visibility`   — entity.visibility tier compiled to viewer rows
+ *   - `inheritance`  — org-chart-membership-based unit walk
+ *   - `migration`    — one-shot backfill from legacy systems (AUTH-004)
+ */
+import { z } from 'zod';
+
+export const ACCESS_SOURCES = [
+  'explicit',
+  'ownership',
+  'visibility',
+  'inheritance',
+  'migration',
+] as const;
+export type AccessSource = (typeof ACCESS_SOURCES)[number];
+
+export const AccessSourceSchema = z.enum(ACCESS_SOURCES);

package/src/permissions/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Permissions Vocabulary Barrel
+ *
+ * Re-exports the three canonical enums introduced in AUTH-001 (PRD-00669).
+ * Import from '@company-semantics/contracts' (root).
+ */
+export * from './access-levels';
+export * from './orgchart-roles';
+export * from './access-source';

package/src/permissions/orgchart-roles.ts

@@ -0,0 +1,24 @@
+/**
+ * Org-Chart Roles
+ *
+ * Canonical four-role vocabulary for subtree-CRUD authority on org_units.
+ *
+ * Authority: ADR-CTRL-088 (Org-Chart Roles).
+ *
+ * These roles govern only member CRUD on a unit and its ltree descendants.
+ * They never grant object access — object access flows through ownership +
+ * ACL + visibility + inheritance per ADR-CTRL-084.
+ *
+ * Consumers: AUTH-006 policy registry (PRD-00674),
+ * AUTH-009 org-chart member CRUD UI (PRD-00677),
+ * AUTH-011C strict-guard flip (PRD-00681).
+ *
+ * The legacy `WorkspaceRole` and `OrgUnitMembershipRole` enums coexist with
+ * this enum until AUTH-011C deletes them.
+ */
+import { z } from 'zod';
+
+export const ORG_CHART_ROLES = ['ceo', 'leader', 'delegate', 'admin'] as const;
+export type OrgChartRole = (typeof ORG_CHART_ROLES)[number];
+
+export const OrgChartRoleSchema = z.enum(ORG_CHART_ROLES);