@neuraloom/contracts 0.0.0-stage → 0.1.22

package/dist/schemas/workflow-progression.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Workflow progression (per-step status) — Zod + inferred types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowStepAiOutputResponseSchema = exports.WorkflowStepAiOutputArtifactRowSchema = exports.WorkflowStepAiOutputRunRowSchema = exports.WorkflowResetStepResponseSchema = exports.WorkflowResetStepRequestSchema = exports.WorkflowStepStatsResponseSchema = exports.WorkflowStepStatsStepIdSchema = exports.WorkflowStatSchema = exports.WorkflowStateApiSuccessResponseSchema = exports.WorkflowStateResponseSchema = exports.WorkflowStateCommandCenterSchema = exports.WorkflowStepStateSchema = exports.WorkflowStepBlockBucketsSchema = exports.WorkflowGateStateSchema = exports.PipelineStageStateSchema = exports.WorkflowProgressionDataSchema = exports.WorkflowGateSummarySchema = exports.WorkflowStepProgressionEntrySchema = exports.WorkflowPhaseGuardianLockSchema = exports.WorkflowStepBlockedBySchema = exports.WorkflowStepStatusSchema = exports.WORKFLOW_STEP_IDS_UNAVAILABLE_ROUTE = exports.WORKFLOW_STEP_IDS_COMING_SOON = exports.WorkflowNormalizedStepStatusSchema = void 0;
+const zod_1 = require("zod");
+const step_evidence_resolution_schema_1 = require("./workflow/step-evidence-resolution.schema");
+const workflow_execution_mode_schema_1 = require("./ai/workflow-execution-mode.schema");
+const guardian_score_schema_1 = require("./guardian/guardian-score.schema");
+const workflow_evidence_schema_1 = require("./workflow/workflow-evidence.schema");
+/** Canonical per-step status for workflow UI (sidebar, cards, body) — single union. */
+exports.WorkflowNormalizedStepStatusSchema = zod_1.z.enum([
+    "not_started",
+    "running",
+    "completed",
+    "completed_with_errors",
+    "halted",
+    "failed",
+    "blocked",
+    "evidence_conflict",
+    "unavailable",
+    "coming_soon",
+]);
+/** Steps with no shipped page yet — extend when product adds stubs. */
+exports.WORKFLOW_STEP_IDS_COMING_SOON = ["monitor"];
+/** Steps whose route exists but is not wired — extend when a page is a known no-op. */
+exports.WORKFLOW_STEP_IDS_UNAVAILABLE_ROUTE = [];
+exports.WorkflowStepStatusSchema = zod_1.z.enum([
+    "complete",
+    "pending",
+    "blocked",
+    "stale",
+    "generating",
+]);
+exports.WorkflowStepBlockedBySchema = zod_1.z.enum(["plan"]).nullable();
+exports.WorkflowPhaseGuardianLockSchema = zod_1.z.object({
+    navPhaseTitle: zod_1.z.string(),
+    scoreDisplay: guardian_score_schema_1.GuardianScoreSchema,
+    threshold: guardian_score_schema_1.GuardianScoreSchema,
+});
+exports.WorkflowStepProgressionEntrySchema = zod_1.z.object({
+    status: exports.WorkflowStepStatusSchema,
+    count: zod_1.z.number().int().min(0),
+    blockedBy: exports.WorkflowStepBlockedBySchema.optional(),
+    phaseGuardianLock: exports.WorkflowPhaseGuardianLockSchema.optional(),
+    /** ISO timestamp of the latest successful completion for this step, when known. */
+    lastCompletedAt: zod_1.z.string().nullable().optional(),
+    /** Guardian score from the most recent `ai_runs` row for this step (any status), when present. */
+    lastRunGuardianScore: guardian_score_schema_1.GuardianScoreNullableSchema.optional(),
+});
+exports.WorkflowGateSummarySchema = zod_1.z.object({
+    step: zod_1.z.string(),
+    status: zod_1.z.string(),
+    id: zod_1.z.string().optional(),
+});
+exports.WorkflowProgressionDataSchema = zod_1.z.object({
+    steps: zod_1.z.record(zod_1.z.string(), exports.WorkflowStepProgressionEntrySchema),
+    overallGuardianScore: zod_1.z.union([
+        zod_1.z.number().min(0).max(100),
+        zod_1.z.null(),
+    ]),
+    activeGates: zod_1.z.array(exports.WorkflowGateSummarySchema),
+});
+// ---------------------------------------------------------------------------
+// Workflow State API — enriched read-model for the Visual Workflow UI
+// ---------------------------------------------------------------------------
+exports.PipelineStageStateSchema = zod_1.z.object({
+    stageId: zod_1.z.string(),
+    status: zod_1.z.enum(['not_started', 'accepted', 'rejected', 'validating', 'pending']),
+    guardianScore: guardian_score_schema_1.GuardianScoreNullableSchema,
+    artifactId: zod_1.z.string().nullable(),
+    createdAt: zod_1.z.string().nullable(),
+    domainSummary: zod_1.z.string(),
+    /** CI validation depth (e.g. actionlint skipped → partial). */
+    validationLevel: zod_1.z.enum(['full', 'partial']).optional(),
+});
+exports.WorkflowGateStateSchema = zod_1.z.object({
+    gateId: zod_1.z.string(),
+    type: zod_1.z.string(),
+    status: zod_1.z.string(),
+    requiredApprover: zod_1.z.string().nullable(),
+    resolvedAt: zod_1.z.string().nullable(),
+    decision: zod_1.z.string().nullable(),
+});
+/** Three-way UI categorization for workflow step pipeline/gate readiness (#376). */
+exports.WorkflowStepBlockBucketsSchema = zod_1.z.object({
+    /** Preconditions that disable Generate / must clear before continuing */
+    hardBlockers: zod_1.z.array(zod_1.z.string()),
+    /** Quality/upstream cues — Generate remains allowed */
+    warnings: zod_1.z.array(zod_1.z.string()),
+    /** Missing stage outputs — work in flight, not gating Generate */
+    pendingStages: zod_1.z.array(zod_1.z.string()),
+});
+exports.WorkflowStepStateSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    stepId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    phase: zod_1.z.string(),
+    phaseIndex: zod_1.z.number().int(),
+    stepIndex: zod_1.z.number().int(),
+    pageRoute: zod_1.z.string(),
+    status: exports.WorkflowNormalizedStepStatusSchema,
+    complete: zod_1.z.boolean(),
+    completionReasons: zod_1.z.array(zod_1.z.string()),
+    pipeline: zod_1.z
+        .object({
+        stages: zod_1.z.array(exports.PipelineStageStateSchema),
+        pendingStages: zod_1.z.array(zod_1.z.string()),
+        rejectedStages: zod_1.z.array(zod_1.z.string()),
+        guardianMin: guardian_score_schema_1.GuardianScoreNullableSchema,
+    })
+        .nullable(),
+    latestGuardianScore: guardian_score_schema_1.GuardianScoreNullableSchema,
+    latestArtifactId: zod_1.z.string().nullable(),
+    latestAiRunId: zod_1.z.string().nullable(),
+    ...exports.WorkflowStepBlockBucketsSchema.shape,
+    gates: zod_1.z.array(exports.WorkflowGateStateSchema),
+    /** Evidence resolution source for aliased software_app steps (#1062). */
+    evidenceSource: step_evidence_resolution_schema_1.StepEvidenceSourceSchema.optional(),
+    evidenceWarnings: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.WorkflowStateCommandCenterSchema = zod_1.z.object({
+    /** Latest orchestrations.id for this project (same spine id used across AI runs). */
+    activeOrchestrationId: zod_1.z.string().uuid().nullable(),
+    workflowExecutionMode: workflow_execution_mode_schema_1.WorkflowExecutionModeSchema.nullable(),
+});
+exports.WorkflowStateResponseSchema = zod_1.z.object({
+    project: zod_1.z.object({
+        id: zod_1.z.string(),
+        name: zod_1.z.string(),
+        description: zod_1.z.string().nullable(),
+        status: zod_1.z.string().nullable(),
+    }),
+    commandCenter: exports.WorkflowStateCommandCenterSchema,
+    phases: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        number: zod_1.z.number().int(),
+        title: zod_1.z.string(),
+        steps: zod_1.z.array(zod_1.z.string()),
+    })),
+    currentStepId: zod_1.z.string().nullable(),
+    steps: zod_1.z.array(exports.WorkflowStepStateSchema),
+    summary: zod_1.z.object({
+        totalSteps: zod_1.z.number().int(),
+        completedSteps: zod_1.z.number().int(),
+        inProgressSteps: zod_1.z.number().int(),
+        blockedSteps: zod_1.z.number().int(),
+        overallGuardianMin: zod_1.z.union([
+            zod_1.z.number().min(0).max(100),
+            zod_1.z.null(),
+        ]),
+    }),
+    workflowEvidence: workflow_evidence_schema_1.WorkflowEvidenceSummarySchema.optional(),
+});
+/**
+ * GET /api/projects/[id]/workflow/state — JSON body on success.
+ * Matches `NextResponse.json({ success: true, data })` and `typedFetch` envelope unwrap.
+ */
+exports.WorkflowStateApiSuccessResponseSchema = zod_1.z.object({
+    success: zod_1.z.literal(true),
+    data: exports.WorkflowStateResponseSchema,
+});
+/** Display stat for workflow step stats cards (WorkflowStatsCard). */
+exports.WorkflowStatSchema = zod_1.z.object({
+    label: zod_1.z.string(),
+    value: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]),
+    trend: zod_1.z.enum(["up", "down", "neutral"]).optional(),
+    trendValue: zod_1.z.string().optional(),
+    variant: zod_1.z.enum(["default", "success", "warning", "destructive"]).optional(),
+});
+/** GET /api/projects/[id]/workflow/step-stats — supported step ids for metrics cards. */
+exports.WorkflowStepStatsStepIdSchema = zod_1.z.enum([
+    "specify",
+    "plan",
+    "schema",
+    "api",
+    "ui",
+    "constitution",
+    "guardian",
+    "tasks",
+    "implement",
+    "knowledge",
+    "ci",
+    "cicd",
+    "deploy",
+    "deployments",
+    "review",
+]);
+exports.WorkflowStepStatsResponseSchema = zod_1.z.object({
+    success: zod_1.z.literal(true),
+    data: zod_1.z.array(exports.WorkflowStatSchema),
+});
+exports.WorkflowResetStepRequestSchema = zod_1.z
+    .object({
+    stepId: zod_1.z.literal("api"),
+    dryRun: zod_1.z.boolean(),
+    confirm: zod_1.z.literal("RESET_API_STEP").optional(),
+})
+    .superRefine((body, ctx) => {
+    if (!body.dryRun && body.confirm !== "RESET_API_STEP") {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: "Destructive reset requires confirm token RESET_API_STEP",
+            path: ["confirm"],
+        });
+    }
+});
+exports.WorkflowResetStepResponseSchema = zod_1.z.object({
+    dryRun: zod_1.z.boolean(),
+    projectId: zod_1.z.string().uuid(),
+    stepId: zod_1.z.literal("api"),
+    wouldDelete: zod_1.z.object({
+        workflowArtifacts: zod_1.z.number().int().nonnegative(),
+        apiDefinitions: zod_1.z.number().int().nonnegative(),
+        apiKgNodes: zod_1.z.number().int().nonnegative(),
+        apiKgEdges: zod_1.z.number().int().nonnegative(),
+        orchestrationEvents: zod_1.z.number().int().nonnegative(),
+        aiRuns: zod_1.z.number().int().nonnegative(),
+        stepCompletionRows: zod_1.z.number().int().nonnegative(),
+    }),
+    protectedCounts: zod_1.z.object({
+        specifyArtifacts: zod_1.z.number().int().nonnegative(),
+        planArtifacts: zod_1.z.number().int().nonnegative(),
+        schemaArtifacts: zod_1.z.number().int().nonnegative(),
+        specifications: zod_1.z.number().int().nonnegative(),
+        nonApiKgNodes: zod_1.z.number().int().nonnegative(),
+        nonApiKgEdges: zod_1.z.number().int().nonnegative(),
+        workflowGates: zod_1.z.number().int().nonnegative(),
+    }),
+});
+/** GET /api/projects/[id]/workflow/step-ai-output — ai_runs + workflow_artifacts digest for AIOutputDisplay. */
+exports.WorkflowStepAiOutputRunRowSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    step: zod_1.z.string(),
+    status: zod_1.z.string(),
+    output: zod_1.z.unknown().nullable(),
+    metadata: zod_1.z.unknown().nullable(),
+    guardian_score_after: zod_1.z.number().nullable(),
+    created_at: zod_1.z.string(),
+    completed_at: zod_1.z.string().nullable(),
+});
+exports.WorkflowStepAiOutputArtifactRowSchema = zod_1.z.object({
+    stage_id: zod_1.z.string(),
+    artifact_type: zod_1.z.string(),
+    status: zod_1.z.string(),
+    guardian_score: zod_1.z.union([zod_1.z.number(), zod_1.z.string()]).nullable(),
+    payload: zod_1.z.unknown(),
+    created_at: zod_1.z.string(),
+});
+exports.WorkflowStepAiOutputResponseSchema = zod_1.z.object({
+    success: zod_1.z.literal(true),
+    data: zod_1.z.object({
+        aiRuns: zod_1.z.array(exports.WorkflowStepAiOutputRunRowSchema),
+        artifactRows: zod_1.z.array(exports.WorkflowStepAiOutputArtifactRowSchema),
+        /** Alias of artifactRows (latest per stage) for browser probes and legacy clients. */
+        artifacts: zod_1.z.array(exports.WorkflowStepAiOutputArtifactRowSchema),
+    }),
+});

package/dist/telemetry/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * NeuraLoom Telemetry - Single Source of Truth for Monitoring & Analytics
+ * All telemetry events must be defined and tracked through this package
+ */
+export interface TelemetryEvent {
+    type: TelemetryEventType;
+    timestamp: number;
+    sessionId?: string;
+    userId?: string;
+    projectId?: string;
+    metadata?: Record<string, unknown>;
+}
+export type TelemetryEventType = "system.startup" | "system.shutdown" | "system.error" | "build.started" | "build.completed" | "build.failed" | "validation.started" | "validation.completed" | "validation.failed" | "ssot.check.started" | "ssot.check.completed" | "ssot.violation.detected" | "user.login" | "user.logout" | "user.created" | "project.created" | "project.updated" | "project.deleted" | "spec.created" | "spec.approved" | "spec.rejected" | "plan.created" | "plan.started" | "plan.completed" | "task.created" | "task.started" | "task.completed" | "ml.training.started" | "ml.training.completed" | "ml.model.deployed" | "performance.metric" | "constitutional.violation";
+export interface SystemEvent extends TelemetryEvent {
+    type: "system.startup" | "system.shutdown" | "system.error";
+    metadata: {
+        version?: string;
+        environment?: string;
+        nodeVersion?: string;
+        error?: string;
+        stackTrace?: string;
+    };
+}
+export interface BuildEvent extends TelemetryEvent {
+    type: "build.started" | "build.completed" | "build.failed";
+    metadata: {
+        packageName: string;
+        duration?: number;
+        buildSize?: number;
+        error?: string;
+        warnings?: string[];
+    };
+}
+export interface ValidationEvent extends TelemetryEvent {
+    type: "validation.started" | "validation.completed" | "validation.failed";
+    metadata: {
+        validationType: "constitutional" | "typescript" | "ssot" | "performance";
+        duration: number;
+        violationsFound?: number;
+        error?: string;
+    };
+}
+export interface SSOTEvent extends TelemetryEvent {
+    type: "ssot.check.started" | "ssot.check.completed" | "ssot.violation.detected";
+    metadata: {
+        checkType: "inline_interfaces" | "hardcoded_css" | "env_fallbacks" | "import_compliance";
+        filesChecked?: number;
+        violationsFound?: number;
+        duration?: number;
+        violationDetails?: {
+            file: string;
+            line?: number;
+            rule: string;
+            severity: "low" | "medium" | "high" | "critical";
+        }[];
+    };
+}
+export interface UserEvent extends TelemetryEvent {
+    type: "user.login" | "user.logout" | "user.created";
+    metadata: {
+        userRole?: string;
+        loginMethod?: "email" | "oauth" | "sso";
+        success?: boolean;
+        error?: string;
+    };
+}
+export interface ProjectEvent extends TelemetryEvent {
+    type: "project.created" | "project.updated" | "project.deleted";
+    metadata: {
+        projectStatus?: string;
+        teamSize?: number;
+        estimatedHours?: number;
+        actualHours?: number;
+    };
+}
+export interface SpecEvent extends TelemetryEvent {
+    type: "spec.created" | "spec.approved" | "spec.rejected";
+    metadata: {
+        specPriority: string;
+        requirementsCount: number;
+        acceptanceCriteriaCount: number;
+        reviewDuration?: number;
+    };
+}
+export interface PlanEvent extends TelemetryEvent {
+    type: "plan.created" | "plan.started" | "plan.completed";
+    metadata: {
+        estimatedHours: number;
+        actualHours?: number;
+        tasksCount: number;
+        dependenciesCount: number;
+        planStatus: string;
+    };
+}
+export interface TaskEvent extends TelemetryEvent {
+    type: "task.created" | "task.started" | "task.completed";
+    metadata: {
+        taskType: string;
+        taskPriority: string;
+        estimatedHours: number;
+        actualHours?: number;
+        dependenciesCount: number;
+    };
+}
+export interface MLEvent extends TelemetryEvent {
+    type: "ml.training.started" | "ml.training.completed" | "ml.model.deployed";
+    metadata: {
+        modelType: string;
+        datasetSize?: number;
+        trainingDuration?: number;
+        accuracy?: number;
+        modelSize?: number;
+        deploymentTarget?: string;
+    };
+}
+export interface PerformanceEvent extends TelemetryEvent {
+    type: "performance.metric";
+    metadata: {
+        metricName: string;
+        metricValue: number;
+        metricUnit: string;
+        threshold?: number;
+        passed?: boolean;
+        component?: string;
+    };
+}
+export interface ConstitutionalViolationEvent extends TelemetryEvent {
+    type: "constitutional.violation";
+    metadata: {
+        violationType: string;
+        severity: "low" | "medium" | "high" | "critical";
+        file: string;
+        line?: number;
+        rule: string;
+        autoFixable?: boolean;
+    };
+}
+export interface TelemetryConfig {
+    enabled: boolean;
+    endpoint?: string;
+    apiKey?: string;
+    batchSize: number;
+    flushInterval: number;
+    retryAttempts: number;
+    enableDebugLogs: boolean;
+    enablePerformanceMetrics: boolean;
+    enableConstitutionalTracking: boolean;
+}
+export declare const DEFAULT_TELEMETRY_CONFIG: TelemetryConfig;
+export interface TelemetryClient {
+    track(event: TelemetryEvent): void;
+    trackSystem(event: Omit<SystemEvent, 'timestamp'>): void;
+    trackBuild(event: Omit<BuildEvent, 'timestamp'>): void;
+    trackValidation(event: Omit<ValidationEvent, 'timestamp'>): void;
+    trackSSOT(event: Omit<SSOTEvent, 'timestamp'>): void;
+    trackUser(event: Omit<UserEvent, 'timestamp'>): void;
+    trackProject(event: Omit<ProjectEvent, 'timestamp'>): void;
+    trackSpec(event: Omit<SpecEvent, 'timestamp'>): void;
+    trackPlan(event: Omit<PlanEvent, 'timestamp'>): void;
+    trackTask(event: Omit<TaskEvent, 'timestamp'>): void;
+    trackML(event: Omit<MLEvent, 'timestamp'>): void;
+    trackPerformance(event: Omit<PerformanceEvent, 'timestamp'>): void;
+    trackConstitutionalViolation(event: Omit<ConstitutionalViolationEvent, 'timestamp'>): void;
+    flush(): Promise<void>;
+    configure(config: Partial<TelemetryConfig>): void;
+}
+export declare const PERFORMANCE_METRICS: {
+    readonly BUILD_TIME: "build_time";
+    readonly TYPE_CHECK_TIME: "typecheck_time";
+    readonly VALIDATION_TIME: "validation_time";
+    readonly BUNDLE_SIZE: "bundle_size";
+    readonly API_RESPONSE_TIME: "api_response_time";
+    readonly MEMORY_USAGE: "memory_usage";
+    readonly CPU_USAGE: "cpu_usage";
+};
+export declare const PERFORMANCE_THRESHOLDS: {
+    readonly build_time: 10000;
+    readonly typecheck_time: 5000;
+    readonly validation_time: 2000;
+    readonly bundle_size: 512000;
+    readonly api_response_time: 200;
+    readonly memory_usage: 1024;
+    readonly cpu_usage: 80;
+};
+export declare const TelemetryUtils: {
+    readonly generateSessionId: () => string;
+    readonly createBaseEvent: (type: TelemetryEventType, metadata?: Record<string, unknown>) => TelemetryEvent;
+    readonly validateEvent: (event: TelemetryEvent) => boolean;
+    readonly sanitizeMetadata: (metadata: Record<string, unknown>) => Record<string, unknown>;
+    readonly checkPerformanceThreshold: (metricName: string, value: number) => boolean;
+    readonly formatDuration: (milliseconds: number) => string;
+    readonly formatFileSize: (bytes: number) => string;
+};
+export type AllTelemetryEvents = SystemEvent | BuildEvent | ValidationEvent | SSOTEvent | UserEvent | ProjectEvent | SpecEvent | PlanEvent | TaskEvent | MLEvent | PerformanceEvent | ConstitutionalViolationEvent;

package/dist/telemetry/index.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * NeuraLoom Telemetry - Single Source of Truth for Monitoring & Analytics
+ * All telemetry events must be defined and tracked through this package
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryUtils = exports.PERFORMANCE_THRESHOLDS = exports.PERFORMANCE_METRICS = exports.DEFAULT_TELEMETRY_CONFIG = void 0;
+// Default Telemetry Configuration
+exports.DEFAULT_TELEMETRY_CONFIG = {
+    enabled: true,
+    batchSize: 10,
+    flushInterval: 5000, // 5 seconds
+    retryAttempts: 3,
+    enableDebugLogs: false,
+    enablePerformanceMetrics: true,
+    enableConstitutionalTracking: true,
+};
+// Performance Metrics Constants
+exports.PERFORMANCE_METRICS = {
+    BUILD_TIME: "build_time",
+    TYPE_CHECK_TIME: "typecheck_time",
+    VALIDATION_TIME: "validation_time",
+    BUNDLE_SIZE: "bundle_size",
+    API_RESPONSE_TIME: "api_response_time",
+    MEMORY_USAGE: "memory_usage",
+    CPU_USAGE: "cpu_usage",
+};
+// Performance Thresholds
+exports.PERFORMANCE_THRESHOLDS = {
+    [exports.PERFORMANCE_METRICS.BUILD_TIME]: 10000, // 10 seconds
+    [exports.PERFORMANCE_METRICS.TYPE_CHECK_TIME]: 5000, // 5 seconds
+    [exports.PERFORMANCE_METRICS.VALIDATION_TIME]: 2000, // 2 seconds
+    [exports.PERFORMANCE_METRICS.BUNDLE_SIZE]: 512000, // 500KB
+    [exports.PERFORMANCE_METRICS.API_RESPONSE_TIME]: 200, // 200ms
+    [exports.PERFORMANCE_METRICS.MEMORY_USAGE]: 1024, // 1GB
+    [exports.PERFORMANCE_METRICS.CPU_USAGE]: 80, // 80%
+};
+// Telemetry Utilities
+exports.TelemetryUtils = {
+    // Generate unique session ID
+    generateSessionId: () => {
+        return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    },
+    // Create base event with timestamp
+    createBaseEvent: (type, metadata) => ({
+        type,
+        timestamp: Date.now(),
+        ...(metadata && { metadata }),
+    }),
+    // Validate event structure
+    validateEvent: (event) => {
+        return (typeof event.type === "string" &&
+            typeof event.timestamp === "number" &&
+            event.timestamp > 0 &&
+            (event.metadata === undefined || typeof event.metadata === "object"));
+    },
+    // Sanitize metadata to remove sensitive information
+    sanitizeMetadata: (metadata) => {
+        const sensitiveKeys = ["password", "token", "apiKey", "secret", "auth"];
+        const sanitized = { ...metadata };
+        Object.keys(sanitized).forEach(key => {
+            const lowerKey = key.toLowerCase();
+            if (sensitiveKeys.some(sensitiveKey => lowerKey.includes(sensitiveKey))) {
+                sanitized[key] = "[REDACTED]";
+            }
+        });
+        return sanitized;
+    },
+    // Check if performance metric exceeds threshold
+    checkPerformanceThreshold: (metricName, value) => {
+        const threshold = exports.PERFORMANCE_THRESHOLDS[metricName];
+        return threshold ? value <= threshold : true;
+    },
+    // Format duration in milliseconds to human readable
+    formatDuration: (milliseconds) => {
+        if (milliseconds < 1000)
+            return `${milliseconds}ms`;
+        if (milliseconds < 60000)
+            return `${(milliseconds / 1000).toFixed(1)}s`;
+        return `${(milliseconds / 60000).toFixed(1)}m`;
+    },
+    // Format file size in bytes to human readable
+    formatFileSize: (bytes) => {
+        const units = ["B", "KB", "MB", "GB"];
+        let size = bytes;
+        let unitIndex = 0;
+        while (size >= 1024 && unitIndex < units.length - 1) {
+            size /= 1024;
+            unitIndex++;
+        }
+        return `${size.toFixed(1)}${units[unitIndex]}`;
+    },
+};