@company-semantics/contracts 13.4.0 → 13.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.4.0",
+  "version": "13.6.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 = '3740712c6cee' as const;
+export const SPEC_HASH_FULL = '3740712c6cee7d3684fb174624951f59bc1c3bb5f48dabf43ebf6c2a535c654e' as const;

package/src/api/generated.ts

@@ -1165,6 +1165,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/executions/{executionId}/result": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get the full execution result for a finished execution */
+        get: operations["getExecutionResult"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/executions/{executionId}/undo": {
         parameters: {
             query?: never;
@@ -1250,6 +1267,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/executions/{executionId}/stream": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Stream execution lifecycle events via SSE
+         * @description Server-Sent Events stream of execution lifecycle events. x-streaming: true. Event payloads conform to ExecutionSseEvent; resume via Last-Event-ID (= event_sequence). See ADR-BE-269.
+         */
+        get: operations["streamExecutionLifecycle"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/capabilities": {
         parameters: {
             query?: never;
@@ -2058,6 +2095,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 +2453,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;
@@ -3785,6 +3842,16 @@ export interface components {
             /** @constant */
             status: "cancelled";
         };
+        ExecutionSseEvent: {
+            eventSequence: number;
+            /** @enum {string} */
+            eventType: "execution_created" | "execution_started" | "confirmation_approved" | "confirmation_rejected" | "confirmation_expired" | "approval_requested" | "execution_completed" | "execution_failed" | "undo_completed" | "cancelled";
+            /** @enum {string} */
+            stateAfter: "pending_confirmation" | "blocked_pending_approval" | "ready" | "executing" | "completed" | "completed_with_rollbacks" | "failed_retryable" | "failed_exhausted" | "failed_terminal" | "failed_with_partial_execution" | "cancelled" | "expired" | "undone";
+            actorType: string;
+            /** Format: date-time */
+            createdAt: string;
+        };
         CapabilitiesResponse: {
             profile?: {
                 fullName: {
@@ -4465,6 +4532,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 +4696,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 +4831,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 */
@@ -6881,6 +6960,26 @@ export interface operations {
             };
         };
     };
+    getExecutionResult: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                executionId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Execution result */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     undoExecution: {
         parameters: {
             query?: never;
@@ -6988,6 +7087,28 @@ export interface operations {
             };
         };
     };
+    streamExecutionLifecycle: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                executionId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description SSE event stream (text/event-stream). Event payload: ExecutionSseEvent. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": components["schemas"]["ExecutionSseEvent"];
+                };
+            };
+        };
+    };
     getMutationCapabilities: {
         parameters: {
             query?: never;
@@ -8374,6 +8495,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 +9021,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 +9261,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/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/generated/openapi-routes.ts

@@ -47,11 +47,13 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/confirm': ['POST'],
   '/api/executions/{executionId}/explanation': ['GET'],
   '/api/executions/{executionId}/reject': ['POST'],
+  '/api/executions/{executionId}/stream': ['GET'],
   '/api/executions/{executionId}/summary': ['GET'],
   '/api/executions/{executionId}/timeline': ['GET'],
   '/api/executions/{executionId}/undo': ['POST'],
   '/api/factory/floor': ['GET'],
   '/api/factory/snapshot': ['GET'],
+  '/api/ingestion/operations/{id}': ['GET'],
   '/api/internal-admin/impersonate/end': ['POST'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],