@company-semantics/contracts 0.88.0 → 0.90.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.88.0",
+  "version": "0.90.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[] = [
@@ -108,6 +107,20 @@ describe('decision table key consistency', () => {
     const decisionKeys = Object.keys(LIFECYCLE_DECISIONS.confirm).sort()
     expect(decisionKeys).toEqual(transitionKeys)
   })
+
+  it('LIFECYCLE_DECISIONS.reject keys match VALID_TRANSITIONS keys', () => {
+    const transitionKeys = Object.keys(VALID_TRANSITIONS).sort()
+    const decisionKeys = Object.keys(LIFECYCLE_DECISIONS.reject).sort()
+    expect(decisionKeys).toEqual(transitionKeys)
+  })
+
+  it('all intent rows have the same set of state keys', () => {
+    const intents = Object.keys(LIFECYCLE_DECISIONS) as Array<keyof typeof LIFECYCLE_DECISIONS>
+    const referenceKeys = Object.keys(LIFECYCLE_DECISIONS[intents[0]]).sort()
+    for (const intent of intents) {
+      expect(Object.keys(LIFECYCLE_DECISIONS[intent]).sort()).toEqual(referenceKeys)
+    }
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -158,48 +171,37 @@ describe('applyIntent', () => {
   it('undone + confirm = conflict', () => {
     expect(applyIntent('undone', 'confirm')).toBe('conflict')
   })
-})
-
-// ---------------------------------------------------------------------------
-// 7. EXECUTION_ERROR 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('pending_confirmation + reject = approve', () => {
+    expect(applyIntent('pending_confirmation', 'reject')).toBe('approve')
   })
 
-  it('has correct message', () => {
-    const err = new ExecutionError('execution_not_found', 'not found', 404)
-    expect(err.message).toBe('not found')
+  it('expired + reject = expired', () => {
+    expect(applyIntent('expired', 'reject')).toBe('expired')
   })
 
-  it('has correct httpStatus', () => {
-    const err = new ExecutionError('execution_forbidden', 'forbidden', 403)
-    expect(err.httpStatus).toBe(403)
+  it('cancelled + reject = conflict', () => {
+    expect(applyIntent('cancelled', 'reject')).toBe('conflict')
   })
 
-  it('httpStatus is optional', () => {
-    const err = new ExecutionError('execution_expired', 'expired')
-    expect(err.httpStatus).toBeUndefined()
+  it('ready + reject = conflict', () => {
+    expect(applyIntent('ready', 'reject')).toBe('conflict')
   })
 
-  it('instanceof Error works', () => {
-    const err = new ExecutionError('execution_expired', 'expired', 410)
-    expect(err).toBeInstanceOf(Error)
+  it('executing + reject = conflict', () => {
+    expect(applyIntent('executing', 'reject')).toBe('conflict')
   })
 
-  it('instanceof ExecutionError works', () => {
-    const err = new ExecutionError('execution_expired', 'expired', 410)
-    expect(err).toBeInstanceOf(ExecutionError)
+  it('completed + reject = conflict', () => {
+    expect(applyIntent('completed', 'reject')).toBe('conflict')
   })
+})
 
-  it('supports all error codes', () => {
+// ---------------------------------------------------------------------------
+// 7. EXECUTION_ERROR TYPE TESTS
+// ---------------------------------------------------------------------------
+describe('ExecutionErrorCode', () => {
+  it('covers all expected error codes', () => {
     const codes: ExecutionErrorCode[] = [
       'execution_expired',
       'execution_already_confirmed',
@@ -208,11 +210,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,8 @@ 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;
 }

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/execution/lifecycle.ts

@@ -1,6 +1,6 @@
 import type { ExecutionState } from './status';
 
-export type ExecutionIntent = 'confirm';
+export type ExecutionIntent = 'confirm' | 'reject';
 
 export type LifecycleDecision =
   | 'approve'
@@ -29,6 +29,20 @@ export const LIFECYCLE_DECISIONS: DecisionTable = {
     failed_with_partial_execution: 'conflict',
     undone: 'conflict',
   },
+  reject: {
+    pending_confirmation: 'approve',
+    expired: 'expired',
+    cancelled: 'conflict',
+    blocked_pending_approval: 'conflict',
+    ready: 'conflict',
+    executing: 'conflict',
+    completed: 'conflict',
+    completed_with_rollbacks: 'conflict',
+    failed_retryable: 'conflict',
+    failed_terminal: 'conflict',
+    failed_with_partial_execution: 'conflict',
+    undone: 'conflict',
+  },
 };
 
 export function applyIntent(

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[];
+}