@company-semantics/contracts 13.5.0 → 13.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.5.0",
+  "version": "13.7.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 = 'c6a71ea0cfa4' as const;
-export const SPEC_HASH_FULL = 'c6a71ea0cfa4937f7069dbdbec771f42ab895123073e57995cdcff4805b0ee9b' 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;
@@ -3805,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: {
@@ -6913,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;
@@ -7020,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;

package/src/execution/index.ts

@@ -162,6 +162,10 @@ export {
   ConfirmExecutionResponseSchema,
   RejectExecutionResponseSchema,
   StartExecutionResponseSchema,
+  ExecutionResultDataSchema,
+  ExecutionResultResponseSchema,
+  ExecutionSummaryProjectionSchema,
+  GetExecutionSummaryResponseSchema,
 } from "./schemas";
 
 export type {
@@ -172,4 +176,6 @@ export type {
   ConfirmExecutionResponse,
   RejectExecutionResponse,
   StartExecutionResponse,
+  ExecutionResultResponse,
+  GetExecutionSummaryResponse,
 } from "./schemas";

package/src/execution/schemas.ts

@@ -9,6 +9,11 @@
 
 import { z } from "zod";
 
+import type { ExecutionResultData } from "../message-parts/execution";
+import type { ExecutionKind } from "./kinds";
+import type { ExecutionSummary } from "./summary";
+import { EXECUTION_KINDS } from "./registry";
+
 // =============================================================================
 // Execution Summary
 // =============================================================================
@@ -108,3 +113,103 @@ export const StartExecutionResponseSchema = z.object({
 export type StartExecutionResponse = z.infer<
   typeof StartExecutionResponseSchema
 >;
+
+// =============================================================================
+// Execution Result (GET /api/executions/{executionId}/result)
+// =============================================================================
+
+/**
+ * Zod mirror of the canonical ExecutionResultData contract
+ * (message-parts/execution.ts), authored so GET /result can declare a typed
+ * 200 body instead of forcing the client to cast. The
+ * `satisfies z.ZodType<ExecutionResultData>` guard fails compilation if the
+ * schema drifts from the interface (a wrong/missing field or a loosened enum).
+ *
+ * @see ADR-CONT-067 for the response-typing decision
+ */
+export const ExecutionResultDataSchema = z.object({
+  actionId: z.string(),
+  executionId: z.string(),
+  state: z.enum(["completed", "failed"]),
+  artifacts: z.array(
+    z.object({
+      // Mirrors PreviewArtifactKind (message-parts/preview.ts).
+      kind: z.enum([
+        "message",
+        "api_call",
+        "diff",
+        "notification",
+        "task",
+        "calendar",
+        "integration",
+      ]),
+      label: z.string(),
+      status: z.enum(["success", "failed", "skipped"]),
+      error: z.string().optional(),
+      resultLabel: z.string().optional(),
+    }),
+  ),
+  summary: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+  }),
+  undo: z
+    .object({
+      availableUntil: z.string(),
+      kind: z.string(),
+    })
+    .optional(),
+}) satisfies z.ZodType<ExecutionResultData>;
+
+export const ExecutionResultResponseSchema = z.object({
+  result: ExecutionResultDataSchema,
+});
+
+export type ExecutionResultResponse = z.infer<
+  typeof ExecutionResultResponseSchema
+>;
+
+// =============================================================================
+// Execution Summary Projection (GET /api/executions/{executionId}/summary)
+// =============================================================================
+
+/**
+ * Full ExecutionSummary projection (summary.ts). DISTINCT from the narrow
+ * ExecutionSummarySchema above, which the list endpoint uses and which omits
+ * initiatedBy / visibility / explanationAvailable. GET /summary returns the
+ * full projection at runtime, so it gets its own schema. ExecutionKind is
+ * derived from the EXECUTION_KINDS registry so the enum can never drift.
+ *
+ * @see ADR-CONT-067
+ */
+const EXECUTION_KIND_VALUES = Object.keys(EXECUTION_KINDS) as [
+  ExecutionKind,
+  ...ExecutionKind[],
+];
+
+export const ExecutionSummaryProjectionSchema = z.object({
+  executionId: z.string(),
+  kind: z.enum(EXECUTION_KIND_VALUES),
+  target: z.object({
+    type: z.literal("slack"),
+    workspaceId: z.string().optional(),
+  }),
+  status: z.enum(["pending", "succeeded", "failed"]),
+  initiatedBy: z.object({
+    actorType: z.enum(["user", "system"]),
+    actorId: z.string(),
+    displayName: z.string(),
+  }),
+  decidedAt: z.string(),
+  completedAt: z.string().optional(),
+  visibility: z.enum(["admin", "user"]),
+  explanationAvailable: z.boolean(),
+}) satisfies z.ZodType<ExecutionSummary>;
+
+export const GetExecutionSummaryResponseSchema = z.object({
+  summary: ExecutionSummaryProjectionSchema,
+});
+
+export type GetExecutionSummaryResponse = z.infer<
+  typeof GetExecutionSummaryResponseSchema
+>;

package/src/generated/openapi-routes.ts

@@ -47,11 +47,14 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/confirm': ['POST'],
   '/api/executions/{executionId}/explanation': ['GET'],
   '/api/executions/{executionId}/reject': ['POST'],
+  '/api/executions/{executionId}/result': ['GET'],
+  '/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'],