@company-semantics/contracts 0.88.0 → 0.89.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.88.0",
+  "version": "0.89.0",
   "private": false,
   "repository": {
     "type": "git",

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

@@ -8,7 +8,6 @@ import {
 } from '../status.js'
 import { LIFECYCLE_DECISIONS, applyIntent } from '../lifecycle.js'
 import type { ExecutionErrorCode } from '../errors.js'
-import { ExecutionError } from '../errors.js'
 import { parseExpiresAt, isConfirmationExpired } from '../expiry.js'
 
 const ALL_STATES: ExecutionState[] = [
@@ -161,45 +160,10 @@ describe('applyIntent', () => {
 })
 
 // ---------------------------------------------------------------------------
-// 7. EXECUTION_ERROR TESTS
+// 7. EXECUTION_ERROR TYPE TESTS
 // ---------------------------------------------------------------------------
-describe('ExecutionError', () => {
-  it('has correct name', () => {
-    const err = new ExecutionError('execution_expired', 'test', 410)
-    expect(err.name).toBe('ExecutionError')
-  })
-
-  it('has correct code', () => {
-    const err = new ExecutionError('execution_invalid_transition', 'bad transition', 409)
-    expect(err.code).toBe('execution_invalid_transition')
-  })
-
-  it('has correct message', () => {
-    const err = new ExecutionError('execution_not_found', 'not found', 404)
-    expect(err.message).toBe('not found')
-  })
-
-  it('has correct httpStatus', () => {
-    const err = new ExecutionError('execution_forbidden', 'forbidden', 403)
-    expect(err.httpStatus).toBe(403)
-  })
-
-  it('httpStatus is optional', () => {
-    const err = new ExecutionError('execution_expired', 'expired')
-    expect(err.httpStatus).toBeUndefined()
-  })
-
-  it('instanceof Error works', () => {
-    const err = new ExecutionError('execution_expired', 'expired', 410)
-    expect(err).toBeInstanceOf(Error)
-  })
-
-  it('instanceof ExecutionError works', () => {
-    const err = new ExecutionError('execution_expired', 'expired', 410)
-    expect(err).toBeInstanceOf(ExecutionError)
-  })
-
-  it('supports all error codes', () => {
+describe('ExecutionErrorCode', () => {
+  it('covers all expected error codes', () => {
     const codes: ExecutionErrorCode[] = [
       'execution_expired',
       'execution_already_confirmed',
@@ -208,11 +172,7 @@ describe('ExecutionError', () => {
       'execution_forbidden',
       'execution_invalid_transition',
     ]
-    for (const code of codes) {
-      const err = new ExecutionError(code, `msg-${code}`)
-      expect(err.code).toBe(code)
-      expect(err.name).toBe('ExecutionError')
-    }
+    expect(codes).toHaveLength(6)
   })
 })
 

package/src/execution/errors.ts

@@ -6,13 +6,9 @@ export type ExecutionErrorCode =
   | 'execution_forbidden'
   | 'execution_invalid_transition';
 
-export class ExecutionError extends Error {
-  constructor(
-    public readonly code: ExecutionErrorCode,
-    message: string,
-    public readonly httpStatus?: number,
-  ) {
-    super(message);
-    this.name = 'ExecutionError';
-  }
+export interface ExecutionError {
+  readonly name: 'ExecutionError';
+  readonly code: ExecutionErrorCode;
+  readonly message: string;
+  readonly httpStatus?: number;
 }

package/src/execution/index.ts

@@ -103,8 +103,7 @@ export { parseExpiresAt, isConfirmationExpired } from './expiry'
 // Error Types
 // =============================================================================
 
-export type { ExecutionErrorCode } from './errors'
-export { ExecutionError } from './errors'
+export type { ExecutionErrorCode, ExecutionError } from './errors'
 
 // =============================================================================
 // Definition Types

package/src/index.ts

@@ -2,11 +2,10 @@
  * @company-semantics/contracts
  *
  * Shared semantic vocabulary across Company Semantics codebases.
- * Types only - no runtime code, no business logic.
+ * Types and pure deterministic functions — no runtime code, no business logic.
  *
- * This package intentionally contains only minimal shared vocabulary,
- * not full domain models. Structural types live in individual codebases
- * until they are proven stable.
+ * This package contains shared vocabulary and pure derivation functions.
+ * Structural types live in individual codebases until they are proven stable.
  *
  * @see https://github.com/company-semantics/company-semantics-contracts
  */
@@ -466,6 +465,14 @@ export type {
   UsageByFeature,
   UsageByUser,
   OrgUsageResponse,
+  // Unified usage types (PRD-00276/277)
+  UnifiedUsageSummary,
+  UnifiedDailyUsage,
+  UnifiedProfileUsage,
+  UnifiedUserUsage,
+  UnifiedModelUsage,
+  UnifiedFeatureUsage,
+  UnifiedUsageResponse,
 } from './usage/types'
 
 // Runtime execution telemetry types

package/src/mcp/index.ts

@@ -215,7 +215,7 @@ export interface MCPToolDescriptor {
  * Edge in the capability graph connecting two tools via a resource.
  * A tool that produces a resource connects to tools that consume it.
  *
- * @stub Implementation in PRD-00268 (buildCapabilityGraph)
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
  */
 export interface CapabilityGraphEdge {
   /** Tool ID that produces the resource */
@@ -232,7 +232,7 @@ export interface CapabilityGraphEdge {
  * Named workflow derived from capability graph paths.
  * Represents a common multi-tool sequence (e.g., "Connect Slack → Ingest → Query").
  *
- * @stub Implementation in PRD-00268 (buildCapabilityGraph)
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
  */
 export interface ToolWorkflow {
   /** Workflow name (e.g., "Slack Onboarding") */
@@ -247,7 +247,7 @@ export interface ToolWorkflow {
  * Capability graph derived from tool resource flow metadata.
  * Built from produces/consumes fields on MCPToolDescriptor.
  *
- * @stub Type definition only. buildCapabilityGraph() ships in PRD-00268.
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
  */
 export interface CapabilityGraph {
   /** Resource flow edges between tools */
@@ -270,7 +270,7 @@ export interface ToolDiscoveryResponse {
    * Capability graph derived from tool resource flow metadata.
    * Optional — discovery responses may or may not include the computed graph.
    *
-   * @stub Graph computation ships in PRD-00268 (buildCapabilityGraph).
+   * @see capability-graph.ts for buildCapabilityGraph() implementation
    */
   graph?: CapabilityGraph
 }

package/src/usage/types.ts

@@ -46,6 +46,9 @@ export interface UsageByUser {
   requestCount: number;
 }
 
+/**
+ * @deprecated Use UnifiedUsageResponse instead. Will be removed in v1.0.
+ */
 export interface OrgUsageResponse {
   summary: UsageSummary;
   daily: DailyUsage[];
@@ -53,3 +56,64 @@ export interface OrgUsageResponse {
   byFeature: UsageByFeature[];
   topUsers: UsageByUser[];
 }
+
+// ---------------------------------------------------------------------------
+// Unified Usage Response (PRD-00276/277)
+// ---------------------------------------------------------------------------
+
+export interface UnifiedUsageSummary {
+  executions: number;
+  totalCostUsd: string;
+  totalTokens: number;
+  avgDurationMs: number;
+  failureRate: number;
+}
+
+export interface UnifiedDailyUsage {
+  date: string;
+  executions: number;
+  totalCostUsd: string;
+}
+
+export interface UnifiedProfileUsage {
+  profile: string;
+  executions: number;
+  percentOfTotal: number;
+  totalCostUsd: string;
+  avgDurationMs: number;
+  failureRate: number;
+}
+
+export interface UnifiedUserUsage {
+  userId: string;
+  email: string;
+  executions: number;
+  totalCostUsd: string;
+  totalTokens: number;
+  favoriteProfile: string;
+}
+
+export interface UnifiedModelUsage {
+  model: string;
+  provider: string;
+  totalTokens: number;
+  estimatedCostUsd: string;
+  requestCount: number;
+}
+
+export interface UnifiedFeatureUsage {
+  feature: string;
+  totalTokens: number;
+  estimatedCostUsd: string;
+  requestCount: number;
+}
+
+export interface UnifiedUsageResponse {
+  period: { start: string; end: string };
+  summary: UnifiedUsageSummary;
+  daily: UnifiedDailyUsage[];
+  byProfile: UnifiedProfileUsage[];
+  byUser: UnifiedUserUsage[];
+  byModel: UnifiedModelUsage[];
+  byFeature: UnifiedFeatureUsage[];
+}