@defai.digital/contracts 13.0.3

package/dist/cross-cutting/v1/saga.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Saga Pattern Contract V1
+ *
+ * Provides contracts for managing distributed transactions with compensation.
+ * Enables rollback of multi-step operations on failure.
+ *
+ * Invariants:
+ * - INV-SG-001: Compensations run in reverse order on failure
+ * - INV-SG-002: Required compensations must succeed
+ * - INV-SG-003: Saga state transitions are valid
+ */
+import { z } from 'zod';
+/**
+ * Compensation action type
+ */
+export declare const CompensationActionTypeSchema: z.ZodEnum<["rollback", "notify", "log", "custom"]>;
+export type CompensationActionType = z.infer<typeof CompensationActionTypeSchema>;
+/**
+ * Compensation action definition
+ */
+export declare const CompensationActionSchema: z.ZodObject<{
+    /** Step this compensation is for */
+    stepId: z.ZodString;
+    /** Type of compensation action */
+    action: z.ZodEnum<["rollback", "notify", "log", "custom"]>;
+    /** Handler function name or agent ID */
+    handler: z.ZodString;
+    /** Timeout for compensation in ms */
+    timeout: z.ZodDefault<z.ZodNumber>;
+    /** Whether this compensation must succeed (INV-SG-002) */
+    required: z.ZodDefault<z.ZodBoolean>;
+    /** Retry configuration for compensation */
+    retryCount: z.ZodDefault<z.ZodNumber>;
+    /** Additional configuration */
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    stepId: string;
+    required: boolean;
+    retryCount: number;
+    action: "custom" | "rollback" | "notify" | "log";
+    handler: string;
+    config?: Record<string, unknown> | undefined;
+}, {
+    stepId: string;
+    action: "custom" | "rollback" | "notify" | "log";
+    handler: string;
+    timeout?: number | undefined;
+    config?: Record<string, unknown> | undefined;
+    required?: boolean | undefined;
+    retryCount?: number | undefined;
+}>;
+export type CompensationAction = z.infer<typeof CompensationActionSchema>;
+/**
+ * Saga failure handling strategy
+ */
+export declare const SagaFailureStrategySchema: z.ZodEnum<["compensate", "pause", "continue"]>;
+export type SagaFailureStrategy = z.infer<typeof SagaFailureStrategySchema>;
+/**
+ * Compensation execution order
+ */
+export declare const CompensationOrderSchema: z.ZodEnum<["reverse", "parallel"]>;
+export type CompensationOrder = z.infer<typeof CompensationOrderSchema>;
+/**
+ * Saga definition
+ */
+export declare const SagaDefinitionSchema: z.ZodObject<{
+    /** Unique saga identifier */
+    sagaId: z.ZodString;
+    /** Associated workflow ID */
+    workflowId: z.ZodOptional<z.ZodString>;
+    /** Compensation actions for each step */
+    compensations: z.ZodArray<z.ZodObject<{
+        /** Step this compensation is for */
+        stepId: z.ZodString;
+        /** Type of compensation action */
+        action: z.ZodEnum<["rollback", "notify", "log", "custom"]>;
+        /** Handler function name or agent ID */
+        handler: z.ZodString;
+        /** Timeout for compensation in ms */
+        timeout: z.ZodDefault<z.ZodNumber>;
+        /** Whether this compensation must succeed (INV-SG-002) */
+        required: z.ZodDefault<z.ZodBoolean>;
+        /** Retry configuration for compensation */
+        retryCount: z.ZodDefault<z.ZodNumber>;
+        /** Additional configuration */
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        timeout: number;
+        stepId: string;
+        required: boolean;
+        retryCount: number;
+        action: "custom" | "rollback" | "notify" | "log";
+        handler: string;
+        config?: Record<string, unknown> | undefined;
+    }, {
+        stepId: string;
+        action: "custom" | "rollback" | "notify" | "log";
+        handler: string;
+        timeout?: number | undefined;
+        config?: Record<string, unknown> | undefined;
+        required?: boolean | undefined;
+        retryCount?: number | undefined;
+    }>, "many">;
+    /** What to do on step failure */
+    onFailure: z.ZodDefault<z.ZodEnum<["compensate", "pause", "continue"]>>;
+    /** Order to run compensations */
+    compensationOrder: z.ZodDefault<z.ZodEnum<["reverse", "parallel"]>>;
+    /** Saga description */
+    description: z.ZodOptional<z.ZodString>;
+    /** Version for definition tracking */
+    version: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    onFailure: "continue" | "compensate" | "pause";
+    sagaId: string;
+    compensations: {
+        timeout: number;
+        stepId: string;
+        required: boolean;
+        retryCount: number;
+        action: "custom" | "rollback" | "notify" | "log";
+        handler: string;
+        config?: Record<string, unknown> | undefined;
+    }[];
+    compensationOrder: "reverse" | "parallel";
+    workflowId?: string | undefined;
+    version?: string | undefined;
+    description?: string | undefined;
+}, {
+    sagaId: string;
+    compensations: {
+        stepId: string;
+        action: "custom" | "rollback" | "notify" | "log";
+        handler: string;
+        timeout?: number | undefined;
+        config?: Record<string, unknown> | undefined;
+        required?: boolean | undefined;
+        retryCount?: number | undefined;
+    }[];
+    workflowId?: string | undefined;
+    version?: string | undefined;
+    description?: string | undefined;
+    onFailure?: "continue" | "compensate" | "pause" | undefined;
+    compensationOrder?: "reverse" | "parallel" | undefined;
+}>;
+export type SagaDefinition = z.infer<typeof SagaDefinitionSchema>;
+/**
+ * Saga execution status
+ */
+export declare const SagaStatusSchema: z.ZodEnum<["running", "completed", "compensating", "compensated", "failed", "paused"]>;
+export type SagaStatus = z.infer<typeof SagaStatusSchema>;
+/**
+ * Compensation error record
+ */
+export declare const CompensationErrorSchema: z.ZodObject<{
+    stepId: z.ZodString;
+    error: z.ZodString;
+    timestamp: z.ZodString;
+    retryCount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    stepId: string;
+    timestamp: string;
+    error: string;
+    retryCount: number;
+}, {
+    stepId: string;
+    timestamp: string;
+    error: string;
+    retryCount: number;
+}>;
+export type CompensationError = z.infer<typeof CompensationErrorSchema>;
+/**
+ * Saga execution state
+ */
+export declare const SagaStateSchema: z.ZodObject<{
+    /** Saga definition ID */
+    sagaId: z.ZodString;
+    /** Unique execution ID */
+    executionId: z.ZodString;
+    /** Current execution status */
+    status: z.ZodEnum<["running", "completed", "compensating", "compensated", "failed", "paused"]>;
+    /** Steps that completed successfully */
+    completedSteps: z.ZodArray<z.ZodString, "many">;
+    /** Step that failed (if applicable) */
+    failedStep: z.ZodOptional<z.ZodString>;
+    /** Failure reason */
+    failureReason: z.ZodOptional<z.ZodString>;
+    /** Steps that have been compensated */
+    compensatedSteps: z.ZodArray<z.ZodString, "many">;
+    /** Errors from compensation attempts */
+    compensationErrors: z.ZodArray<z.ZodObject<{
+        stepId: z.ZodString;
+        error: z.ZodString;
+        timestamp: z.ZodString;
+        retryCount: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        stepId: string;
+        timestamp: string;
+        error: string;
+        retryCount: number;
+    }, {
+        stepId: string;
+        timestamp: string;
+        error: string;
+        retryCount: number;
+    }>, "many">;
+    /** Execution start time */
+    startedAt: z.ZodString;
+    /** Execution end time */
+    completedAt: z.ZodOptional<z.ZodString>;
+    /** Additional context */
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Correlation ID for tracing */
+    correlationId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "completed" | "failed" | "running" | "paused" | "compensating" | "compensated";
+    executionId: string;
+    startedAt: string;
+    sagaId: string;
+    completedSteps: string[];
+    compensatedSteps: string[];
+    compensationErrors: {
+        stepId: string;
+        timestamp: string;
+        error: string;
+        retryCount: number;
+    }[];
+    context?: Record<string, unknown> | undefined;
+    completedAt?: string | undefined;
+    correlationId?: string | undefined;
+    failedStep?: string | undefined;
+    failureReason?: string | undefined;
+}, {
+    status: "completed" | "failed" | "running" | "paused" | "compensating" | "compensated";
+    executionId: string;
+    startedAt: string;
+    sagaId: string;
+    completedSteps: string[];
+    compensatedSteps: string[];
+    compensationErrors: {
+        stepId: string;
+        timestamp: string;
+        error: string;
+        retryCount: number;
+    }[];
+    context?: Record<string, unknown> | undefined;
+    completedAt?: string | undefined;
+    correlationId?: string | undefined;
+    failedStep?: string | undefined;
+    failureReason?: string | undefined;
+}>;
+export type SagaState = z.infer<typeof SagaStateSchema>;
+/**
+ * Saga execution result
+ */
+export declare const SagaResultSchema: z.ZodObject<{
+    /** Whether saga completed successfully */
+    success: z.ZodBoolean;
+    /** Execution ID */
+    executionId: z.ZodString;
+    /** Step results (if successful) */
+    results: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    /** Error message (if failed) */
+    error: z.ZodOptional<z.ZodString>;
+    /** Whether compensations ran */
+    compensated: z.ZodOptional<z.ZodBoolean>;
+    /** Duration in ms */
+    durationMs: z.ZodNumber;
+    /** Final state */
+    finalStatus: z.ZodEnum<["running", "completed", "compensating", "compensated", "failed", "paused"]>;
+}, "strip", z.ZodTypeAny, {
+    durationMs: number;
+    executionId: string;
+    success: boolean;
+    finalStatus: "completed" | "failed" | "running" | "paused" | "compensating" | "compensated";
+    error?: string | undefined;
+    results?: unknown[] | undefined;
+    compensated?: boolean | undefined;
+}, {
+    durationMs: number;
+    executionId: string;
+    success: boolean;
+    finalStatus: "completed" | "failed" | "running" | "paused" | "compensating" | "compensated";
+    error?: string | undefined;
+    results?: unknown[] | undefined;
+    compensated?: boolean | undefined;
+}>;
+export type SagaResult = z.infer<typeof SagaResultSchema>;
+/**
+ * Saga step definition for execution
+ */
+export declare const SagaStepSchema: z.ZodObject<{
+    /** Step identifier */
+    stepId: z.ZodString;
+    /** Step name for display */
+    name: z.ZodOptional<z.ZodString>;
+    /** Step timeout in ms */
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    stepId: string;
+    timeout?: number | undefined;
+    name?: string | undefined;
+}, {
+    stepId: string;
+    timeout?: number | undefined;
+    name?: string | undefined;
+}>;
+export type SagaStep = z.infer<typeof SagaStepSchema>;
+/**
+ * Saga context for execution
+ */
+export declare const SagaContextSchema: z.ZodObject<{
+    /** Correlation ID for tracing */
+    correlationId: z.ZodString;
+    /** Additional context data */
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    correlationId: string;
+    data?: Record<string, unknown> | undefined;
+}, {
+    correlationId: string;
+    data?: Record<string, unknown> | undefined;
+}>;
+export type SagaContext = z.infer<typeof SagaContextSchema>;
+/**
+ * Saga error codes
+ */
+export declare const SagaErrorCodes: {
+    readonly SAGA_NOT_FOUND: "SAGA_NOT_FOUND";
+    readonly SAGA_ALREADY_RUNNING: "SAGA_ALREADY_RUNNING";
+    readonly STEP_FAILED: "SAGA_STEP_FAILED";
+    readonly COMPENSATION_FAILED: "SAGA_COMPENSATION_FAILED";
+    readonly REQUIRED_COMPENSATION_FAILED: "SAGA_REQUIRED_COMPENSATION_FAILED";
+    readonly INVALID_STATE_TRANSITION: "SAGA_INVALID_STATE_TRANSITION";
+    readonly TIMEOUT: "SAGA_TIMEOUT";
+};
+export type SagaErrorCode = (typeof SagaErrorCodes)[keyof typeof SagaErrorCodes];
+/**
+ * Valid saga state transitions
+ */
+export declare const SAGA_STATE_TRANSITIONS: Record<SagaStatus, SagaStatus[]>;
+/**
+ * Validates saga definition
+ */
+export declare function validateSagaDefinition(data: unknown): SagaDefinition;
+/**
+ * Validates saga state
+ */
+export declare function validateSagaState(data: unknown): SagaState;
+/**
+ * Checks if state transition is valid
+ */
+export declare function isValidSagaTransition(from: SagaStatus, to: SagaStatus): boolean;
+/**
+ * Creates initial saga state
+ */
+export declare function createInitialSagaState(sagaId: string, correlationId?: string): SagaState;
+//# sourceMappingURL=saga.d.ts.map

package/dist/cross-cutting/v1/saga.d.ts.map

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

package/dist/cross-cutting/v1/saga.js

@@ -0,0 +1,219 @@
+/**
+ * Saga Pattern Contract V1
+ *
+ * Provides contracts for managing distributed transactions with compensation.
+ * Enables rollback of multi-step operations on failure.
+ *
+ * Invariants:
+ * - INV-SG-001: Compensations run in reverse order on failure
+ * - INV-SG-002: Required compensations must succeed
+ * - INV-SG-003: Saga state transitions are valid
+ */
+import { z } from 'zod';
+/**
+ * Compensation action type
+ */
+export const CompensationActionTypeSchema = z.enum([
+    'rollback', // Undo the step's changes
+    'notify', // Send notification about failure
+    'log', // Log the failure for investigation
+    'custom', // Custom compensation handler
+]);
+/**
+ * Compensation action definition
+ */
+export const CompensationActionSchema = z.object({
+    /** Step this compensation is for */
+    stepId: z.string(),
+    /** Type of compensation action */
+    action: CompensationActionTypeSchema,
+    /** Handler function name or agent ID */
+    handler: z.string(),
+    /** Timeout for compensation in ms */
+    timeout: z.number().int().min(1000).max(300000).default(30000),
+    /** Whether this compensation must succeed (INV-SG-002) */
+    required: z.boolean().default(true),
+    /** Retry configuration for compensation */
+    retryCount: z.number().int().min(0).max(3).default(1),
+    /** Additional configuration */
+    config: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Saga failure handling strategy
+ */
+export const SagaFailureStrategySchema = z.enum([
+    'compensate', // Run compensations in reverse order
+    'pause', // Pause for manual intervention
+    'continue', // Continue without compensation (log only)
+]);
+/**
+ * Compensation execution order
+ */
+export const CompensationOrderSchema = z.enum([
+    'reverse', // Execute in reverse step order (INV-SG-001)
+    'parallel', // Execute all compensations in parallel
+]);
+/**
+ * Saga definition
+ */
+export const SagaDefinitionSchema = z.object({
+    /** Unique saga identifier */
+    sagaId: z.string(),
+    /** Associated workflow ID */
+    workflowId: z.string().optional(),
+    /** Compensation actions for each step */
+    compensations: z.array(CompensationActionSchema),
+    /** What to do on step failure */
+    onFailure: SagaFailureStrategySchema.default('compensate'),
+    /** Order to run compensations */
+    compensationOrder: CompensationOrderSchema.default('reverse'),
+    /** Saga description */
+    description: z.string().optional(),
+    /** Version for definition tracking */
+    version: z.string().optional(),
+});
+/**
+ * Saga execution status
+ */
+export const SagaStatusSchema = z.enum([
+    'running', // Saga is executing steps
+    'completed', // All steps completed successfully
+    'compensating', // Running compensations
+    'compensated', // Compensations completed
+    'failed', // Saga or compensation failed
+    'paused', // Paused for intervention
+]);
+/**
+ * Compensation error record
+ */
+export const CompensationErrorSchema = z.object({
+    stepId: z.string(),
+    error: z.string(),
+    timestamp: z.string().datetime(),
+    retryCount: z.number().int().min(0),
+});
+/**
+ * Saga execution state
+ */
+export const SagaStateSchema = z.object({
+    /** Saga definition ID */
+    sagaId: z.string(),
+    /** Unique execution ID */
+    executionId: z.string().uuid(),
+    /** Current execution status */
+    status: SagaStatusSchema,
+    /** Steps that completed successfully */
+    completedSteps: z.array(z.string()),
+    /** Step that failed (if applicable) */
+    failedStep: z.string().optional(),
+    /** Failure reason */
+    failureReason: z.string().optional(),
+    /** Steps that have been compensated */
+    compensatedSteps: z.array(z.string()),
+    /** Errors from compensation attempts */
+    compensationErrors: z.array(CompensationErrorSchema),
+    /** Execution start time */
+    startedAt: z.string().datetime(),
+    /** Execution end time */
+    completedAt: z.string().datetime().optional(),
+    /** Additional context */
+    context: z.record(z.string(), z.unknown()).optional(),
+    /** Correlation ID for tracing */
+    correlationId: z.string().optional(),
+});
+/**
+ * Saga execution result
+ */
+export const SagaResultSchema = z.object({
+    /** Whether saga completed successfully */
+    success: z.boolean(),
+    /** Execution ID */
+    executionId: z.string().uuid(),
+    /** Step results (if successful) */
+    results: z.array(z.unknown()).optional(),
+    /** Error message (if failed) */
+    error: z.string().optional(),
+    /** Whether compensations ran */
+    compensated: z.boolean().optional(),
+    /** Duration in ms */
+    durationMs: z.number().int().min(0),
+    /** Final state */
+    finalStatus: SagaStatusSchema,
+});
+/**
+ * Saga step definition for execution
+ */
+export const SagaStepSchema = z.object({
+    /** Step identifier */
+    stepId: z.string(),
+    /** Step name for display */
+    name: z.string().optional(),
+    /** Step timeout in ms */
+    timeout: z.number().int().min(1000).max(600000).optional(),
+});
+/**
+ * Saga context for execution
+ */
+export const SagaContextSchema = z.object({
+    /** Correlation ID for tracing */
+    correlationId: z.string(),
+    /** Additional context data */
+    data: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Saga error codes
+ */
+export const SagaErrorCodes = {
+    SAGA_NOT_FOUND: 'SAGA_NOT_FOUND',
+    SAGA_ALREADY_RUNNING: 'SAGA_ALREADY_RUNNING',
+    STEP_FAILED: 'SAGA_STEP_FAILED',
+    COMPENSATION_FAILED: 'SAGA_COMPENSATION_FAILED',
+    REQUIRED_COMPENSATION_FAILED: 'SAGA_REQUIRED_COMPENSATION_FAILED',
+    INVALID_STATE_TRANSITION: 'SAGA_INVALID_STATE_TRANSITION',
+    TIMEOUT: 'SAGA_TIMEOUT',
+};
+/**
+ * Valid saga state transitions
+ */
+export const SAGA_STATE_TRANSITIONS = {
+    running: ['completed', 'compensating', 'paused', 'failed'],
+    completed: [],
+    compensating: ['compensated', 'failed', 'paused'],
+    compensated: [],
+    failed: [],
+    paused: ['running', 'compensating', 'failed'],
+};
+/**
+ * Validates saga definition
+ */
+export function validateSagaDefinition(data) {
+    return SagaDefinitionSchema.parse(data);
+}
+/**
+ * Validates saga state
+ */
+export function validateSagaState(data) {
+    return SagaStateSchema.parse(data);
+}
+/**
+ * Checks if state transition is valid
+ */
+export function isValidSagaTransition(from, to) {
+    return SAGA_STATE_TRANSITIONS[from].includes(to);
+}
+/**
+ * Creates initial saga state
+ */
+export function createInitialSagaState(sagaId, correlationId) {
+    return {
+        sagaId,
+        executionId: crypto.randomUUID(),
+        status: 'running',
+        completedSteps: [],
+        compensatedSteps: [],
+        compensationErrors: [],
+        startedAt: new Date().toISOString(),
+        correlationId,
+    };
+}
+//# sourceMappingURL=saga.js.map

package/dist/cross-cutting/v1/saga.js.map

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

package/dist/design/v1/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Design Contracts v1
+ */
+export { DesignTypeSchema, DesignFormatSchema, DesignStatusSchema, DesignArtifactSchema, HttpMethodSchema, ApiEndpointSchema, ApiDesignRequestSchema, ApiDesignResultSchema, ComponentTypeSchema, ComponentDesignRequestSchema, ComponentDesignResultSchema, SchemaFieldTypeSchema, SchemaFieldSchema, SchemaDesignRequestSchema, SchemaDesignResultSchema, ArchitecturePatternSchema, ArchitectureComponentSchema, ArchitectureDesignRequestSchema, ArchitectureDesignResultSchema, DesignErrorCode, validateApiDesignRequest, validateComponentDesignRequest, validateSchemaDesignRequest, validateArchitectureDesignRequest, safeValidateApiDesignRequest, type DesignType, type DesignFormat, type DesignStatus, type DesignArtifact, type HttpMethod, type ApiEndpoint, type ApiDesignRequest, type ApiDesignResult, type ComponentType, type ComponentDesignRequest, type ComponentDesignResult, type SchemaFieldType, type SchemaField, type SchemaDesignRequest, type SchemaDesignResult, type ArchitecturePattern, type ArchitectureComponent, type ArchitectureDesignRequest, type ArchitectureDesignResult, } from './schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/design/v1/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/design/v1/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,EACjB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,+BAA+B,EAC/B,8BAA8B,EAC9B,eAAe,EACf,wBAAwB,EACxB,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,EACjC,4BAA4B,EAC5B,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,aAAa,CAAC"}

package/dist/design/v1/index.js

@@ -0,0 +1,5 @@
+/**
+ * Design Contracts v1
+ */
+export { DesignTypeSchema, DesignFormatSchema, DesignStatusSchema, DesignArtifactSchema, HttpMethodSchema, ApiEndpointSchema, ApiDesignRequestSchema, ApiDesignResultSchema, ComponentTypeSchema, ComponentDesignRequestSchema, ComponentDesignResultSchema, SchemaFieldTypeSchema, SchemaFieldSchema, SchemaDesignRequestSchema, SchemaDesignResultSchema, ArchitecturePatternSchema, ArchitectureComponentSchema, ArchitectureDesignRequestSchema, ArchitectureDesignResultSchema, DesignErrorCode, validateApiDesignRequest, validateComponentDesignRequest, validateSchemaDesignRequest, validateArchitectureDesignRequest, safeValidateApiDesignRequest, } from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/design/v1/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/design/v1/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,EACjB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,+BAA+B,EAC/B,8BAA8B,EAC9B,eAAe,EACf,wBAAwB,EACxB,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,EACjC,4BAA4B,GAoB7B,MAAM,aAAa,CAAC"}