@intutic/shared-types 0.1.0

package/.dist/anomaly.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Anomaly detection types for the Anomaly Recognition Engine (ARE).
+ *
+ * These types support the 12-category runtime anomaly taxonomy,
+ * corrective prompt card system, trust scoring, and ARE probe battery.
+ *
+ * HLD §3.5 (Anomaly Detection), HLD §7.7 (Drift Detector)
+ * LLD #5 — Anomaly Detection + ARE
+ *
+ * @module
+ */
+import type { AnomalyType } from './enums.js';
+/**
+ * A detected anomaly event emitted by the ARE pipeline.
+ *
+ * Anomaly events are evaluated per-trace and may trigger enforcement
+ * actions, governance incidents, or corrective prompt injection.
+ *
+ * HLD §3.5 — 12-category runtime taxonomy
+ */
+export interface AnomalyEvent {
+    /** Classification from the 12-category anomaly taxonomy. */
+    type: AnomalyType;
+    /** Detection confidence score (0.0–1.0). */
+    confidence: number;
+    /** Optional structured metadata for forensic analysis. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Full classification result from the anomaly detector.
+ * Includes severity mapping and whether an incident was created.
+ *
+ * LLD #5 §2.2 — classifyAnomaly() return type
+ */
+export interface AnomalyClassification {
+    /** Whether an anomaly was detected. */
+    detected: boolean;
+    /** Classification from the 12-category taxonomy. Null if not detected. */
+    anomalyType: AnomalyType | null;
+    /** Detection confidence score (0.0–1.0). */
+    confidence: number;
+    /** Severity level derived from anomaly type. */
+    severity: AnomalySeverity;
+    /** Generated corrective prompt card, if applicable. */
+    correctiveCard: CorrectivePromptCard | null;
+    /** Probe results that contributed to the classification. */
+    probeResults: ProbeResult[];
+    /** ID of the governance incident created, if severity >= HIGH. */
+    incidentId: string | null;
+}
+/**
+ * Anomaly severity levels, mapped from anomaly type.
+ *
+ * HLD §3.5 — Alert Route column
+ */
+export type AnomalySeverity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'INFORMATIONAL';
+/**
+ * Static mapping from anomaly type to default severity.
+ *
+ * HLD §3.5 — 12-category table, Alert Route column
+ * LLD #5 Appendix B
+ */
+export declare const ANOMALY_SEVERITY_MAP: Record<AnomalyType, AnomalySeverity>;
+/**
+ * A corrective prompt card generated in response to an anomaly.
+ *
+ * Prompt cards contain a remediation prompt, evidence chain, and a
+ * link to the SOP that governs the expected behavior. They are injected
+ * into the agent context to steer it back on track.
+ *
+ * HLD §3.5 — Corrective prompt injection
+ */
+export interface CorrectivePromptCard {
+    /** The corrective prompt text to inject into agent context. */
+    promptText: string;
+    /** Confidence that this prompt will resolve the anomaly (0.0–1.0). */
+    confidence: number;
+    /** Evidence chain supporting the corrective action. */
+    sourceEvidence: string[];
+    /** SOP ID that defines the expected behavior — `newId('sp')`. */
+    sopId: string | null;
+}
+/**
+ * ARE probe tier classification.
+ *
+ * HLD §3.5 — ARE Probe Battery table
+ */
+export type ProbeType = 'PATTERN' | 'SCHEMA' | 'LLM';
+/**
+ * Result from an individual ARE probe execution.
+ *
+ * LLD #5 §2.2 — runProbes() return type
+ */
+export interface ProbeResult {
+    /** Probe tier. */
+    probeType: ProbeType;
+    /** Probe name (e.g., 'WorkspaceHygieneProbe', 'MCPHealthProbe'). */
+    probeName: string;
+    /** Whether the probe detected an issue. */
+    triggered: boolean;
+    /** Confidence score if triggered (0.0–1.0). */
+    confidence: number;
+    /** Whether the probe was skipped (e.g., LLM probe in Phase 1). */
+    skipped: boolean;
+    /** Reason for skip if applicable. */
+    skipReason?: string;
+    /** Execution latency in milliseconds. */
+    latencyMs: number;
+    /** Additional probe-specific details. */
+    details?: Record<string, unknown>;
+}
+/**
+ * Trust score for a user/agent within a workspace.
+ *
+ * LLD #5 §4.4 — Trust Score Algorithm
+ * Decay: score * 0.85 per anomaly
+ * Boost: score * 1.02 per clean session
+ * Clamped to [0, 100]. Initial: 80.
+ */
+export interface TrustScoreResult {
+    /** Trust score ID — `newId('ts')`. */
+    scoreId: string;
+    /** Workspace ID. */
+    workspaceId: string;
+    /** User/agent ID. */
+    userId: string;
+    /** Current trust score (0–100). */
+    currentScore: number;
+    /** Total anomaly count. */
+    anomalyCount: number;
+    /** Total clean sessions. */
+    cleanSessions: number;
+    /** Timestamp of last anomaly. */
+    lastAnomalyAt: string | null;
+    /** Timestamp of last boost. */
+    lastBoostAt: string | null;
+}
+/**
+ * Result of a trust score update operation.
+ *
+ * LLD #5 §2.2 — updateTrustScore() return type
+ */
+export interface TrustScoreUpdate {
+    /** Previous score before update. */
+    previousScore: number;
+    /** New score after update. */
+    newScore: number;
+    /** Delta applied. */
+    delta: number;
+    /** Reason for the update. */
+    reason: string;
+}
+/**
+ * Events that can modify a trust score.
+ *
+ * LLD #5 §4.4
+ */
+export interface TrustEvent {
+    type: 'ANOMALY_DETECTED' | 'CLEAN_SESSION';
+    anomalyType?: AnomalyType;
+    traceId?: string;
+    sessionId?: string;
+}
+import type { IncidentStatus } from './enums.js';
+/**
+ * @deprecated Use {@link IncidentStatus} from enums.ts instead.
+ * Kept as alias for backward compatibility.
+ */
+export type GovernanceIncidentStatus = IncidentStatus;
+/**
+ * CAPABILITY_MISS event — logged when an agent encounters a task
+ * for which no governing SOP exists.
+ *
+ * HLD §3.5 — CAPABILITY_MISS (Non-Anomaly Informational Event)
+ */
+export interface CapabilityMissEvent {
+    /** Miss ID — `newId('cm')`. */
+    missId: string;
+    /** Workspace ID. */
+    workspaceId: string;
+    /** Session ID where the miss occurred. */
+    sessionId: string | null;
+    /** Brief description of the ungoverned task. */
+    taskDescription: string;
+    /** Tools the agent attempted. */
+    toolSequence: string[];
+    /** Closest SOP by embedding similarity, or null. */
+    nearestSopId: string | null;
+    /** How close the nearest SOP was (0.0–1.0). */
+    similarityScore: number | null;
+    /** Recommended action for Dream Cycle. */
+    recommendedAction: 'AUTHOR_NEW_SOP' | 'EXTEND_EXISTING_SOP';
+}
+/**
+ * Input for recording a capability miss.
+ *
+ * LLD #5 §2.2 — recordCapabilityMiss() parameter
+ */
+export interface CapabilityMissInput {
+    workspaceId: string;
+    sessionId?: string;
+    taskDescription: string;
+    toolSequence: string[];
+    nearestSopId?: string;
+    similarityScore?: number;
+    recommendedAction?: 'AUTHOR_NEW_SOP' | 'EXTEND_EXISTING_SOP';
+}
+/**
+ * Drift direction classification.
+ *
+ * HLD §7.7 — Behavioral Drift Detector
+ */
+export type DriftDirection = 'POSITIVE_DRIFT' | 'NEGATIVE_DRIFT' | 'NEUTRAL_DRIFT';
+/**
+ * Drift detection event payload.
+ *
+ * LLD #5 §2.3 — anomaly.drift.detected event
+ */
+export interface DriftEvent {
+    workspaceId: string;
+    sopId: string;
+    driftScore: number;
+    driftDirection: DriftDirection;
+    baselineScore: number;
+    currentScore: number;
+}
+//# sourceMappingURL=anomaly.d.ts.map

package/.dist/anomaly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anomaly.d.ts","sourceRoot":"","sources":["../src/anomaly.ts"],"names":[],"mappings":"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"}

package/.dist/anomaly.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Anomaly detection types for the Anomaly Recognition Engine (ARE).
+ *
+ * These types support the 12-category runtime anomaly taxonomy,
+ * corrective prompt card system, trust scoring, and ARE probe battery.
+ *
+ * HLD §3.5 (Anomaly Detection), HLD §7.7 (Drift Detector)
+ * LLD #5 — Anomaly Detection + ARE
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANOMALY_SEVERITY_MAP = void 0;
+/**
+ * Static mapping from anomaly type to default severity.
+ *
+ * HLD §3.5 — 12-category table, Alert Route column
+ * LLD #5 Appendix B
+ */
+exports.ANOMALY_SEVERITY_MAP = {
+    TOOL_ABUSE: 'HIGH',
+    TOKEN_WASTE: 'MEDIUM',
+    LOOP_DETECTED: 'HIGH',
+    UNAUTHORIZED_TOOL: 'HIGH',
+    DATA_EXFILTRATION: 'CRITICAL',
+    PROMPT_INJECTION: 'CRITICAL',
+    HALLUCINATION: 'HIGH',
+    SCOPE_VIOLATION: 'MEDIUM',
+    BUDGET_BREACH: 'HIGH',
+    SPAWN_BUDGET_BREACH: 'HIGH',
+    WORKFLOW_BUDGET_BREACH: 'HIGH',
+    WORKFLOW_GOAL_DRIFT: 'MEDIUM',
+};
+//# sourceMappingURL=anomaly.js.map

package/.dist/anomaly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anomaly.js","sourceRoot":"","sources":["../src/anomaly.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAiEH;;;;;GAKG;AACU,QAAA,oBAAoB,GAAyC;IACxE,UAAU,EAAE,MAAM;IAClB,WAAW,EAAE,QAAQ;IACrB,aAAa,EAAE,MAAM;IACrB,iBAAiB,EAAE,MAAM;IACzB,iBAAiB,EAAE,UAAU;IAC7B,gBAAgB,EAAE,UAAU;IAC5B,aAAa,EAAE,MAAM;IACrB,eAAe,EAAE,QAAQ;IACzB,aAAa,EAAE,MAAM;IACrB,mBAAmB,EAAE,MAAM;IAC3B,sBAAsB,EAAE,MAAM;IAC9B,mBAAmB,EAAE,QAAQ;CACrB,CAAA"}

package/.dist/api-contracts.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Zod schemas for API request/response validation.
+ *
+ * Each schema is exported alongside its inferred TypeScript type.
+ * Services use these schemas in route handlers to validate incoming
+ * payloads; the inferred types are used in service function signatures.
+ *
+ * HLD §3.1 (Proxy Gateway), §3.6 (FinOps), §3.3 (PCAS)
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for the `POST /api/v1/sessions` request body.
+ *
+ * Creates a new agent session in the control plane.
+ */
+export declare const CreateSessionSchema: z.ZodObject<{
+    /** Workspace to create the session in. */
+    workspaceId: z.ZodString;
+    /** User initiating the session. */
+    userId: z.ZodString;
+    /** Optional project to scope the session. */
+    projectId: z.ZodOptional<z.ZodString>;
+    /** Optional SOP to govern the session. */
+    activeSopId: z.ZodOptional<z.ZodString>;
+    /** Agent harness type. */
+    harnessType: z.ZodEnum<["cursor" | "claude-code" | "antigravity" | "n8n" | "codex" | "windsurf" | "aider" | "openhands" | "openclaw" | "hermes" | "pi", ...("cursor" | "claude-code" | "antigravity" | "n8n" | "codex" | "windsurf" | "aider" | "openhands" | "openclaw" | "hermes" | "pi")[]]>;
+    /** Budget tier — defaults to JUNIOR on the server. */
+    budgetTier: z.ZodOptional<z.ZodEnum<["JUNIOR" | "SENIOR" | "STAFF" | "PRINCIPAL", ...("JUNIOR" | "SENIOR" | "STAFF" | "PRINCIPAL")[]]>>;
+    /** Execution mode — defaults to STANDARD on the server. */
+    executionMode: z.ZodOptional<z.ZodEnum<["STANDARD" | "PLAN_ONLY" | "SHADOW" | "AUTONOMOUS", ...("STANDARD" | "PLAN_ONLY" | "SHADOW" | "AUTONOMOUS")[]]>>;
+}, "strip", z.ZodTypeAny, {
+    workspaceId: string;
+    userId: string;
+    harnessType: "cursor" | "claude-code" | "antigravity" | "n8n" | "codex" | "windsurf" | "aider" | "openhands" | "openclaw" | "hermes" | "pi";
+    projectId?: string | undefined;
+    activeSopId?: string | undefined;
+    budgetTier?: "JUNIOR" | "SENIOR" | "STAFF" | "PRINCIPAL" | undefined;
+    executionMode?: "STANDARD" | "PLAN_ONLY" | "SHADOW" | "AUTONOMOUS" | undefined;
+}, {
+    workspaceId: string;
+    userId: string;
+    harnessType: "cursor" | "claude-code" | "antigravity" | "n8n" | "codex" | "windsurf" | "aider" | "openhands" | "openclaw" | "hermes" | "pi";
+    projectId?: string | undefined;
+    activeSopId?: string | undefined;
+    budgetTier?: "JUNIOR" | "SENIOR" | "STAFF" | "PRINCIPAL" | undefined;
+    executionMode?: "STANDARD" | "PLAN_ONLY" | "SHADOW" | "AUTONOMOUS" | undefined;
+}>;
+/** Inferred type for a create-session request payload. */
+export type CreateSessionInput = z.infer<typeof CreateSessionSchema>;
+/**
+ * Zod schema for the `POST /api/v1/traces` request body.
+ *
+ * Appends a new row to the `execution_traces` ledger.
+ * Fields with server-side defaults (e.g., `timestamp`) are optional.
+ */
+export declare const CreateTraceSchema: z.ZodObject<{
+    /** Session that produced this trace. */
+    sessionId: z.ZodString;
+    /** Idempotency key — must be unique across all traces. */
+    requestId: z.ZodString;
+    /** Effective date of the governing SOP (ISO 8601). */
+    sopEffectiveDate: z.ZodString;
+    requestedModel: z.ZodString;
+    actualModelRouted: z.ZodString;
+    routingTier: z.ZodEnum<["frontier" | "economy" | "local", ...("frontier" | "economy" | "local")[]]>;
+    complexityScore: z.ZodNumber;
+    rawInputTokens: z.ZodNumber;
+    compressedInputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    rawCostUsd: z.ZodNumber;
+    actualCostUsd: z.ZodNumber;
+    tokenUtility: z.ZodOptional<z.ZodEnum<["USEFUL" | "WASTED", ...("USEFUL" | "WASTED")[]]>>;
+    tokenUtilityScore: z.ZodOptional<z.ZodNumber>;
+    complianceScore: z.ZodNumber;
+    enforcementAction: z.ZodEnum<["BYPASS" | "ENHANCE" | "HIJACK" | "KILL", ...("BYPASS" | "ENHANCE" | "HIJACK" | "KILL")[]]>;
+    anomalyDetected: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    anomalyConfidenceScore: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    taxonomyMetadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    rawPayloadJson: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    appId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agentChainId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agentChain: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    cacheHit: z.ZodOptional<z.ZodBoolean>;
+    cacheSavingsUsd: z.ZodOptional<z.ZodNumber>;
+    rootCauseAttribution: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    correctivePromptCard: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    requestId: string;
+    sopEffectiveDate: string;
+    requestedModel: string;
+    actualModelRouted: string;
+    routingTier: "frontier" | "economy" | "local";
+    complexityScore: number;
+    rawInputTokens: number;
+    compressedInputTokens: number;
+    outputTokens: number;
+    rawCostUsd: number;
+    actualCostUsd: number;
+    complianceScore: number;
+    enforcementAction: "BYPASS" | "ENHANCE" | "HIJACK" | "KILL";
+    tokenUtility?: "USEFUL" | "WASTED" | undefined;
+    tokenUtilityScore?: number | undefined;
+    anomalyDetected?: string | null | undefined;
+    anomalyConfidenceScore?: number | null | undefined;
+    taxonomyMetadata?: Record<string, unknown> | null | undefined;
+    rawPayloadJson?: Record<string, unknown> | null | undefined;
+    appId?: string | null | undefined;
+    agentChainId?: string | null | undefined;
+    agentChain?: Record<string, unknown> | null | undefined;
+    cacheHit?: boolean | undefined;
+    cacheSavingsUsd?: number | undefined;
+    rootCauseAttribution?: Record<string, unknown> | null | undefined;
+    correctivePromptCard?: Record<string, unknown> | null | undefined;
+}, {
+    sessionId: string;
+    requestId: string;
+    sopEffectiveDate: string;
+    requestedModel: string;
+    actualModelRouted: string;
+    routingTier: "frontier" | "economy" | "local";
+    complexityScore: number;
+    rawInputTokens: number;
+    compressedInputTokens: number;
+    outputTokens: number;
+    rawCostUsd: number;
+    actualCostUsd: number;
+    complianceScore: number;
+    enforcementAction: "BYPASS" | "ENHANCE" | "HIJACK" | "KILL";
+    tokenUtility?: "USEFUL" | "WASTED" | undefined;
+    tokenUtilityScore?: number | undefined;
+    anomalyDetected?: string | null | undefined;
+    anomalyConfidenceScore?: number | null | undefined;
+    taxonomyMetadata?: Record<string, unknown> | null | undefined;
+    rawPayloadJson?: Record<string, unknown> | null | undefined;
+    appId?: string | null | undefined;
+    agentChainId?: string | null | undefined;
+    agentChain?: Record<string, unknown> | null | undefined;
+    cacheHit?: boolean | undefined;
+    cacheSavingsUsd?: number | undefined;
+    rootCauseAttribution?: Record<string, unknown> | null | undefined;
+    correctivePromptCard?: Record<string, unknown> | null | undefined;
+}>;
+/** Inferred type for a create-trace request payload. */
+export type CreateTraceInput = z.infer<typeof CreateTraceSchema>;
+/**
+ * Zod schema for a policy verdict (used in Circuit Breaker responses
+ * and inter-service communication).
+ *
+ * HLD §3.3 — PCAS enforcement
+ */
+export declare const PolicyVerdictSchema: z.ZodObject<{
+    /** Enforcement action to apply. */
+    action: z.ZodEnum<["BYPASS" | "ENHANCE" | "HIJACK" | "KILL", ...("BYPASS" | "ENHANCE" | "HIJACK" | "KILL")[]]>;
+    /** Confidence score (0.0–1.0). */
+    confidence: z.ZodNumber;
+    /** Human-readable reason. */
+    reason: z.ZodString;
+    /** Optional policy rule ID. */
+    policyId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "BYPASS" | "ENHANCE" | "HIJACK" | "KILL";
+    confidence: number;
+    reason: string;
+    policyId?: string | undefined;
+}, {
+    action: "BYPASS" | "ENHANCE" | "HIJACK" | "KILL";
+    confidence: number;
+    reason: string;
+    policyId?: string | undefined;
+}>;
+/** Inferred type for a policy verdict. */
+export type PolicyVerdictInput = z.infer<typeof PolicyVerdictSchema>;
+//# sourceMappingURL=api-contracts.d.ts.map

package/.dist/api-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-contracts.d.ts","sourceRoot":"","sources":["../src/api-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAmBvB;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B,0CAA0C;;IAG1C,mCAAmC;;IAGnC,6CAA6C;;IAG7C,0CAA0C;;IAG1C,0BAA0B;;IAG1B,sDAAsD;;IAGtD,2DAA2D;;;;;;;;;;;;;;;;;;EAE3D,CAAA;AAEF,0DAA0D;AAC1D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAIpE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;IAC5B,wCAAwC;;IAGxC,0DAA0D;;IAG1D,sDAAsD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8CtD,CAAA;AAEF,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAIhE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;IAC9B,mCAAmC;;IAGnC,kCAAkC;;IAGlC,6BAA6B;;IAG7B,+BAA+B;;;;;;;;;;;;EAE/B,CAAA;AAEF,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/.dist/api-contracts.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Zod schemas for API request/response validation.
+ *
+ * Each schema is exported alongside its inferred TypeScript type.
+ * Services use these schemas in route handlers to validate incoming
+ * payloads; the inferred types are used in service function signatures.
+ *
+ * HLD §3.1 (Proxy Gateway), §3.6 (FinOps), §3.3 (PCAS)
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyVerdictSchema = exports.CreateTraceSchema = exports.CreateSessionSchema = void 0;
+const zod_1 = require("zod");
+const enums_js_1 = require("./enums.js");
+// ─── Helpers ─────────────────────────────────────────────────────────
+/** Extract the values array from a const object for use in `z.enum()`. */
+function constValues(obj) {
+    return Object.values(obj);
+}
+// ─── CreateSession ───────────────────────────────────────────────────
+/**
+ * Zod schema for the `POST /api/v1/sessions` request body.
+ *
+ * Creates a new agent session in the control plane.
+ */
+exports.CreateSessionSchema = zod_1.z.object({
+    /** Workspace to create the session in. */
+    workspaceId: zod_1.z.string().min(1),
+    /** User initiating the session. */
+    userId: zod_1.z.string().min(1),
+    /** Optional project to scope the session. */
+    projectId: zod_1.z.string().min(1).optional(),
+    /** Optional SOP to govern the session. */
+    activeSopId: zod_1.z.string().min(1).optional(),
+    /** Agent harness type. */
+    harnessType: zod_1.z.enum(constValues(enums_js_1.HarnessType)),
+    /** Budget tier — defaults to JUNIOR on the server. */
+    budgetTier: zod_1.z.enum(constValues(enums_js_1.BudgetTier)).optional(),
+    /** Execution mode — defaults to STANDARD on the server. */
+    executionMode: zod_1.z.enum(constValues(enums_js_1.ExecutionMode)).optional(),
+});
+// ─── CreateTrace ─────────────────────────────────────────────────────
+/**
+ * Zod schema for the `POST /api/v1/traces` request body.
+ *
+ * Appends a new row to the `execution_traces` ledger.
+ * Fields with server-side defaults (e.g., `timestamp`) are optional.
+ */
+exports.CreateTraceSchema = zod_1.z.object({
+    /** Session that produced this trace. */
+    sessionId: zod_1.z.string().min(1),
+    /** Idempotency key — must be unique across all traces. */
+    requestId: zod_1.z.string().min(1),
+    /** Effective date of the governing SOP (ISO 8601). */
+    sopEffectiveDate: zod_1.z.string().datetime(),
+    // ── Model routing ──
+    requestedModel: zod_1.z.string().min(1),
+    actualModelRouted: zod_1.z.string().min(1),
+    routingTier: zod_1.z.enum(constValues(enums_js_1.RoutingTier)),
+    complexityScore: zod_1.z.number().min(0).max(1),
+    // ── Token accounting ──
+    rawInputTokens: zod_1.z.number().int().nonnegative(),
+    compressedInputTokens: zod_1.z.number().int().nonnegative(),
+    outputTokens: zod_1.z.number().int().nonnegative(),
+    // ── Cost accounting ──
+    rawCostUsd: zod_1.z.number().nonnegative(),
+    actualCostUsd: zod_1.z.number().nonnegative(),
+    // ── Token utility ──
+    tokenUtility: zod_1.z.enum(constValues(enums_js_1.TokenUtility)).optional(),
+    tokenUtilityScore: zod_1.z.number().min(0).max(1).optional(),
+    // ── Enforcement ──
+    complianceScore: zod_1.z.number().min(0).max(1),
+    enforcementAction: zod_1.z.enum(constValues(enums_js_1.EnforcementAction)),
+    // ── Anomaly ──
+    anomalyDetected: zod_1.z.string().nullable().optional(),
+    anomalyConfidenceScore: zod_1.z.number().min(0).max(1).nullable().optional(),
+    taxonomyMetadata: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+    // ── Forensics ──
+    rawPayloadJson: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+    // ── 4D Attribution ──
+    appId: zod_1.z.string().nullable().optional(),
+    agentChainId: zod_1.z.string().nullable().optional(),
+    agentChain: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+    // ── Cache ──
+    cacheHit: zod_1.z.boolean().optional(),
+    cacheSavingsUsd: zod_1.z.number().nonnegative().optional(),
+    // ── Root cause ──
+    rootCauseAttribution: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+    correctivePromptCard: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+});
+// ─── PolicyVerdict ───────────────────────────────────────────────────
+/**
+ * Zod schema for a policy verdict (used in Circuit Breaker responses
+ * and inter-service communication).
+ *
+ * HLD §3.3 — PCAS enforcement
+ */
+exports.PolicyVerdictSchema = zod_1.z.object({
+    /** Enforcement action to apply. */
+    action: zod_1.z.enum(constValues(enums_js_1.EnforcementAction)),
+    /** Confidence score (0.0–1.0). */
+    confidence: zod_1.z.number().min(0).max(1),
+    /** Human-readable reason. */
+    reason: zod_1.z.string().min(1),
+    /** Optional policy rule ID. */
+    policyId: zod_1.z.string().optional(),
+});
+//# sourceMappingURL=api-contracts.js.map

package/.dist/api-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-contracts.js","sourceRoot":"","sources":["../src/api-contracts.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,6BAAuB;AACvB,yCAOmB;AAEnB,wEAAwE;AAExE,0EAA0E;AAC1E,SAAS,WAAW,CAAmC,GAAM;IAC3D,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAkC,CAAA;AAC5D,CAAC;AAED,wEAAwE;AAExE;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC1C,0CAA0C;IAC1C,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE9B,mCAAmC;IACnC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEzB,6CAA6C;IAC7C,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEvC,0CAA0C;IAC1C,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEzC,0BAA0B;IAC1B,WAAW,EAAE,OAAC,CAAC,IAAI,CAAC,WAAW,CAAC,sBAAW,CAAC,CAAC;IAE7C,sDAAsD;IACtD,UAAU,EAAE,OAAC,CAAC,IAAI,CAAC,WAAW,CAAC,qBAAU,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEtD,2DAA2D;IAC3D,aAAa,EAAE,OAAC,CAAC,IAAI,CAAC,WAAW,CAAC,wBAAa,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC7D,CAAC,CAAA;AAKF,wEAAwE;AAExE;;;;;GAKG;AACU,QAAA,iBAAiB,GAAG,OAAC,CAAC,MAAM,CAAC;IACxC,wCAAwC;IACxC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE5B,0DAA0D;IAC1D,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE5B,sDAAsD;IACtD,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAEvC,sBAAsB;IACtB,cAAc,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,iBAAiB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC,WAAW,EAAE,OAAC,CAAC,IAAI,CAAC,WAAW,CAAC,sBAAW,CAAC,CAAC;IAC7C,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAEzC,yBAAyB;IACzB,cAAc,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC9C,qBAAqB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACrD,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAE5C,wBAAwB;IACxB,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACpC,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IAEvC,sBAAsB;IACtB,YAAY,EAAE,OAAC,CAAC,IAAI,CAAC,WAAW,CAAC,uBAAY,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1D,iBAAiB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEtD,oBAAoB;IACpB,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,iBAAiB,EAAE,OAAC,CAAC,IAAI,CAAC,WAAW,CAAC,4BAAiB,CAAC,CAAC;IAEzD,gBAAgB;IAChB,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACjD,sBAAsB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACtE,gBAAgB,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAE7D,kBAAkB;IAClB,cAAc,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAE3D,uBAAuB;IACvB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACvC,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC9C,UAAU,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAEvD,cAAc;IACd,QAAQ,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAEpD,mBAAmB;IACnB,oBAAoB,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACjE,oBAAoB,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAClE,CAAC,CAAA;AAKF,wEAAwE;AAExE;;;;;GAKG;AACU,QAAA,mBAAmB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC1C,mCAAmC;IACnC,MAAM,EAAE,OAAC,CAAC,IAAI,CAAC,WAAW,CAAC,4BAAiB,CAAC,CAAC;IAE9C,kCAAkC;IAClC,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAEpC,6BAA6B;IAC7B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEzB,+BAA+B;IAC/B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAA"}