@defai.digital/contracts 13.0.3

package/dist/resilience/v1/loop-guard.js

@@ -0,0 +1,96 @@
+/**
+ * Loop Guard Contract
+ *
+ * Prevents infinite loops and runaway execution that burns resources.
+ */
+import { z } from 'zod';
+// ============================================================================
+// Configuration
+// ============================================================================
+export const LoopGuardConfigSchema = z.object({
+    /** Maximum iterations before hard stop */
+    maxIterations: z.number().int().min(1).max(10000).default(100),
+    /** Iteration count that triggers warning */
+    warnAtIterations: z.number().int().min(1).max(10000).default(50),
+    /** Maximum execution duration in ms */
+    maxDurationMs: z.number().int().min(1000).max(3600000).default(300000), // 5 min
+    /** Duration that triggers warning in ms */
+    warnAtDurationMs: z.number().int().min(1000).max(3600000).default(120000), // 2 min
+});
+// ============================================================================
+// Context
+// ============================================================================
+export const LoopGuardContextSchema = z.object({
+    /** Unique context identifier */
+    contextId: z.string(),
+    /** Current iteration count */
+    iterations: z.number().int().min(0),
+    /** Start time */
+    startedAt: z.string().datetime(),
+    /** Elapsed time in ms */
+    elapsedMs: z.number().int().min(0),
+    /** Whether warning was already issued */
+    warningIssued: z.boolean(),
+    /** Context metadata */
+    metadata: z.record(z.unknown()).optional(),
+});
+// ============================================================================
+// Check Result
+// ============================================================================
+export const LoopGuardResultSchema = z.discriminatedUnion('status', [
+    z.object({
+        status: z.literal('ok'),
+        iteration: z.number().int().min(0),
+        elapsedMs: z.number().int().min(0),
+    }),
+    z.object({
+        status: z.literal('warning'),
+        iteration: z.number().int().min(0),
+        elapsedMs: z.number().int().min(0),
+        message: z.string(),
+        warningType: z.enum(['iteration', 'duration']),
+    }),
+    z.object({
+        status: z.literal('blocked'),
+        iteration: z.number().int().min(0),
+        elapsedMs: z.number().int().min(0),
+        reason: z.string(),
+        blockType: z.enum(['max-iterations', 'max-duration']),
+    }),
+]);
+// ============================================================================
+// Error Codes
+// ============================================================================
+export const LoopGuardErrorCodes = {
+    MAX_ITERATIONS: 'LOOP_GUARD_MAX_ITERATIONS',
+    MAX_DURATION: 'LOOP_GUARD_MAX_DURATION',
+    CONTEXT_NOT_FOUND: 'LOOP_GUARD_CONTEXT_NOT_FOUND',
+};
+// ============================================================================
+// Validation Functions
+// ============================================================================
+export function validateLoopGuardConfig(data) {
+    return LoopGuardConfigSchema.parse(data);
+}
+export function safeValidateLoopGuardConfig(data) {
+    const result = LoopGuardConfigSchema.safeParse(data);
+    if (result.success)
+        return { success: true, data: result.data };
+    return { success: false, error: result.error };
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+export function createDefaultLoopGuardConfig() {
+    return LoopGuardConfigSchema.parse({});
+}
+export function createLoopGuardContext(contextId) {
+    return {
+        contextId,
+        iterations: 0,
+        startedAt: new Date().toISOString(),
+        elapsedMs: 0,
+        warningIssued: false,
+    };
+}
+//# sourceMappingURL=loop-guard.js.map

package/dist/resilience/v1/loop-guard.js.map

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

package/dist/resilience/v1/metrics.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Metrics Contract
+ *
+ * Basic observability metrics for monitoring system health.
+ */
+import { z } from 'zod';
+export declare const MetricsTimeRangeSchema: z.ZodObject<{
+    /** Start time (ISO string or relative like '-1h', '-30m', '-1d') */
+    start: z.ZodString;
+    /** End time (ISO string or 'now') */
+    end: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    start: string;
+    end: string;
+}, {
+    start: string;
+    end?: string | undefined;
+}>;
+export type MetricsTimeRange = z.infer<typeof MetricsTimeRangeSchema>;
+export declare const RequestMetricSchema: z.ZodObject<{
+    /** Timestamp */
+    timestamp: z.ZodString;
+    /** Provider ID */
+    providerId: z.ZodString;
+    /** Operation type */
+    operation: z.ZodString;
+    /** Whether request succeeded */
+    success: z.ZodBoolean;
+    /** Duration in ms */
+    durationMs: z.ZodNumber;
+    /** Input tokens used */
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    /** Output tokens used */
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    /** Estimated cost */
+    estimatedCost: z.ZodOptional<z.ZodNumber>;
+    /** Error code if failed */
+    errorCode: z.ZodOptional<z.ZodString>;
+    /** Additional metadata */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    timestamp: string;
+    durationMs: number;
+    success: boolean;
+    providerId: string;
+    operation: string;
+    metadata?: Record<string, unknown> | undefined;
+    errorCode?: string | undefined;
+    outputTokens?: number | undefined;
+    inputTokens?: number | undefined;
+    estimatedCost?: number | undefined;
+}, {
+    timestamp: string;
+    durationMs: number;
+    success: boolean;
+    providerId: string;
+    operation: string;
+    metadata?: Record<string, unknown> | undefined;
+    errorCode?: string | undefined;
+    outputTokens?: number | undefined;
+    inputTokens?: number | undefined;
+    estimatedCost?: number | undefined;
+}>;
+export type RequestMetric = z.infer<typeof RequestMetricSchema>;
+export declare const ErrorMetricSchema: z.ZodObject<{
+    /** Timestamp */
+    timestamp: z.ZodString;
+    /** Error code */
+    code: z.ZodString;
+    /** Error message */
+    message: z.ZodString;
+    /** Provider ID if applicable */
+    providerId: z.ZodOptional<z.ZodString>;
+    /** Operation that failed */
+    operation: z.ZodOptional<z.ZodString>;
+    /** Whether error was recoverable */
+    recoverable: z.ZodDefault<z.ZodBoolean>;
+    /** Stack trace (truncated) */
+    stack: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    timestamp: string;
+    recoverable: boolean;
+    stack?: string | undefined;
+    providerId?: string | undefined;
+    operation?: string | undefined;
+}, {
+    code: string;
+    message: string;
+    timestamp: string;
+    stack?: string | undefined;
+    providerId?: string | undefined;
+    operation?: string | undefined;
+    recoverable?: boolean | undefined;
+}>;
+export type ErrorMetric = z.infer<typeof ErrorMetricSchema>;
+export declare const LatencyStatsSchema: z.ZodObject<{
+    /** Minimum latency in ms */
+    min: z.ZodNumber;
+    /** Maximum latency in ms */
+    max: z.ZodNumber;
+    /** Mean latency in ms */
+    mean: z.ZodNumber;
+    /** Median (p50) latency in ms */
+    p50: z.ZodNumber;
+    /** 95th percentile latency in ms */
+    p95: z.ZodNumber;
+    /** 99th percentile latency in ms */
+    p99: z.ZodNumber;
+    /** Sample count */
+    count: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    count: number;
+    min: number;
+    max: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    mean: number;
+}, {
+    count: number;
+    min: number;
+    max: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    mean: number;
+}>;
+export type LatencyStats = z.infer<typeof LatencyStatsSchema>;
+export declare const MetricsSnapshotSchema: z.ZodObject<{
+    /** Time range for this snapshot */
+    timeRange: z.ZodObject<{
+        /** Start time (ISO string or relative like '-1h', '-30m', '-1d') */
+        start: z.ZodString;
+        /** End time (ISO string or 'now') */
+        end: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        start: string;
+        end: string;
+    }, {
+        start: string;
+        end?: string | undefined;
+    }>;
+    /** Request counts */
+    requests: z.ZodObject<{
+        total: z.ZodNumber;
+        success: z.ZodNumber;
+        failure: z.ZodNumber;
+        successRate: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        success: number;
+        total: number;
+        failure: number;
+        successRate: number;
+    }, {
+        success: number;
+        total: number;
+        failure: number;
+        successRate: number;
+    }>;
+    /** Latency statistics */
+    latency: z.ZodObject<{
+        /** Minimum latency in ms */
+        min: z.ZodNumber;
+        /** Maximum latency in ms */
+        max: z.ZodNumber;
+        /** Mean latency in ms */
+        mean: z.ZodNumber;
+        /** Median (p50) latency in ms */
+        p50: z.ZodNumber;
+        /** 95th percentile latency in ms */
+        p95: z.ZodNumber;
+        /** 99th percentile latency in ms */
+        p99: z.ZodNumber;
+        /** Sample count */
+        count: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        count: number;
+        min: number;
+        max: number;
+        p50: number;
+        p95: number;
+        p99: number;
+        mean: number;
+    }, {
+        count: number;
+        min: number;
+        max: number;
+        p50: number;
+        p95: number;
+        p99: number;
+        mean: number;
+    }>;
+    /** Token usage */
+    tokens: z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        total: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        input: number;
+        total: number;
+        output: number;
+    }, {
+        input: number;
+        total: number;
+        output: number;
+    }>;
+    /** Cost statistics */
+    cost: z.ZodObject<{
+        estimated: z.ZodNumber;
+        perRequest: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        estimated: number;
+        perRequest: number;
+    }, {
+        estimated: number;
+        perRequest: number;
+    }>;
+    /** Error breakdown by code */
+    errors: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    /** Per-provider breakdown */
+    byProvider: z.ZodRecord<z.ZodString, z.ZodObject<{
+        requests: z.ZodNumber;
+        failures: z.ZodNumber;
+        latencyP50: z.ZodNumber;
+        tokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        tokens: number;
+        requests: number;
+        failures: number;
+        latencyP50: number;
+    }, {
+        tokens: number;
+        requests: number;
+        failures: number;
+        latencyP50: number;
+    }>>;
+    /** Generated at timestamp */
+    generatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    errors: Record<string, number>;
+    generatedAt: string;
+    tokens: {
+        input: number;
+        total: number;
+        output: number;
+    };
+    requests: {
+        success: number;
+        total: number;
+        failure: number;
+        successRate: number;
+    };
+    timeRange: {
+        start: string;
+        end: string;
+    };
+    cost: {
+        estimated: number;
+        perRequest: number;
+    };
+    latency: {
+        count: number;
+        min: number;
+        max: number;
+        p50: number;
+        p95: number;
+        p99: number;
+        mean: number;
+    };
+    byProvider: Record<string, {
+        tokens: number;
+        requests: number;
+        failures: number;
+        latencyP50: number;
+    }>;
+}, {
+    errors: Record<string, number>;
+    generatedAt: string;
+    tokens: {
+        input: number;
+        total: number;
+        output: number;
+    };
+    requests: {
+        success: number;
+        total: number;
+        failure: number;
+        successRate: number;
+    };
+    timeRange: {
+        start: string;
+        end?: string | undefined;
+    };
+    cost: {
+        estimated: number;
+        perRequest: number;
+    };
+    latency: {
+        count: number;
+        min: number;
+        max: number;
+        p50: number;
+        p95: number;
+        p99: number;
+        mean: number;
+    };
+    byProvider: Record<string, {
+        tokens: number;
+        requests: number;
+        failures: number;
+        latencyP50: number;
+    }>;
+}>;
+export type MetricsSnapshot = z.infer<typeof MetricsSnapshotSchema>;
+export declare function validateRequestMetric(data: unknown): RequestMetric;
+export declare function validateErrorMetric(data: unknown): ErrorMetric;
+export declare function validateMetricsSnapshot(data: unknown): MetricsSnapshot;
+export declare function createEmptyMetricsSnapshot(timeRange?: MetricsTimeRange): MetricsSnapshot;
+export declare function createRequestMetric(providerId: string, operation: string, success: boolean, durationMs: number): RequestMetric;
+export declare function createErrorMetric(code: string, message: string, options?: Partial<ErrorMetric>): ErrorMetric;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/resilience/v1/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/resilience/v1/metrics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,sBAAsB;IACjC,oEAAoE;;IAGpE,qCAAqC;;;;;;;;EAErC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAMtE,eAAO,MAAM,mBAAmB;IAC9B,gBAAgB;;IAGhB,kBAAkB;;IAGlB,qBAAqB;;IAGrB,gCAAgC;;IAGhC,qBAAqB;;IAGrB,wBAAwB;;IAGxB,yBAAyB;;IAGzB,qBAAqB;;IAGrB,2BAA2B;;IAG3B,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;EAE1B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,eAAO,MAAM,iBAAiB;IAC5B,gBAAgB;;IAGhB,iBAAiB;;IAGjB,oBAAoB;;IAGpB,gCAAgC;;IAGhC,4BAA4B;;IAG5B,oCAAoC;;IAGpC,8BAA8B;;;;;;;;;;;;;;;;;;EAE9B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,kBAAkB;IAC7B,4BAA4B;;IAG5B,4BAA4B;;IAG5B,yBAAyB;;IAGzB,iCAAiC;;IAGjC,oCAAoC;;IAGpC,oCAAoC;;IAGpC,mBAAmB;;;;;;;;;;;;;;;;;;EAEnB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAM9D,eAAO,MAAM,qBAAqB;IAChC,mCAAmC;;QA9GnC,oEAAoE;;QAGpE,qCAAqC;;;;;;;;;IA8GrC,qBAAqB;;;;;;;;;;;;;;;;;IAQrB,yBAAyB;;QAxCzB,4BAA4B;;QAG5B,4BAA4B;;QAG5B,yBAAyB;;QAGzB,iCAAiC;;QAGjC,oCAAoC;;QAGpC,oCAAoC;;QAGpC,mBAAmB;;;;;;;;;;;;;;;;;;;IAyBnB,kBAAkB;;;;;;;;;;;;;;IAOlB,sBAAsB;;;;;;;;;;;IAMtB,8BAA8B;;IAG9B,6BAA6B;;;;;;;;;;;;;;;;;IAU7B,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE7B,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,CAElE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CAE9D;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAEtE;AAMD,wBAAgB,0BAA0B,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,eAAe,CAgCxF;AAED,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,GACjB,aAAa,CAQf;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC7B,WAAW,CAQb"}

package/dist/resilience/v1/metrics.js

@@ -0,0 +1,183 @@
+/**
+ * Metrics Contract
+ *
+ * Basic observability metrics for monitoring system health.
+ */
+import { z } from 'zod';
+// ============================================================================
+// Metrics Time Range (supports relative times like '-1h')
+// ============================================================================
+export const MetricsTimeRangeSchema = z.object({
+    /** Start time (ISO string or relative like '-1h', '-30m', '-1d') */
+    start: z.string(),
+    /** End time (ISO string or 'now') */
+    end: z.string().default('now'),
+});
+// ============================================================================
+// Request Metric
+// ============================================================================
+export const RequestMetricSchema = z.object({
+    /** Timestamp */
+    timestamp: z.string().datetime(),
+    /** Provider ID */
+    providerId: z.string(),
+    /** Operation type */
+    operation: z.string(),
+    /** Whether request succeeded */
+    success: z.boolean(),
+    /** Duration in ms */
+    durationMs: z.number().int().min(0),
+    /** Input tokens used */
+    inputTokens: z.number().int().min(0).optional(),
+    /** Output tokens used */
+    outputTokens: z.number().int().min(0).optional(),
+    /** Estimated cost */
+    estimatedCost: z.number().min(0).optional(),
+    /** Error code if failed */
+    errorCode: z.string().optional(),
+    /** Additional metadata */
+    metadata: z.record(z.unknown()).optional(),
+});
+// ============================================================================
+// Error Metric
+// ============================================================================
+export const ErrorMetricSchema = z.object({
+    /** Timestamp */
+    timestamp: z.string().datetime(),
+    /** Error code */
+    code: z.string(),
+    /** Error message */
+    message: z.string(),
+    /** Provider ID if applicable */
+    providerId: z.string().optional(),
+    /** Operation that failed */
+    operation: z.string().optional(),
+    /** Whether error was recoverable */
+    recoverable: z.boolean().default(false),
+    /** Stack trace (truncated) */
+    stack: z.string().max(2000).optional(),
+});
+// ============================================================================
+// Latency Stats
+// ============================================================================
+export const LatencyStatsSchema = z.object({
+    /** Minimum latency in ms */
+    min: z.number().int().min(0),
+    /** Maximum latency in ms */
+    max: z.number().int().min(0),
+    /** Mean latency in ms */
+    mean: z.number().min(0),
+    /** Median (p50) latency in ms */
+    p50: z.number().int().min(0),
+    /** 95th percentile latency in ms */
+    p95: z.number().int().min(0),
+    /** 99th percentile latency in ms */
+    p99: z.number().int().min(0),
+    /** Sample count */
+    count: z.number().int().min(0),
+});
+// ============================================================================
+// Metrics Snapshot
+// ============================================================================
+export const MetricsSnapshotSchema = z.object({
+    /** Time range for this snapshot */
+    timeRange: MetricsTimeRangeSchema,
+    /** Request counts */
+    requests: z.object({
+        total: z.number().int().min(0),
+        success: z.number().int().min(0),
+        failure: z.number().int().min(0),
+        successRate: z.number().min(0).max(1),
+    }),
+    /** Latency statistics */
+    latency: LatencyStatsSchema,
+    /** Token usage */
+    tokens: z.object({
+        input: z.number().int().min(0),
+        output: z.number().int().min(0),
+        total: z.number().int().min(0),
+    }),
+    /** Cost statistics */
+    cost: z.object({
+        estimated: z.number().min(0),
+        perRequest: z.number().min(0),
+    }),
+    /** Error breakdown by code */
+    errors: z.record(z.number().int().min(0)),
+    /** Per-provider breakdown */
+    byProvider: z.record(z.object({
+        requests: z.number().int().min(0),
+        failures: z.number().int().min(0),
+        latencyP50: z.number().int().min(0),
+        tokens: z.number().int().min(0),
+    })),
+    /** Generated at timestamp */
+    generatedAt: z.string().datetime(),
+});
+// ============================================================================
+// Validation Functions
+// ============================================================================
+export function validateRequestMetric(data) {
+    return RequestMetricSchema.parse(data);
+}
+export function validateErrorMetric(data) {
+    return ErrorMetricSchema.parse(data);
+}
+export function validateMetricsSnapshot(data) {
+    return MetricsSnapshotSchema.parse(data);
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+export function createEmptyMetricsSnapshot(timeRange) {
+    const now = new Date().toISOString();
+    return {
+        timeRange: timeRange ?? { start: now, end: 'now' },
+        requests: {
+            total: 0,
+            success: 0,
+            failure: 0,
+            successRate: 1,
+        },
+        latency: {
+            min: 0,
+            max: 0,
+            mean: 0,
+            p50: 0,
+            p95: 0,
+            p99: 0,
+            count: 0,
+        },
+        tokens: {
+            input: 0,
+            output: 0,
+            total: 0,
+        },
+        cost: {
+            estimated: 0,
+            perRequest: 0,
+        },
+        errors: {},
+        byProvider: {},
+        generatedAt: now,
+    };
+}
+export function createRequestMetric(providerId, operation, success, durationMs) {
+    return {
+        timestamp: new Date().toISOString(),
+        providerId,
+        operation,
+        success,
+        durationMs,
+    };
+}
+export function createErrorMetric(code, message, options) {
+    return {
+        timestamp: new Date().toISOString(),
+        code,
+        message,
+        recoverable: false,
+        ...options,
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/resilience/v1/metrics.js.map

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