@company-semantics/contracts 0.103.2 → 0.104.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.103.2",
+  "version": "0.104.1",
   "private": false,
   "repository": {
     "type": "git",
@@ -101,6 +101,11 @@
     "vitest": "^4.0.16",
     "yaml": "^2.8.3"
   },
+  "pnpm": {
+    "overrides": {
+      "picomatch": ">=4.0.4"
+    }
+  },
   "lint-staged": {
     "*.ts": "bash -c 'tsc -b --noEmit'",
     "*.md": "markdownlint-cli2",

package/src/api/generated.ts

@@ -25,6 +25,28 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/healthz/details": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Detailed system health state
+         * @description Returns system health derived from alert engine and windowed metrics.
+         *     Includes health status, trend, active alerts, and key metrics.
+         *     Must NOT depend on database availability.
+         */
+        get: operations["getHealthDetails"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/auth/start": {
         parameters: {
             query?: never;
@@ -1902,6 +1924,26 @@ export interface components {
             /** @description Current application environment */
             app_env: string;
         };
+        HealthStateResponse: {
+            /** @enum {string} */
+            status: "healthy" | "degraded" | "critical";
+            /** @enum {string} */
+            trend: "stable" | "worsening" | "improving";
+            alerts: Record<string, never>[];
+            metrics: {
+                errorRate: number;
+                p95Latency: number;
+                activeExecutions: number;
+                droppedEvents: {
+                    log: number;
+                    metric: number;
+                    alert: number;
+                    trace: number;
+                };
+            };
+            /** @description Unix timestamp (milliseconds) of last health state computation */
+            lastUpdated: number;
+        };
         MeResponse: {
             /** Format: uuid */
             userId: string;
@@ -2739,6 +2781,26 @@ export interface operations {
             };
         };
     };
+    getHealthDetails: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description System health state */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HealthStateResponse"];
+                };
+            };
+        };
+    };
     startAuth: {
         parameters: {
             query?: never;

package/src/errors/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Canonical error response types for all API surfaces.
+ *
+ * These types are the single source of truth for the error response shape
+ * across HTTP, streaming, agents, and the execution system.
+ *
+ * @see ADR-BE-098 for design rationale
+ */
+
+/** Field-level validation detail for VALIDATION_ERROR responses. */
+export interface ValidationDetail {
+  /** Field path (e.g. 'email', 'settings.name'). */
+  field: string
+  /** Human-readable error message for this field. */
+  message: string
+  /** Machine-readable sub-code (e.g. 'too_short', 'invalid_format') for frontend logic. */
+  code?: string
+}
+
+/** Canonical error response shape returned by all API surfaces. */
+export interface ErrorResponse {
+  /** Domain-specific error code (e.g. INVITE_EXPIRED, SSO_REQUIRED). */
+  error: string
+  /** HTTP status code — lives in payload for transport portability across HTTP, streaming, agents, execution system. */
+  status: number
+  /** Optional human-readable message — safe default applied by handler when absent. */
+  message?: string
+  /** Validation field-level details — only present for VALIDATION_ERROR. */
+  details?: ValidationDetail[]
+  /**
+   * Structured extension fields (e.g. ssoUrl, orgId).
+   *
+   * Conventions: camelCase keys, domain-scoped, shallow values,
+   * serializable, stable keys, no duplication of top-level fields.
+   */
+  meta?: Record<string, unknown>
+}

package/src/execution/__tests__/lifecycle.test.ts

@@ -18,6 +18,7 @@ const ALL_STATES: ExecutionState[] = [
   'completed',
   'completed_with_rollbacks',
   'failed_retryable',
+  'failed_exhausted',
   'failed_terminal',
   'failed_with_partial_execution',
   'cancelled',

package/src/execution/lifecycle.ts

@@ -25,6 +25,7 @@ export const LIFECYCLE_DECISIONS: DecisionTable = {
     completed: 'already_confirmed',
     completed_with_rollbacks: 'already_confirmed',
     failed_retryable: 'conflict',
+    failed_exhausted: 'conflict',
     failed_terminal: 'conflict',
     failed_with_partial_execution: 'conflict',
     undone: 'conflict',
@@ -39,6 +40,7 @@ export const LIFECYCLE_DECISIONS: DecisionTable = {
     completed: 'conflict',
     completed_with_rollbacks: 'conflict',
     failed_retryable: 'conflict',
+    failed_exhausted: 'conflict',
     failed_terminal: 'conflict',
     failed_with_partial_execution: 'conflict',
     undone: 'conflict',

package/src/execution/status.ts

@@ -12,6 +12,7 @@
  *         │                         │                     │          ├──→ completed
  *         │                         │                     │          ├──→ completed_with_rollbacks
  *         │                         │                     │          ├──→ failed_retryable ──→ ready (retry)
+ *         │                         │                     │          │                   └──→ failed_exhausted
  *         │                         │                     │          ├──→ failed_terminal
  *         │                         │                     │          ├──→ failed_with_partial_execution
  *         │                         │                     │          └──→ cancelled
@@ -61,6 +62,7 @@ export type ExecutionState =
   | 'completed'
   | 'completed_with_rollbacks'
   | 'failed_retryable'
+  | 'failed_exhausted'
   | 'failed_terminal'
   | 'failed_with_partial_execution'
   | 'cancelled'
@@ -78,7 +80,8 @@ export const VALID_TRANSITIONS: Record<ExecutionState, readonly ExecutionState[]
   ],
   completed: ['undone'],
   completed_with_rollbacks: [],
-  failed_retryable: ['ready'],
+  failed_retryable: ['ready', 'failed_exhausted'],
+  failed_exhausted: [],
   failed_terminal: [],
   failed_with_partial_execution: [],
   cancelled: [],

package/src/index.ts

@@ -540,9 +540,17 @@ export { resolveScope, toQueryKey, fromQueryKey, resourceRelationships, matchesR
 // Resource response wrapper (typed versioning for cache invalidation)
 export type { ResourceResponse } from './resource-response'
 
+// Error response types (canonical shape for all API surfaces)
+// @see ADR-BE-098 for design rationale
+export type { ValidationDetail, ErrorResponse } from './errors/index'
+
 // OpenAPI generated types (from openapi/backend.yaml)
 // @see src/api/README.md for codegen details
 export type { paths, components, operations } from './api/index'
 
 // OpenAPI route registry (generated from openapi/backend.yaml)
 export { openApiRoutes, type OpenApiRoute, type OpenApiMethod } from './generated/openapi-routes'
+
+// Secret wrapper (multi-surface redaction for sensitive values)
+export type { Secret } from './security/index'
+export { wrapSecret, unwrapSecret } from './security/index'

package/src/security/index.ts

@@ -0,0 +1,2 @@
+export type { Secret } from './secret';
+export { wrapSecret, unwrapSecret } from './secret';

package/src/security/secret.ts

@@ -0,0 +1,47 @@
+/**
+ * Secret<T> — branded wrapper that prevents accidental secret leakage.
+ *
+ * Multi-surface protection:
+ * - toString() → [REDACTED] — template literals, string concatenation, error messages
+ * - toJSON() → [REDACTED] — JSON.stringify (API responses, serialization)
+ * - Symbol.toPrimitive → [REDACTED] — implicit type coercion
+ *
+ * Use wrapSecret() to wrap a value, unwrapSecret() to extract it.
+ * The __secret marker enables external detection (e.g., Pino serializers).
+ */
+
+// @vocabulary-exempt: Class required for prototype method control (toString/toJSON/Symbol.toPrimitive)
+class SecretValue<T> {
+  readonly __secret = true as const;
+  private readonly _value: T;
+
+  constructor(value: T) {
+    this._value = value;
+  }
+
+  unwrap(): T {
+    return this._value;
+  }
+
+  toString(): string {
+    return '[REDACTED]';
+  }
+
+  toJSON(): string {
+    return '[REDACTED]';
+  }
+
+  [Symbol.toPrimitive](): string {
+    return '[REDACTED]';
+  }
+}
+
+export type Secret<T> = SecretValue<T>;
+
+export function wrapSecret<T>(value: T): Secret<T> {
+  return new SecretValue(value);
+}
+
+export function unwrapSecret<T>(secret: Secret<T>): T {
+  return secret.unwrap();
+}