@company-semantics/contracts 0.82.0 → 0.83.0

package/package.json

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

package/src/execution/audit-export.ts

@@ -0,0 +1,67 @@
+import type { ExecutionEventType } from './events';
+import type { ExecutionIntent } from './types';
+import type { HashChainVerificationResult } from './hash-chain';
+
+/**
+ * Immutable governance snapshot captured at execution creation time.
+ * Stored in execution_audit.frozen_intent JSONB column.
+ *
+ * Semantically distinct from ExecutionIntent: this represents what was true
+ * at creation time, not what the registry currently says.
+ * frozenIntentHash enables tamper detection if JSONB is modified by privileged DBA.
+ */
+export type FrozenExecutionIntent = Readonly<ExecutionIntent> & {
+  /** ISO 8601 timestamp of when this snapshot was captured */
+  frozenAt: string;
+  /** SHA-256 of canonicalized frozen intent — for tamper detection */
+  frozenIntentHash: string;
+};
+
+/**
+ * Per-event shape within an audit export bundle.
+ * Events MUST be ordered by eventSequence ascending.
+ */
+export interface AuditExportEvent {
+  eventSequence: number;
+  eventType: ExecutionEventType;
+  stateAfter: string;
+  actorId: string;
+  actorType: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  eventHash: string;
+  previousHash: string | null;
+}
+
+/**
+ * Top-level audit export bundle for a single execution.
+ *
+ * Threat model:
+ * - hashChainValid: Detects internal DB tampering (single-row mutation)
+ * - frozenIntentHashValid: Detects frozen intent JSONB mutation
+ * - exportSignature (HMAC-SHA256): Proves this export was generated by this server.
+ *   Does NOT prove DB was not tampered prior to export.
+ *   Hash chaining + frozen intent hashing detect pre-export tampering.
+ */
+export interface AuditExportBundle {
+  /** Schema version for forward compatibility */
+  version: '1.0';
+  /** ISO 8601 timestamp of export generation */
+  exportedAt: string;
+  /** Execution ID */
+  executionId: string;
+  /** Organization ID */
+  orgId: string;
+  /** Frozen governance snapshot from execution_audit */
+  frozenIntent: FrozenExecutionIntent;
+  /** Whether frozen_intent_hash matches recomputed SHA-256(canonicalize(frozen_intent)) */
+  frozenIntentHashValid: boolean;
+  /** Event chain ordered by eventSequence ascending, with hash fields */
+  events: AuditExportEvent[];
+  /** Whether all event hashes recompute correctly */
+  hashChainValid: boolean;
+  /** Detailed chain verification result */
+  hashChainVerification: HashChainVerificationResult;
+  /** HMAC-SHA256 of bundle content. Present only if AUDIT_EXPORT_SIGNING_KEY is configured. */
+  exportSignature?: string;
+}

package/src/execution/event-metadata.ts

@@ -0,0 +1,103 @@
+import type { ExecutionEventType } from './events';
+import type { ExecutionIntent } from './types';
+
+/** Metadata for execution_created event. Frozen governance snapshot. */
+export interface ExecutionCreatedMetadata {
+  /** Full ExecutionIntent frozen at creation time — authoritative governance snapshot (INV-18) */
+  executionIntent: ExecutionIntent;
+  /** Number of artifacts in the execution */
+  artifactCount: number;
+  /** ISO 8601 confirmation deadline. Present when requiresConfirmation=true. */
+  expiresAt?: string;
+}
+
+/** Metadata for execution_started event. Intentionally empty. */
+export type ExecutionStartedMetadata = Record<string, never>;
+
+/** Metadata for confirmation_approved event. */
+export interface ConfirmationApprovedMetadata {
+  /** userId of the user who confirmed */
+  confirmedBy: string;
+}
+
+/** Metadata for confirmation_rejected event. */
+export interface ConfirmationRejectedMetadata {
+  /** userId of the user who rejected */
+  rejectedBy: string;
+  /** Optional reason for rejection */
+  reason?: string;
+}
+
+/** Metadata for confirmation_expired event. */
+export interface ConfirmationExpiredMetadata {
+  /** What triggered the expiration */
+  trigger: 'job' | 'confirm_attempt';
+  /** ISO 8601 timestamp when expiration was recorded */
+  expiredAt: string;
+  /** ISO 8601 original confirmation deadline */
+  originalExpiresAt: string;
+}
+
+/** Metadata for approval_requested event. Governance-metadata event. */
+export interface ApprovalRequestedMetadata {
+  /** Reason approval is required */
+  reason: string;
+  /** userId who triggered the approval request */
+  requestedBy: string;
+}
+
+/** Metadata for execution_completed event. Forward-compatible. */
+export interface ExecutionCompletedMetadata {
+  /** Human-readable result summary */
+  resultSummary?: string;
+  /** Number of artifacts executed */
+  artifactCount?: number;
+}
+
+/** Metadata for execution_failed event. Forward-compatible. */
+export interface ExecutionFailedMetadata {
+  /** Machine-readable error code */
+  errorCode?: string;
+  /** Error classification for retry decisions */
+  errorClass?: 'retryable' | 'terminal';
+  /** Human-readable error message */
+  message?: string;
+}
+
+/** Metadata for undo_completed event. Forward-compatible. */
+export interface UndoCompletedMetadata {
+  /** userId who initiated the undo */
+  undoneBy: string;
+}
+
+/** Metadata for cancelled event. Forward-compatible. */
+export interface CancelledMetadata {
+  /** userId who cancelled */
+  cancelledBy: string;
+  /** Optional cancellation reason */
+  reason?: string;
+}
+
+/**
+ * Exhaustive mapping from ExecutionEventType to its metadata interface.
+ * TypeScript enforces completeness — adding a new event type without
+ * a metadata definition here is a compile error.
+ */
+export interface ExecutionEventMetadataMap {
+  execution_created: ExecutionCreatedMetadata;
+  execution_started: ExecutionStartedMetadata;
+  confirmation_approved: ConfirmationApprovedMetadata;
+  confirmation_rejected: ConfirmationRejectedMetadata;
+  confirmation_expired: ConfirmationExpiredMetadata;
+  approval_requested: ApprovalRequestedMetadata;
+  execution_completed: ExecutionCompletedMetadata;
+  execution_failed: ExecutionFailedMetadata;
+  undo_completed: UndoCompletedMetadata;
+  cancelled: CancelledMetadata;
+}
+
+// Compile-time exhaustiveness check: this line errors if
+// ExecutionEventMetadataMap keys don't match ExecutionEventType
+type _ExhaustivenessCheck = {
+  [K in ExecutionEventType]: ExecutionEventMetadataMap[K];
+};

package/src/execution/events.ts

@@ -0,0 +1,37 @@
+/**
+ * Enumerates all valid event_type values for the execution_events table.
+ *
+ * Currently emitted: execution_created, execution_started, confirmation_approved,
+ * confirmation_rejected, confirmation_expired, approval_requested.
+ *
+ * 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';
+
+export const EXECUTION_EVENT_TYPES: readonly ExecutionEventType[] = [
+  'execution_created',
+  'execution_started',
+  'confirmation_approved',
+  'confirmation_rejected',
+  'confirmation_expired',
+  'approval_requested',
+  'execution_completed',
+  'execution_failed',
+  'undo_completed',
+  'cancelled',
+] as const;
+
+export function isExecutionEventType(value: string): value is ExecutionEventType {
+  return (EXECUTION_EVENT_TYPES as readonly string[]).includes(value);
+}

package/src/execution/hash-chain.ts

@@ -0,0 +1,40 @@
+/**
+ * Hash chain fields for tamper-evident execution events.
+ *
+ * Algorithm: SHA-256 over RFC 8785 JCS (JSON Canonicalization Scheme) input.
+ * Input: executionId + eventSequence + eventType + stateAfter + actorId + canonicalize(metadata) + (previousHash ?? 'NULL')
+ * created_at intentionally excluded — clock drift across replicas could break verification.
+ *
+ * Threat model: Detects single-row mutation where attacker does not recompute downstream hashes.
+ * Does NOT defend against fully malicious DBA who recomputes entire chain.
+ * External anchoring (periodic anchor hash stored outside DB) is a future enhancement.
+ */
+export interface EventHashFields {
+  /** SHA-256 hex digest (64 characters) of this event's canonicalized content */
+  eventHash: string;
+  /** SHA-256 hex digest of the previous event in this execution's chain, or null for the first event */
+  previousHash: string | null;
+}
+
+/**
+ * Result of verifying a hash chain for a single execution.
+ * If valid=false, brokenAtSequence indicates where the chain first breaks.
+ */
+export interface HashChainVerificationResult {
+  /** True if all event hashes recompute correctly and chain links are valid */
+  valid: boolean;
+  /** Event sequence number where chain integrity first fails (present only if valid=false) */
+  brokenAtSequence?: number;
+  /** What the recomputed hash should be (present only if valid=false) */
+  expectedHash?: string;
+  /** What was stored in the database (present only if valid=false) */
+  actualHash?: string;
+  /** True if frozen_intent_hash verification failed (present only if checked) */
+  frozenIntentMismatch?: boolean;
+}
+
+/** Hash algorithm used for event chain integrity */
+export const HASH_ALGORITHM = 'sha256' as const;
+
+/** Encoding for hash output */
+export const HASH_ENCODING = 'hex' as const;

package/src/execution/index.ts

@@ -7,6 +7,59 @@
  * @see ADR-CONT-029 for design rationale
  */
 
+// =============================================================================
+// Event Types
+// =============================================================================
+
+export type { ExecutionEventType } from './events'
+
+export {
+  EXECUTION_EVENT_TYPES,
+  isExecutionEventType,
+} from './events'
+
+// =============================================================================
+// Event Metadata Schemas
+// =============================================================================
+
+export type {
+  ExecutionCreatedMetadata,
+  ExecutionStartedMetadata,
+  ConfirmationApprovedMetadata,
+  ConfirmationRejectedMetadata,
+  ConfirmationExpiredMetadata,
+  ApprovalRequestedMetadata,
+  ExecutionCompletedMetadata,
+  ExecutionFailedMetadata,
+  UndoCompletedMetadata,
+  CancelledMetadata,
+  ExecutionEventMetadataMap,
+} from './event-metadata'
+
+// =============================================================================
+// Hash Chain Types
+// =============================================================================
+
+export type {
+  EventHashFields,
+  HashChainVerificationResult,
+} from './hash-chain'
+
+export {
+  HASH_ALGORITHM,
+  HASH_ENCODING,
+} from './hash-chain'
+
+// =============================================================================
+// Audit Export Types
+// =============================================================================
+
+export type {
+  FrozenExecutionIntent,
+  AuditExportEvent,
+  AuditExportBundle,
+} from './audit-export'
+
 // =============================================================================
 // Kind Types
 // =============================================================================

package/src/index.ts

@@ -305,6 +305,7 @@ export type {
   ConfirmationChoice,
   ConfirmationRiskLevel,
   ConfirmationData,
+  ConfirmationResponseData,
   ConfirmationDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
@@ -350,6 +351,7 @@ export {
 export type {
   ExecutionKind,
   ExecutionState,
+  ExecutionEventType,
   ISO8601Timestamp,
   IconName,
   ExecutionDomain,
@@ -368,6 +370,8 @@ export {
   EXECUTION_KINDS,
   getExecutionKindDefinition,
   isValidExecutionKind,
+  EXECUTION_EVENT_TYPES,
+  isExecutionEventType,
 } from './execution/index'
 
 // Ralph autonomous coding loop types

package/src/message-parts/confirmation.ts

@@ -69,6 +69,17 @@ export interface ConfirmationData {
 /**
  * Confirmation request message part (semantic type).
  */
+/**
+ * Data sent by the client to confirm or cancel a proposed action.
+ * Structured response only — no natural language inference.
+ */
+export interface ConfirmationResponseData {
+  /** Must match the active preview's actionId */
+  actionId: string;
+  /** User's explicit decision */
+  choice: ConfirmationChoice;
+}
+
 export interface ConfirmationPart {
   type: 'confirmation';
   data: ConfirmationData;

package/src/message-parts/index.ts

@@ -35,6 +35,7 @@ export type {
   ConfirmationChoice,
   ConfirmationRiskLevel,
   ConfirmationData,
+  ConfirmationResponseData,
   ConfirmationPart,
   ConfirmationDataPart,
 } from './confirmation'