@company-semantics/contracts 13.3.1 → 13.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.3.1",
+  "version": "13.5.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 = '5961c9041966' as const;
-export const SPEC_HASH_FULL = '5961c9041966a739d90bd6f60228167aeccf4c1f28d37a28a924499eb452acd0' as const;
+export const SPEC_HASH = 'c6a71ea0cfa4' as const;
+export const SPEC_HASH_FULL = 'c6a71ea0cfa4937f7069dbdbec771f42ab895123073e57995cdcff4805b0ee9b' as const;

package/src/api/generated.ts

@@ -2058,6 +2058,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/ingestion/operations/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Poll a generic ingestion operation by id (single shape for all consumers)
+         * @description Returns the rolled-up status of an ingestion operation plus its consumerKind and dryRun flag. The validated candidate preview and a failure reason are surfaced when present. Org-scoped: an operation belonging to another org returns 404.
+         */
+        get: operations["getIngestionOperation"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/users/{userId}/avatar": {
         parameters: {
             query?: never;
@@ -2396,7 +2416,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get a work item by id (owner-only) */
+        /** Get a work item by id (binding gate; meta-tier admins see metadata only) */
         get: operations["getWorkItemById"];
         put?: never;
         post?: never;
@@ -4465,6 +4485,31 @@ export interface components {
                 relationshipType: "solid" | "dotted";
             }[];
         };
+        /** @description Polling snapshot of a generic ingestion operation. */
+        IngestionOperationPollResponse: {
+            /** Format: uuid */
+            id: string;
+            /** @enum {string} */
+            status: "pending" | "normalizing" | "extracting" | "validating" | "validated" | "persisting" | "applying" | "applied" | "complete" | "failed";
+            consumerKind: string;
+            dryRun: boolean;
+            /** @description A validated, not-yet-persisted extraction artifact (PRD-00756 F5). */
+            candidate?: {
+                data: unknown;
+                model: string;
+                fallbackUsed?: boolean;
+                tokenUsage?: {
+                    input: number;
+                    output: number;
+                };
+                /** @enum {string} */
+                confidence?: "low" | "medium" | "high";
+                flags: string[];
+                extractionMethod: string;
+                extractionEmpty?: boolean;
+            };
+            error?: string;
+        };
         DriveFileListResponse: {
             files: {
                 id: string;
@@ -4604,6 +4649,19 @@ export interface components {
             /** @constant */
             ok: true;
         };
+        WorkItemDetailResponse: {
+            id: string;
+            /** @enum {string} */
+            kind: "meeting" | "comm" | "doc";
+            title: string;
+            content: string;
+            contentRedacted?: boolean;
+            metadata: {
+                [key: string]: unknown;
+            };
+            createdAt: string;
+            updatedAt: string;
+        };
         UpdateWorkItemResponse: {
             updatedAt: string;
         };
@@ -4726,58 +4784,32 @@ export interface components {
             checksum: string;
             cancelled?: boolean;
         };
-        /** @description Synchronous markdown/JSON content, or a queued PDF job id. */
+        /** @description Synchronous markdown/JSON export, or a queued PDF job id. */
         ExportMeetingRecordingResponse: {
-            /** @constant */
-            format: "markdown";
+            /** @description ULID; unified trace key for the recording (INV-MTG-7). */
+            recordingId: string;
+            /**
+             * @description Rendered export format for a finalized meeting transcript.
+             * @enum {string}
+             */
+            format: "markdown" | "text" | "vtt" | "srt" | "json";
             content: string;
-        } | {
-            /** @constant */
-            format: "json";
-            /** @description Finalized read projection for a recording (excludes drafts). */
-            metadata: {
+            contentRedacted?: boolean;
+            segments: {
                 /** @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.
+                 * @description Capture stream identity. Mic = channel 0, system audio = channel 1.
                  * @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;
+                source: "mic" | "system";
+                sequence: number;
+                startedAtMs: number;
+                endedAtMs: number | null;
+                /** @constant */
+                sampleRateHz: 16000;
+                /** @constant */
+                channels: 1;
             }[];
         } | {
             /** @constant */
@@ -8374,6 +8406,35 @@ export interface operations {
             };
         };
     };
+    getIngestionOperation: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Operation polling snapshot */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["IngestionOperationPollResponse"];
+                };
+            };
+            /** @description Operation not found (or belongs to another org) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     uploadUserAvatar: {
         parameters: {
             query?: never;
@@ -8871,12 +8932,14 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Full work item including markdown content */
+            /** @description Full work item including markdown content; content is redacted (contentRedacted:true) for a meta-tier viewer */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content?: never;
+                content: {
+                    "application/json": components["schemas"]["WorkItemDetailResponse"];
+                };
             };
             /** @description Not found or not visible to this viewer */
             404: {
@@ -9109,13 +9172,20 @@ export interface operations {
                     "application/json": components["schemas"]["ExportMeetingRecordingResponse"];
                 };
             };
-            /** @description Recording not found or not owned by this user */
+            /** @description Recording not found, or the actor may not view it (no existence leak) */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
+            /** @description PDF export refused for a metadata-only (redacted) viewer */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     downloadMeetingRecordingExport: {

package/src/content/index.ts

@@ -19,6 +19,10 @@ export type {
   CompanyMdContextBankResponse,
 } from "./schemas";
 
+// Work item response schema (PRD-00763)
+export { WorkItemDetailResponseSchema } from "./schemas";
+export type { WorkItemDetailResponse } from "./schemas";
+
 // Drive response schemas (PRD-00448)
 export {
   DriveFileListResponseSchema,

package/src/content/schemas.ts

@@ -102,6 +102,35 @@ export const CompanyMdDocResponseSchema = z.object({
   updatedAt: z.string(),
 });
 
+// ---------------------------------------------------------------------------
+// Work Item HTTP Response Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Response for GET /api/work-items/:id
+ *
+ * Models the work-item detail shape the backend returns (id, kind, title,
+ * markdown body, free-form metadata, timestamps). Hand-written and independent
+ * of the generated OpenAPI surface; the backend adapts to this schema
+ * (PRD-00760).
+ */
+export const WorkItemDetailResponseSchema = z.object({
+  id: z.string(),
+  kind: z.enum(["meeting", "comm", "doc"]),
+  title: z.string(),
+  content: z.string(),
+  /**
+   * When `true`, `content` is the redacted empty body (`''`) returned to a
+   * metadata-only (meta-tier) viewer who administers the work item but may not
+   * read its body (ADR-BE-245). Omitted/`false` on the normal full-content
+   * path. Keeping it optional preserves back-compat for full-content readers.
+   */
+  contentRedacted: z.boolean().optional(),
+  metadata: z.record(z.string(), z.unknown()),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
 // ---------------------------------------------------------------------------
 // Company.md Sharing Sub-schemas
 // ---------------------------------------------------------------------------
@@ -207,6 +236,9 @@ export type CompanyMdShareResponse = z.infer<
 export type CompanyMdContextBankResponse = z.infer<
   typeof CompanyMdContextBankResponseSchema
 >;
+export type WorkItemDetailResponse = z.infer<
+  typeof WorkItemDetailResponseSchema
+>;
 export type DriveFileListResponse = z.infer<typeof DriveFileListResponseSchema>;
 export type DriveFileContentResponse = z.infer<
   typeof DriveFileContentResponseSchema

package/src/execution/events.ts

@@ -7,19 +7,9 @@
  * Forward-compatible: execution_completed, execution_failed, undo_completed, cancelled.
  * These are defined here for type exhaustiveness but not yet emitted by backend.
  */
-export type ExecutionEventType =
-  | "execution_created"
-  | "execution_started"
-  | "confirmation_approved"
-  | "confirmation_rejected"
-  | "confirmation_expired"
-  | "approval_requested"
-  | "execution_completed"
-  | "execution_failed"
-  | "undo_completed"
-  | "cancelled";
+import { z } from "zod";
 
-export const EXECUTION_EVENT_TYPES: readonly ExecutionEventType[] = [
+export const EXECUTION_EVENT_TYPES = [
   "execution_created",
   "execution_started",
   "confirmation_approved",
@@ -32,6 +22,11 @@ export const EXECUTION_EVENT_TYPES: readonly ExecutionEventType[] = [
   "cancelled",
 ] as const;
 
+export type ExecutionEventType = (typeof EXECUTION_EVENT_TYPES)[number];
+
+/** Runtime-validatable form of {@link ExecutionEventType}, derived from the single source. */
+export const ExecutionEventTypeSchema = z.enum(EXECUTION_EVENT_TYPES);
+
 export function isExecutionEventType(
   value: string,
 ): value is ExecutionEventType {

package/src/execution/index.ts

@@ -13,7 +13,18 @@
 
 export type { ExecutionEventType } from "./events";
 
-export { EXECUTION_EVENT_TYPES, isExecutionEventType } from "./events";
+export {
+  EXECUTION_EVENT_TYPES,
+  ExecutionEventTypeSchema,
+  isExecutionEventType,
+} from "./events";
+
+// =============================================================================
+// SSE Stream Event (wire contract)
+// =============================================================================
+
+export { ExecutionSseEventSchema } from "./sse";
+export type { ExecutionSseEvent } from "./sse";
 
 // =============================================================================
 // Event Metadata Schemas
@@ -67,6 +78,8 @@ export type { ExecutionKind } from "./kinds";
 export type { ExecutionState } from "./status";
 
 export {
+  EXECUTION_STATES,
+  ExecutionStateSchema,
   VALID_TRANSITIONS,
   TERMINAL_STATES,
   EFFECTIVE_TERMINAL_STATES,

package/src/execution/sse.ts

@@ -0,0 +1,33 @@
+/**
+ * Execution lifecycle SSE event — wire contract.
+ *
+ * The payload of one `text/event-stream` message emitted by
+ * `GET /api/executions/{executionId}/stream` (ADR-BE-269). Each SSE frame
+ * carries one execution_events row, PROJECTED to this least-exposure shape —
+ * the raw row's hash-chain fields (`event_hash`, `previous_hash`), `actor_id`,
+ * and free-form `metadata` are deliberately NOT on the wire. The stream never
+ * emits raw rows.
+ *
+ * `eventSequence` is the monotonic per-execution cursor (also the SSE `id:`
+ * field), so a client resumes after a disconnect via `Last-Event-ID`.
+ *
+ * @see ADR-CONT-029 for execution-contract design rationale.
+ */
+
+import { z } from "zod";
+import { ExecutionEventTypeSchema } from "./events";
+import { ExecutionStateSchema } from "./status";
+
+export const ExecutionSseEventSchema = z.object({
+  /** Monotonic per-execution sequence; doubles as the SSE `id:` for resume. */
+  eventSequence: z.number().int().nonnegative(),
+  eventType: ExecutionEventTypeSchema,
+  /** Execution lifecycle state AFTER this event. */
+  stateAfter: ExecutionStateSchema,
+  /** Coarse actor class that produced the event (e.g. `user`, `system`). */
+  actorType: z.string(),
+  /** DB insert time of the event, ISO-8601 with offset. */
+  createdAt: z.string().datetime({ offset: true }),
+});
+
+export type ExecutionSseEvent = z.infer<typeof ExecutionSseEventSchema>;

package/src/execution/status.ts

@@ -54,20 +54,28 @@
  * - **INV-EXEC-5**: failed_retryable -> ready loop bounded by executor retry budget.
  *   Retry events must include retryAttempt in metadata.
  */
-export type ExecutionState =
-  | "pending_confirmation"
-  | "blocked_pending_approval"
-  | "ready"
-  | "executing"
-  | "completed"
-  | "completed_with_rollbacks"
-  | "failed_retryable"
-  | "failed_exhausted"
-  | "failed_terminal"
-  | "failed_with_partial_execution"
-  | "cancelled"
-  | "expired"
-  | "undone";
+import { z } from "zod";
+
+export const EXECUTION_STATES = [
+  "pending_confirmation",
+  "blocked_pending_approval",
+  "ready",
+  "executing",
+  "completed",
+  "completed_with_rollbacks",
+  "failed_retryable",
+  "failed_exhausted",
+  "failed_terminal",
+  "failed_with_partial_execution",
+  "cancelled",
+  "expired",
+  "undone",
+] as const;
+
+export type ExecutionState = (typeof EXECUTION_STATES)[number];
+
+/** Runtime-validatable form of {@link ExecutionState}, derived from the single source. */
+export const ExecutionStateSchema = z.enum(EXECUTION_STATES);
 
 export const VALID_TRANSITIONS: Record<
   ExecutionState,

package/src/meetings/index.ts

@@ -16,6 +16,8 @@ export {
   RecordingEventSchema,
   TranscriptionSessionGrantSchema,
   MeetingMetadataProjectionSchema,
+  MeetingExportFormatSchema,
+  MeetingExportResponseSchema,
 } from "./schemas";
 
 export type {
@@ -31,4 +33,6 @@ export type {
   RecordingEvent,
   TranscriptionSessionGrant,
   MeetingMetadataProjection,
+  MeetingExportFormat,
+  MeetingExportResponse,
 } from "./schemas";

package/src/meetings/schemas.ts

@@ -291,3 +291,50 @@ export const MeetingMetadataProjectionSchema = z
 export type MeetingMetadataProjection = z.infer<
   typeof MeetingMetadataProjectionSchema
 >;
+
+// =============================================================================
+// Meeting export response (HTTP read model)
+// =============================================================================
+
+/**
+ * Export format the backend renders a finalized meeting transcript into.
+ * `markdown`/`text` are prose bodies; `vtt`/`srt` are timed-caption formats;
+ * `json` is the structured segment payload.
+ */
+export const MeetingExportFormatSchema = z
+  .enum(["markdown", "text", "vtt", "srt", "json"])
+  .meta({
+    description: "Rendered export format for a finalized meeting transcript.",
+  });
+export type MeetingExportFormat = z.infer<typeof MeetingExportFormatSchema>;
+
+/**
+ * Response for the meeting-export endpoint. Models the rendered export the
+ * backend returns for a finalized recording: the chosen `format`, the rendered
+ * `content` body, and the `segments` the export was assembled from. Hand-written
+ * and independent of the generated OpenAPI surface; the backend adapts to this
+ * schema (PRD-00763).
+ *
+ * Mirrors the meta-tier redaction contract of `WorkItemDetailResponseSchema`
+ * and `CompanyMdDocResponseSchema`.
+ */
+export const MeetingExportResponseSchema = z
+  .object({
+    recordingId: RecordingIdSchema,
+    format: MeetingExportFormatSchema,
+    content: z.string(),
+    /**
+     * When `true`, `content` is the redacted empty body (`''`) returned to a
+     * metadata-only (meta-tier) viewer who administers the meeting but may not
+     * read its transcript body (ADR-BE-245). Omitted/`false` on the normal
+     * full-content path. Keeping it optional preserves back-compat for
+     * full-content readers.
+     */
+    contentRedacted: z.boolean().optional(),
+    segments: z.array(SourceSegmentSchema),
+  })
+  .meta({
+    description:
+      "Rendered meeting-transcript export (format, content, segments) with optional meta-tier redaction flag.",
+  });
+export type MeetingExportResponse = z.infer<typeof MeetingExportResponseSchema>;