@contractspec/lib.evolution 3.7.6 → 3.7.10

package/dist/index.js

@@ -1,765 +1,762 @@
 // @bun
-// src/analyzer/spec-analyzer.ts
-import { randomUUID } from "crypto";
-import { LifecycleStage } from "@contractspec/lib.lifecycle";
-var DEFAULT_OPTIONS = {
-  minSampleSize: 50,
-  errorRateThreshold: 0.05,
-  latencyP99ThresholdMs: 750
-};
-
-class SpecAnalyzer {
-  logger;
-  minSampleSize;
-  errorRateThreshold;
-  latencyP99ThresholdMs;
-  throughputDropThreshold;
-  constructor(options = {}) {
-    this.logger = options.logger;
-    this.minSampleSize = options.minSampleSize ?? DEFAULT_OPTIONS.minSampleSize;
-    this.errorRateThreshold = options.errorRateThreshold ?? DEFAULT_OPTIONS.errorRateThreshold;
-    this.latencyP99ThresholdMs = options.latencyP99ThresholdMs ?? DEFAULT_OPTIONS.latencyP99ThresholdMs;
-    this.throughputDropThreshold = options.throughputDropThreshold ?? 0.2;
+// src/analyzer/posthog-telemetry-reader.ts
+class PosthogTelemetryReader {
+  reader;
+  eventPrefix;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.eventPrefix = options.eventPrefix ?? "observability";
   }
-  analyzeSpecUsage(samples) {
-    if (!samples.length) {
-      this.logger?.debug("SpecAnalyzer.analyzeSpecUsage.skip", {
-        reason: "no-samples"
-      });
-      return [];
-    }
-    const groups = new Map;
-    for (const sample of samples) {
-      const key = this.operationKey(sample);
-      const arr = groups.get(key) ?? [];
-      arr.push(sample);
-      groups.set(key, arr);
-    }
-    const entries = [...groups.values()];
-    const usable = entries.filter((samplesForOp) => {
-      const valid = samplesForOp.length >= this.minSampleSize;
-      if (!valid) {
-        this.logger?.debug("SpecAnalyzer.analyzeSpecUsage.skipOperation", {
-          operation: this.operationKey(samplesForOp[0]),
-          sampleSize: samplesForOp.length,
-          minSampleSize: this.minSampleSize
-        });
-      }
-      return valid;
+  async readOperationSamples(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.operation as operationKey,",
+        "  properties.version as version,",
+        "  properties.durationMs as durationMs,",
+        "  properties.success as success,",
+        "  properties.errorCode as errorCode,",
+        "  properties.tenantId as tenantId,",
+        "  properties.traceId as traceId,",
+        "  properties.metadata as metadata,",
+        "  timestamp as timestamp",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, input)}`,
+        "order by timestamp desc",
+        `limit ${input.limit ?? 1000}`
+      ].join(`
+`),
+      values: buildOperationValues(input)
     });
-    return usable.map((operationSamples) => this.buildUsageStats(operationSamples));
+    return mapOperationSamples(result);
   }
-  detectAnomalies(stats, baseline) {
-    const anomalies = [];
-    if (!stats.length) {
-      this.logger?.debug("SpecAnalyzer.detectAnomalies.skip", {
-        reason: "no-stats"
-      });
-      return anomalies;
-    }
-    const baselineByOp = new Map((baseline ?? []).map((item) => [this.operationKey(item.operation), item]));
-    for (const stat of stats) {
-      const evidence = [];
-      if (stat.errorRate >= this.errorRateThreshold) {
-        evidence.push({
-          type: "telemetry",
-          description: `Error rate ${stat.errorRate.toFixed(2)} exceeded threshold ${this.errorRateThreshold}`,
-          data: { errorRate: stat.errorRate }
-        });
-        anomalies.push({
-          operation: stat.operation,
-          severity: this.toSeverity(stat.errorRate / this.errorRateThreshold),
-          metric: "error-rate",
-          description: "Error rate spike",
-          detectedAt: new Date,
-          threshold: this.errorRateThreshold,
-          observedValue: stat.errorRate,
-          evidence
-        });
-        continue;
-      }
-      if (stat.p99LatencyMs >= this.latencyP99ThresholdMs) {
-        evidence.push({
-          type: "telemetry",
-          description: `P99 latency ${stat.p99LatencyMs}ms exceeded threshold ${this.latencyP99ThresholdMs}ms`,
-          data: { p99LatencyMs: stat.p99LatencyMs }
-        });
-        anomalies.push({
-          operation: stat.operation,
-          severity: this.toSeverity(stat.p99LatencyMs / this.latencyP99ThresholdMs),
-          metric: "latency",
-          description: "Latency regression detected",
-          detectedAt: new Date,
-          threshold: this.latencyP99ThresholdMs,
-          observedValue: stat.p99LatencyMs,
-          evidence
-        });
-        continue;
-      }
-      const baselineStat = baselineByOp.get(this.operationKey(stat.operation));
-      if (baselineStat) {
-        const drop = (baselineStat.totalCalls - stat.totalCalls) / baselineStat.totalCalls;
-        if (drop >= this.throughputDropThreshold) {
-          evidence.push({
-            type: "telemetry",
-            description: `Throughput dropped by ${(drop * 100).toFixed(1)}% compared to baseline`,
-            data: {
-              baselineCalls: baselineStat.totalCalls,
-              currentCalls: stat.totalCalls
-            }
-          });
-          anomalies.push({
-            operation: stat.operation,
-            severity: this.toSeverity(drop / this.throughputDropThreshold),
-            metric: "throughput",
-            description: "Usage drop detected",
-            detectedAt: new Date,
-            threshold: this.throughputDropThreshold,
-            observedValue: drop,
-            evidence
-          });
-        }
-      }
-    }
-    return anomalies;
+  async readAnomalyBaseline(operation, windowDays = 7) {
+    const dateRange = buildWindowRange(windowDays);
+    const baseResult = await this.queryHogQL({
+      query: [
+        "select",
+        "  count() as totalCalls,",
+        "  avg(properties.durationMs) as averageLatencyMs,",
+        "  quantile(0.95)(properties.durationMs) as p95LatencyMs,",
+        "  quantile(0.99)(properties.durationMs) as p99LatencyMs,",
+        "  max(properties.durationMs) as maxLatencyMs,",
+        "  sum(if(properties.success = 1, 1, 0)) as successCount,",
+        "  sum(if(properties.success = 0, 1, 0)) as errorCount",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, {
+          operations: [operation],
+          dateRange
+        })}`
+      ].join(`
+`),
+      values: buildOperationValues({
+        operations: [operation],
+        dateRange
+      })
+    });
+    const stats = mapBaselineStats(baseResult, operation, dateRange);
+    if (!stats)
+      return null;
+    const topErrors = await this.readTopErrors(operation, dateRange);
+    return {
+      ...stats,
+      topErrors
+    };
   }
-  toIntentPatterns(anomalies, stats) {
-    const statsByOp = new Map(stats.map((item) => [this.operationKey(item.operation), item]));
-    return anomalies.map((anomaly) => {
-      const stat = statsByOp.get(this.operationKey(anomaly.operation));
-      const confidence = {
-        score: Math.min(1, (anomaly.observedValue ?? 0) / (anomaly.threshold ?? 1)),
-        sampleSize: stat?.totalCalls ?? 0,
-        pValue: undefined
-      };
-      return {
-        id: randomUUID(),
-        type: this.mapMetricToIntent(anomaly.metric),
-        description: anomaly.description,
-        operation: anomaly.operation,
-        confidence,
-        metadata: {
-          observedValue: anomaly.observedValue,
-          threshold: anomaly.threshold
-        },
-        evidence: anomaly.evidence
-      };
+  async readTopErrors(operation, dateRange) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.errorCode as errorCode,",
+        "  count() as errorCount",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, {
+          operations: [operation],
+          dateRange
+        })} and properties.success = 0`,
+        "group by errorCode",
+        "order by errorCount desc",
+        "limit 5"
+      ].join(`
+`),
+      values: buildOperationValues({
+        operations: [operation],
+        dateRange
+      })
     });
+    const rows = mapRows(result);
+    return rows.reduce((acc, row) => {
+      const code = asString(row.errorCode);
+      if (!code)
+        return acc;
+      acc[code] = asNumber(row.errorCount);
+      return acc;
+    }, {});
   }
-  suggestOptimizations(stats, anomalies, lifecycleContext) {
-    const anomaliesByOp = new Map(this.groupByOperation(anomalies));
-    const hints = [];
-    for (const stat of stats) {
-      const opKey = this.operationKey(stat.operation);
-      const opAnomalies = anomaliesByOp.get(opKey) ?? [];
-      for (const anomaly of opAnomalies) {
-        if (anomaly.metric === "latency") {
-          hints.push(this.applyLifecycleContext({
-            operation: stat.operation,
-            category: "performance",
-            summary: "Latency regression detected",
-            justification: `P99 latency at ${stat.p99LatencyMs}ms`,
-            recommendedActions: [
-              "Add batching or caching layer",
-              "Replay golden tests to capture slow inputs"
-            ]
-          }, lifecycleContext?.stage));
-        } else if (anomaly.metric === "error-rate") {
-          const topError = Object.entries(stat.topErrors).sort((a, b) => b[1] - a[1])[0]?.[0];
-          hints.push(this.applyLifecycleContext({
-            operation: stat.operation,
-            category: "error-handling",
-            summary: "Error spike detected",
-            justification: topError ? `Dominant error code ${topError}` : "Increase in failures",
-            recommendedActions: [
-              "Generate regression spec from failing payloads",
-              "Add policy guardrails before rollout"
-            ]
-          }, lifecycleContext?.stage));
-        } else if (anomaly.metric === "throughput") {
-          hints.push(this.applyLifecycleContext({
-            operation: stat.operation,
-            category: "performance",
-            summary: "Throughput drop detected",
-            justification: "Significant traffic reduction relative to baseline",
-            recommendedActions: [
-              "Validate routing + feature flag bucketing",
-              "Backfill spec variant to rehydrate demand"
-            ]
-          }, lifecycleContext?.stage));
-        }
-      }
+  async queryHogQL(input) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
     }
-    return hints;
+    return this.reader.queryHogQL(input);
   }
-  operationKey(op) {
-    const coordinate = "operation" in op ? op.operation : op;
-    return `${coordinate.key}.v${coordinate.version}${coordinate.tenantId ? `@${coordinate.tenantId}` : ""}`;
+}
+function buildOperationWhereClause(eventPrefix, input) {
+  const clauses = [`event = '${eventPrefix}.operation'`];
+  if (input.operations?.length) {
+    clauses.push(`(${buildOperationFilters(input.operations)})`);
   }
-  buildUsageStats(samples) {
-    const durations = samples.map((s) => s.durationMs).sort((a, b) => a - b);
-    const errors = samples.filter((s) => !s.success);
-    const totalCalls = samples.length;
-    const successRate = (totalCalls - errors.length) / totalCalls;
-    const errorRate = errors.length / totalCalls;
-    const averageLatencyMs = durations.reduce((sum, value) => sum + value, 0) / totalCalls;
-    const topErrors = errors.reduce((acc, sample) => {
-      if (!sample.errorCode)
-        return acc;
-      acc[sample.errorCode] = (acc[sample.errorCode] ?? 0) + 1;
-      return acc;
-    }, {});
-    const timestamps = samples.map((s) => s.timestamp.getTime());
-    const windowStart = new Date(Math.min(...timestamps));
-    const windowEnd = new Date(Math.max(...timestamps));
-    return {
-      operation: samples[0].operation,
-      totalCalls,
-      successRate,
-      errorRate,
-      averageLatencyMs,
-      p95LatencyMs: percentile(durations, 0.95),
-      p99LatencyMs: percentile(durations, 0.99),
-      maxLatencyMs: Math.max(...durations),
-      lastSeenAt: windowEnd,
-      windowStart,
-      windowEnd,
-      topErrors
-    };
+  if (input.dateRange?.from) {
+    clauses.push("timestamp >= {dateFrom}");
   }
-  toSeverity(ratio) {
-    if (ratio >= 2)
-      return "high";
-    if (ratio >= 1.3)
-      return "medium";
-    return "low";
+  if (input.dateRange?.to) {
+    clauses.push("timestamp < {dateTo}");
   }
-  mapMetricToIntent(metric) {
-    switch (metric) {
-      case "error-rate":
-        return "error-spike";
-      case "latency":
-        return "latency-regression";
-      case "throughput":
-        return "throughput-drop";
-      default:
-        return "schema-mismatch";
+  return clauses.join(" and ");
+}
+function buildOperationValues(input) {
+  const values = {
+    dateFrom: toIsoString(input.dateRange?.from),
+    dateTo: toIsoString(input.dateRange?.to)
+  };
+  input.operations?.forEach((op, index) => {
+    values[`operationKey${index}`] = op.key;
+    values[`operationVersion${index}`] = op.version;
+    if (op.tenantId) {
+      values[`operationTenant${index}`] = op.tenantId;
     }
-  }
-  groupByOperation(items) {
-    const map = new Map;
-    for (const item of items) {
-      const key = this.operationKey(item.operation);
-      const arr = map.get(key) ?? [];
-      arr.push(item);
-      map.set(key, arr);
+  });
+  return values;
+}
+function buildOperationFilters(operations) {
+  return operations.map((op, index) => {
+    const clauses = [
+      `properties.operation = {operationKey${index}}`,
+      `properties.version = {operationVersion${index}}`
+    ];
+    if (op.tenantId) {
+      clauses.push(`properties.tenantId = {operationTenant${index}}`);
     }
-    return map;
-  }
-  applyLifecycleContext(hint, stage) {
-    if (stage === undefined)
-      return hint;
-    const band = mapStageBand(stage);
-    const advice = LIFECYCLE_HINTS[band]?.[hint.category];
-    if (!advice) {
-      return { ...hint, lifecycleStage: stage };
+    return `(${clauses.join(" and ")})`;
+  }).join(" or ");
+}
+function mapOperationSamples(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const operationKey = asString(row.operationKey);
+    const version = asString(row.version);
+    const timestamp = asDate(row.timestamp);
+    if (!operationKey || !version || !timestamp) {
+      return [];
     }
-    return {
-      ...hint,
-      lifecycleStage: stage,
-      lifecycleNotes: advice.message,
-      recommendedActions: dedupeActions([
-        ...hint.recommendedActions,
-        ...advice.supplementalActions
-      ])
-    };
+    return [
+      {
+        operation: {
+          key: operationKey,
+          version,
+          tenantId: asOptionalString(row.tenantId) ?? undefined
+        },
+        durationMs: asNumber(row.durationMs),
+        success: asBoolean(row.success),
+        timestamp,
+        errorCode: asOptionalString(row.errorCode) ?? undefined,
+        traceId: asOptionalString(row.traceId) ?? undefined,
+        metadata: isRecord(row.metadata) ? row.metadata : undefined
+      }
+    ];
+  });
+}
+function mapBaselineStats(result, operation, dateRange) {
+  const rows = mapRows(result);
+  const row = rows[0];
+  if (!row)
+    return null;
+  const totalCalls = asNumber(row.totalCalls);
+  if (!totalCalls)
+    return null;
+  const successCount = asNumber(row.successCount);
+  const errorCount = asNumber(row.errorCount);
+  return {
+    operation,
+    totalCalls,
+    successRate: totalCalls ? successCount / totalCalls : 0,
+    errorRate: totalCalls ? errorCount / totalCalls : 0,
+    averageLatencyMs: asNumber(row.averageLatencyMs),
+    p95LatencyMs: asNumber(row.p95LatencyMs),
+    p99LatencyMs: asNumber(row.p99LatencyMs),
+    maxLatencyMs: asNumber(row.maxLatencyMs),
+    lastSeenAt: new Date,
+    windowStart: toDate(dateRange.from) ?? new Date,
+    windowEnd: toDate(dateRange.to) ?? new Date,
+    topErrors: {}
+  };
+}
+function mapRows(result) {
+  if (!Array.isArray(result.results) || !Array.isArray(result.columns)) {
+    return [];
   }
+  const columns = result.columns;
+  return result.results.flatMap((row) => {
+    if (!Array.isArray(row))
+      return [];
+    const record = {};
+    columns.forEach((column, index) => {
+      record[column] = row[index];
+    });
+    return [record];
+  });
 }
-function percentile(values, p) {
-  if (!values.length)
-    return 0;
-  if (values.length === 1)
-    return values[0];
-  const idx = Math.min(values.length - 1, Math.floor(p * values.length));
-  return values[idx];
+function buildWindowRange(windowDays) {
+  const windowEnd = new Date;
+  const windowStart = new Date(windowEnd.getTime() - windowDays * 24 * 60 * 60 * 1000);
+  return {
+    from: windowStart,
+    to: windowEnd
+  };
 }
-var mapStageBand = (stage) => {
-  if (stage <= 2)
-    return "early";
-  if (stage === LifecycleStage.ProductMarketFit)
-    return "pmf";
-  if (stage === LifecycleStage.GrowthScaleUp || stage === LifecycleStage.ExpansionPlatform) {
-    return "scale";
-  }
-  return "mature";
-};
-var LIFECYCLE_HINTS = {
-  early: {
-    performance: {
-      message: "Favor guardrails that protect learning velocity before heavy rewrites.",
-      supplementalActions: [
-        "Wrap risky changes behind progressive delivery flags"
-      ]
-    },
-    "error-handling": {
-      message: "Make failures loud and recoverable so you can learn faster.",
-      supplementalActions: ["Add auto-rollbacks or manual kill switches"]
-    }
-  },
-  pmf: {
-    performance: {
-      message: "Stabilize the core use case to avoid regressions while demand grows.",
-      supplementalActions: ["Instrument regression tests on critical specs"]
-    }
-  },
-  scale: {
-    performance: {
-      message: "Prioritize resilience and multi-tenant safety as volumes expand.",
-      supplementalActions: [
-        "Introduce workload partitioning or isolation per tenant"
-      ]
-    },
-    "error-handling": {
-      message: "Contain blast radius with policy fallbacks and circuit breakers.",
-      supplementalActions: ["Add circuit breakers to high-risk operations"]
-    }
-  },
-  mature: {
-    performance: {
-      message: "Optimize for margins and predictable SLAs.",
-      supplementalActions: [
-        "Capture unit-cost impacts alongside latency fixes"
-      ]
-    },
-    "error-handling": {
-      message: "Prevent regressions with automated regression specs before deploy.",
-      supplementalActions: [
-        "Run auto-evolution simulations on renewal scenarios"
-      ]
-    }
-  }
-};
-var dedupeActions = (actions) => {
-  const seen = new Set;
-  const ordered = [];
-  for (const action of actions) {
-    if (seen.has(action))
-      continue;
-    seen.add(action);
-    ordered.push(action);
-  }
-  return ordered;
-};
-// src/analyzer/posthog-telemetry-reader.ts
-class PosthogTelemetryReader {
-  reader;
-  eventPrefix;
-  constructor(reader, options = {}) {
-    this.reader = reader;
-    this.eventPrefix = options.eventPrefix ?? "observability";
-  }
-  async readOperationSamples(input) {
-    const result = await this.queryHogQL({
-      query: [
-        "select",
-        "  properties.operation as operationKey,",
-        "  properties.version as version,",
-        "  properties.durationMs as durationMs,",
-        "  properties.success as success,",
-        "  properties.errorCode as errorCode,",
-        "  properties.tenantId as tenantId,",
-        "  properties.traceId as traceId,",
-        "  properties.metadata as metadata,",
-        "  timestamp as timestamp",
-        "from events",
-        `where ${buildOperationWhereClause(this.eventPrefix, input)}`,
-        "order by timestamp desc",
-        `limit ${input.limit ?? 1000}`
-      ].join(`
-`),
-      values: buildOperationValues(input)
-    });
-    return mapOperationSamples(result);
-  }
-  async readAnomalyBaseline(operation, windowDays = 7) {
-    const dateRange = buildWindowRange(windowDays);
-    const baseResult = await this.queryHogQL({
-      query: [
-        "select",
-        "  count() as totalCalls,",
-        "  avg(properties.durationMs) as averageLatencyMs,",
-        "  quantile(0.95)(properties.durationMs) as p95LatencyMs,",
-        "  quantile(0.99)(properties.durationMs) as p99LatencyMs,",
-        "  max(properties.durationMs) as maxLatencyMs,",
-        "  sum(if(properties.success = 1, 1, 0)) as successCount,",
-        "  sum(if(properties.success = 0, 1, 0)) as errorCount",
-        "from events",
-        `where ${buildOperationWhereClause(this.eventPrefix, {
-          operations: [operation],
-          dateRange
-        })}`
-      ].join(`
-`),
-      values: buildOperationValues({
-        operations: [operation],
-        dateRange
-      })
-    });
-    const stats = mapBaselineStats(baseResult, operation, dateRange);
-    if (!stats)
-      return null;
-    const topErrors = await this.readTopErrors(operation, dateRange);
-    return {
-      ...stats,
-      topErrors
-    };
-  }
-  async readTopErrors(operation, dateRange) {
-    const result = await this.queryHogQL({
-      query: [
-        "select",
-        "  properties.errorCode as errorCode,",
-        "  count() as errorCount",
-        "from events",
-        `where ${buildOperationWhereClause(this.eventPrefix, {
-          operations: [operation],
-          dateRange
-        })} and properties.success = 0`,
-        "group by errorCode",
-        "order by errorCount desc",
-        "limit 5"
-      ].join(`
-`),
-      values: buildOperationValues({
-        operations: [operation],
-        dateRange
-      })
-    });
-    const rows = mapRows(result);
-    return rows.reduce((acc, row) => {
-      const code = asString(row.errorCode);
-      if (!code)
-        return acc;
-      acc[code] = asNumber(row.errorCount);
-      return acc;
-    }, {});
-  }
-  async queryHogQL(input) {
-    if (!this.reader.queryHogQL) {
-      throw new Error("Analytics reader does not support HogQL queries.");
-    }
-    return this.reader.queryHogQL(input);
+function asString(value) {
+  if (typeof value === "string" && value.trim())
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asOptionalString(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed))
+      return parsed;
   }
+  return 0;
 }
-function buildOperationWhereClause(eventPrefix, input) {
-  const clauses = [`event = '${eventPrefix}.operation'`];
-  if (input.operations?.length) {
-    clauses.push(`(${buildOperationFilters(input.operations)})`);
-  }
-  if (input.dateRange?.from) {
-    clauses.push("timestamp >= {dateFrom}");
-  }
-  if (input.dateRange?.to) {
-    clauses.push("timestamp < {dateTo}");
+function asBoolean(value) {
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "number")
+    return value !== 0;
+  if (typeof value === "string")
+    return value.toLowerCase() === "true";
+  return false;
+}
+function asDate(value) {
+  if (value instanceof Date)
+    return value;
+  if (typeof value === "string" || typeof value === "number") {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime()))
+      return date;
   }
-  return clauses.join(" and ");
+  return null;
 }
-function buildOperationValues(input) {
-  const values = {
-    dateFrom: toIsoString(input.dateRange?.from),
-    dateTo: toIsoString(input.dateRange?.to)
-  };
-  input.operations?.forEach((op, index) => {
-    values[`operationKey${index}`] = op.key;
-    values[`operationVersion${index}`] = op.version;
-    if (op.tenantId) {
-      values[`operationTenant${index}`] = op.tenantId;
-    }
-  });
-  return values;
+function toIsoString(value) {
+  if (!value)
+    return;
+  return typeof value === "string" ? value : value.toISOString();
 }
-function buildOperationFilters(operations) {
-  return operations.map((op, index) => {
-    const clauses = [
-      `properties.operation = {operationKey${index}}`,
-      `properties.version = {operationVersion${index}}`
-    ];
-    if (op.tenantId) {
-      clauses.push(`properties.tenantId = {operationTenant${index}}`);
-    }
-    return `(${clauses.join(" and ")})`;
-  }).join(" or ");
+function toDate(value) {
+  if (!value)
+    return null;
+  return value instanceof Date ? value : new Date(value);
 }
-function mapOperationSamples(result) {
-  const rows = mapRows(result);
-  return rows.flatMap((row) => {
-    const operationKey = asString(row.operationKey);
-    const version = asString(row.version);
-    const timestamp = asDate(row.timestamp);
-    if (!operationKey || !version || !timestamp) {
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+// src/analyzer/spec-analyzer.ts
+import { randomUUID } from "crypto";
+import { LifecycleStage } from "@contractspec/lib.lifecycle";
+var DEFAULT_OPTIONS = {
+  minSampleSize: 50,
+  errorRateThreshold: 0.05,
+  latencyP99ThresholdMs: 750
+};
+
+class SpecAnalyzer {
+  logger;
+  minSampleSize;
+  errorRateThreshold;
+  latencyP99ThresholdMs;
+  throughputDropThreshold;
+  constructor(options = {}) {
+    this.logger = options.logger;
+    this.minSampleSize = options.minSampleSize ?? DEFAULT_OPTIONS.minSampleSize;
+    this.errorRateThreshold = options.errorRateThreshold ?? DEFAULT_OPTIONS.errorRateThreshold;
+    this.latencyP99ThresholdMs = options.latencyP99ThresholdMs ?? DEFAULT_OPTIONS.latencyP99ThresholdMs;
+    this.throughputDropThreshold = options.throughputDropThreshold ?? 0.2;
+  }
+  analyzeSpecUsage(samples) {
+    if (!samples.length) {
+      this.logger?.debug("SpecAnalyzer.analyzeSpecUsage.skip", {
+        reason: "no-samples"
+      });
       return [];
     }
-    return [
-      {
-        operation: {
-          key: operationKey,
-          version,
-          tenantId: asOptionalString(row.tenantId) ?? undefined
-        },
-        durationMs: asNumber(row.durationMs),
-        success: asBoolean(row.success),
-        timestamp,
-        errorCode: asOptionalString(row.errorCode) ?? undefined,
-        traceId: asOptionalString(row.traceId) ?? undefined,
-        metadata: isRecord(row.metadata) ? row.metadata : undefined
-      }
-    ];
-  });
-}
-function mapBaselineStats(result, operation, dateRange) {
-  const rows = mapRows(result);
-  const row = rows[0];
-  if (!row)
-    return null;
-  const totalCalls = asNumber(row.totalCalls);
-  if (!totalCalls)
-    return null;
-  const successCount = asNumber(row.successCount);
-  const errorCount = asNumber(row.errorCount);
-  return {
-    operation,
-    totalCalls,
-    successRate: totalCalls ? successCount / totalCalls : 0,
-    errorRate: totalCalls ? errorCount / totalCalls : 0,
-    averageLatencyMs: asNumber(row.averageLatencyMs),
-    p95LatencyMs: asNumber(row.p95LatencyMs),
-    p99LatencyMs: asNumber(row.p99LatencyMs),
-    maxLatencyMs: asNumber(row.maxLatencyMs),
-    lastSeenAt: new Date,
-    windowStart: toDate(dateRange.from) ?? new Date,
-    windowEnd: toDate(dateRange.to) ?? new Date,
-    topErrors: {}
-  };
-}
-function mapRows(result) {
-  if (!Array.isArray(result.results) || !Array.isArray(result.columns)) {
-    return [];
+    const groups = new Map;
+    for (const sample of samples) {
+      const key = this.operationKey(sample);
+      const arr = groups.get(key) ?? [];
+      arr.push(sample);
+      groups.set(key, arr);
+    }
+    const entries = [...groups.values()];
+    const usable = entries.filter((samplesForOp) => {
+      const valid = samplesForOp.length >= this.minSampleSize;
+      if (!valid) {
+        this.logger?.debug("SpecAnalyzer.analyzeSpecUsage.skipOperation", {
+          operation: this.operationKey(samplesForOp[0]),
+          sampleSize: samplesForOp.length,
+          minSampleSize: this.minSampleSize
+        });
+      }
+      return valid;
+    });
+    return usable.map((operationSamples) => this.buildUsageStats(operationSamples));
   }
-  const columns = result.columns;
-  return result.results.flatMap((row) => {
-    if (!Array.isArray(row))
-      return [];
-    const record = {};
-    columns.forEach((column, index) => {
-      record[column] = row[index];
+  detectAnomalies(stats, baseline) {
+    const anomalies = [];
+    if (!stats.length) {
+      this.logger?.debug("SpecAnalyzer.detectAnomalies.skip", {
+        reason: "no-stats"
+      });
+      return anomalies;
+    }
+    const baselineByOp = new Map((baseline ?? []).map((item) => [this.operationKey(item.operation), item]));
+    for (const stat of stats) {
+      const evidence = [];
+      if (stat.errorRate >= this.errorRateThreshold) {
+        evidence.push({
+          type: "telemetry",
+          description: `Error rate ${stat.errorRate.toFixed(2)} exceeded threshold ${this.errorRateThreshold}`,
+          data: { errorRate: stat.errorRate }
+        });
+        anomalies.push({
+          operation: stat.operation,
+          severity: this.toSeverity(stat.errorRate / this.errorRateThreshold),
+          metric: "error-rate",
+          description: "Error rate spike",
+          detectedAt: new Date,
+          threshold: this.errorRateThreshold,
+          observedValue: stat.errorRate,
+          evidence
+        });
+        continue;
+      }
+      if (stat.p99LatencyMs >= this.latencyP99ThresholdMs) {
+        evidence.push({
+          type: "telemetry",
+          description: `P99 latency ${stat.p99LatencyMs}ms exceeded threshold ${this.latencyP99ThresholdMs}ms`,
+          data: { p99LatencyMs: stat.p99LatencyMs }
+        });
+        anomalies.push({
+          operation: stat.operation,
+          severity: this.toSeverity(stat.p99LatencyMs / this.latencyP99ThresholdMs),
+          metric: "latency",
+          description: "Latency regression detected",
+          detectedAt: new Date,
+          threshold: this.latencyP99ThresholdMs,
+          observedValue: stat.p99LatencyMs,
+          evidence
+        });
+        continue;
+      }
+      const baselineStat = baselineByOp.get(this.operationKey(stat.operation));
+      if (baselineStat) {
+        const drop = (baselineStat.totalCalls - stat.totalCalls) / baselineStat.totalCalls;
+        if (drop >= this.throughputDropThreshold) {
+          evidence.push({
+            type: "telemetry",
+            description: `Throughput dropped by ${(drop * 100).toFixed(1)}% compared to baseline`,
+            data: {
+              baselineCalls: baselineStat.totalCalls,
+              currentCalls: stat.totalCalls
+            }
+          });
+          anomalies.push({
+            operation: stat.operation,
+            severity: this.toSeverity(drop / this.throughputDropThreshold),
+            metric: "throughput",
+            description: "Usage drop detected",
+            detectedAt: new Date,
+            threshold: this.throughputDropThreshold,
+            observedValue: drop,
+            evidence
+          });
+        }
+      }
+    }
+    return anomalies;
+  }
+  toIntentPatterns(anomalies, stats) {
+    const statsByOp = new Map(stats.map((item) => [this.operationKey(item.operation), item]));
+    return anomalies.map((anomaly) => {
+      const stat = statsByOp.get(this.operationKey(anomaly.operation));
+      const confidence = {
+        score: Math.min(1, (anomaly.observedValue ?? 0) / (anomaly.threshold ?? 1)),
+        sampleSize: stat?.totalCalls ?? 0,
+        pValue: undefined
+      };
+      return {
+        id: randomUUID(),
+        type: this.mapMetricToIntent(anomaly.metric),
+        description: anomaly.description,
+        operation: anomaly.operation,
+        confidence,
+        metadata: {
+          observedValue: anomaly.observedValue,
+          threshold: anomaly.threshold
+        },
+        evidence: anomaly.evidence
+      };
     });
-    return [record];
-  });
-}
-function buildWindowRange(windowDays) {
-  const windowEnd = new Date;
-  const windowStart = new Date(windowEnd.getTime() - windowDays * 24 * 60 * 60 * 1000);
-  return {
-    from: windowStart,
-    to: windowEnd
-  };
-}
-function asString(value) {
-  if (typeof value === "string" && value.trim())
-    return value;
-  if (typeof value === "number")
-    return String(value);
-  return null;
-}
-function asOptionalString(value) {
-  if (typeof value === "string")
-    return value;
-  if (typeof value === "number")
-    return String(value);
-  return null;
-}
-function asNumber(value) {
-  if (typeof value === "number" && Number.isFinite(value))
-    return value;
-  if (typeof value === "string" && value.trim()) {
-    const parsed = Number(value);
-    if (Number.isFinite(parsed))
-      return parsed;
   }
-  return 0;
-}
-function asBoolean(value) {
-  if (typeof value === "boolean")
-    return value;
-  if (typeof value === "number")
-    return value !== 0;
-  if (typeof value === "string")
-    return value.toLowerCase() === "true";
-  return false;
-}
-function asDate(value) {
-  if (value instanceof Date)
-    return value;
-  if (typeof value === "string" || typeof value === "number") {
-    const date = new Date(value);
-    if (!Number.isNaN(date.getTime()))
-      return date;
+  suggestOptimizations(stats, anomalies, lifecycleContext) {
+    const anomaliesByOp = new Map(this.groupByOperation(anomalies));
+    const hints = [];
+    for (const stat of stats) {
+      const opKey = this.operationKey(stat.operation);
+      const opAnomalies = anomaliesByOp.get(opKey) ?? [];
+      for (const anomaly of opAnomalies) {
+        if (anomaly.metric === "latency") {
+          hints.push(this.applyLifecycleContext({
+            operation: stat.operation,
+            category: "performance",
+            summary: "Latency regression detected",
+            justification: `P99 latency at ${stat.p99LatencyMs}ms`,
+            recommendedActions: [
+              "Add batching or caching layer",
+              "Replay golden tests to capture slow inputs"
+            ]
+          }, lifecycleContext?.stage));
+        } else if (anomaly.metric === "error-rate") {
+          const topError = Object.entries(stat.topErrors).sort((a, b) => b[1] - a[1])[0]?.[0];
+          hints.push(this.applyLifecycleContext({
+            operation: stat.operation,
+            category: "error-handling",
+            summary: "Error spike detected",
+            justification: topError ? `Dominant error code ${topError}` : "Increase in failures",
+            recommendedActions: [
+              "Generate regression spec from failing payloads",
+              "Add policy guardrails before rollout"
+            ]
+          }, lifecycleContext?.stage));
+        } else if (anomaly.metric === "throughput") {
+          hints.push(this.applyLifecycleContext({
+            operation: stat.operation,
+            category: "performance",
+            summary: "Throughput drop detected",
+            justification: "Significant traffic reduction relative to baseline",
+            recommendedActions: [
+              "Validate routing + feature flag bucketing",
+              "Backfill spec variant to rehydrate demand"
+            ]
+          }, lifecycleContext?.stage));
+        }
+      }
+    }
+    return hints;
   }
-  return null;
-}
-function toIsoString(value) {
-  if (!value)
-    return;
-  return typeof value === "string" ? value : value.toISOString();
-}
-function toDate(value) {
-  if (!value)
-    return null;
-  return value instanceof Date ? value : new Date(value);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
-// src/generator/spec-generator.ts
-import { randomUUID as randomUUID2 } from "crypto";
-
-class SpecGenerator {
-  config;
-  logger;
-  clock;
-  getSpec;
-  constructor(options = {}) {
-    this.config = options.config ?? {};
-    this.logger = options.logger;
-    this.clock = options.clock ?? (() => new Date);
-    this.getSpec = options.getSpec;
+  operationKey(op) {
+    const coordinate = "operation" in op ? op.operation : op;
+    return `${coordinate.key}.v${coordinate.version}${coordinate.tenantId ? `@${coordinate.tenantId}` : ""}`;
   }
-  generateFromIntent(intent, options = {}) {
-    const now = this.clock();
-    const summary = options.summary ?? `${this.intentToVerb(intent.type)} ${intent.operation?.key ?? "operation"}`;
-    const rationale = options.rationale ?? [
-      intent.description,
-      intent.metadata?.observedValue ? `Observed ${intent.metadata.observedValue}` : undefined
-    ].filter(Boolean).join(" \u2014 ");
-    const suggestion = {
-      id: randomUUID2(),
-      intent,
-      target: intent.operation,
-      proposal: {
-        summary,
-        rationale,
-        changeType: options.changeType ?? this.inferChangeType(intent),
-        kind: options.kind,
-        spec: options.spec,
-        diff: options.diff,
-        metadata: options.metadata
-      },
-      confidence: intent.confidence.score,
-      priority: this.intentToPriority(intent),
-      createdAt: now,
-      createdBy: options.createdBy ?? "auto-evolution",
-      status: options.status ?? "pending",
-      evidence: intent.evidence,
-      tags: options.tags
+  buildUsageStats(samples) {
+    const durations = samples.map((s) => s.durationMs).sort((a, b) => a - b);
+    const errors = samples.filter((s) => !s.success);
+    const totalCalls = samples.length;
+    const successRate = (totalCalls - errors.length) / totalCalls;
+    const errorRate = errors.length / totalCalls;
+    const averageLatencyMs = durations.reduce((sum, value) => sum + value, 0) / totalCalls;
+    const topErrors = errors.reduce((acc, sample) => {
+      if (!sample.errorCode)
+        return acc;
+      acc[sample.errorCode] = (acc[sample.errorCode] ?? 0) + 1;
+      return acc;
+    }, {});
+    const timestamps = samples.map((s) => s.timestamp.getTime());
+    const windowStart = new Date(Math.min(...timestamps));
+    const windowEnd = new Date(Math.max(...timestamps));
+    return {
+      operation: samples[0].operation,
+      totalCalls,
+      successRate,
+      errorRate,
+      averageLatencyMs,
+      p95LatencyMs: percentile(durations, 0.95),
+      p99LatencyMs: percentile(durations, 0.99),
+      maxLatencyMs: Math.max(...durations),
+      lastSeenAt: windowEnd,
+      windowStart,
+      windowEnd,
+      topErrors
+    };
+  }
+  toSeverity(ratio) {
+    if (ratio >= 2)
+      return "high";
+    if (ratio >= 1.3)
+      return "medium";
+    return "low";
+  }
+  mapMetricToIntent(metric) {
+    switch (metric) {
+      case "error-rate":
+        return "error-spike";
+      case "latency":
+        return "latency-regression";
+      case "throughput":
+        return "throughput-drop";
+      default:
+        return "schema-mismatch";
+    }
+  }
+  groupByOperation(items) {
+    const map = new Map;
+    for (const item of items) {
+      const key = this.operationKey(item.operation);
+      const arr = map.get(key) ?? [];
+      arr.push(item);
+      map.set(key, arr);
+    }
+    return map;
+  }
+  applyLifecycleContext(hint, stage) {
+    if (stage === undefined)
+      return hint;
+    const band = mapStageBand(stage);
+    const advice = LIFECYCLE_HINTS[band]?.[hint.category];
+    if (!advice) {
+      return { ...hint, lifecycleStage: stage };
+    }
+    return {
+      ...hint,
+      lifecycleStage: stage,
+      lifecycleNotes: advice.message,
+      recommendedActions: dedupeActions([
+        ...hint.recommendedActions,
+        ...advice.supplementalActions
+      ])
     };
-    return suggestion;
   }
-  generateVariant(operation, patch, intent, options = {}) {
-    if (!this.getSpec) {
-      throw new Error("SpecGenerator requires getSpec() to generate variants");
-    }
-    const base = this.getSpec(operation.key, operation.version);
-    if (!base) {
-      throw new Error(`Cannot generate variant; spec ${operation.key}.v${operation.version} not found`);
-    }
-    const merged = mergeContract(base, patch);
-    return this.generateFromIntent(intent, { ...options, spec: merged });
+}
+function percentile(values, p) {
+  if (!values.length)
+    return 0;
+  if (values.length === 1)
+    return values[0];
+  const idx = Math.min(values.length - 1, Math.floor(p * values.length));
+  return values[idx];
+}
+var mapStageBand = (stage) => {
+  if (stage <= 2)
+    return "early";
+  if (stage === LifecycleStage.ProductMarketFit)
+    return "pmf";
+  if (stage === LifecycleStage.GrowthScaleUp || stage === LifecycleStage.ExpansionPlatform) {
+    return "scale";
   }
-  validateSuggestion(suggestion, config = this.config) {
-    const reasons = [];
-    if (config.minConfidence != null && suggestion.confidence < config.minConfidence) {
-      reasons.push(`Confidence ${suggestion.confidence.toFixed(2)} below minimum ${config.minConfidence}`);
+  return "mature";
+};
+var LIFECYCLE_HINTS = {
+  early: {
+    performance: {
+      message: "Favor guardrails that protect learning velocity before heavy rewrites.",
+      supplementalActions: [
+        "Wrap risky changes behind progressive delivery flags"
+      ]
+    },
+    "error-handling": {
+      message: "Make failures loud and recoverable so you can learn faster.",
+      supplementalActions: ["Add auto-rollbacks or manual kill switches"]
     }
-    if (config.requireApproval && suggestion.status === "approved") {
-      reasons.push("Suggestion cannot be auto-approved when approval is required");
+  },
+  pmf: {
+    performance: {
+      message: "Stabilize the core use case to avoid regressions while demand grows.",
+      supplementalActions: ["Instrument regression tests on critical specs"]
     }
-    if (suggestion.proposal.spec && !suggestion.proposal.spec.meta?.key) {
-      reasons.push("Proposal spec must include meta.key");
+  },
+  scale: {
+    performance: {
+      message: "Prioritize resilience and multi-tenant safety as volumes expand.",
+      supplementalActions: [
+        "Introduce workload partitioning or isolation per tenant"
+      ]
+    },
+    "error-handling": {
+      message: "Contain blast radius with policy fallbacks and circuit breakers.",
+      supplementalActions: ["Add circuit breakers to high-risk operations"]
     }
-    if (!suggestion.proposal.summary) {
-      reasons.push("Proposal summary is required");
+  },
+  mature: {
+    performance: {
+      message: "Optimize for margins and predictable SLAs.",
+      supplementalActions: [
+        "Capture unit-cost impacts alongside latency fixes"
+      ]
+    },
+    "error-handling": {
+      message: "Prevent regressions with automated regression specs before deploy.",
+      supplementalActions: [
+        "Run auto-evolution simulations on renewal scenarios"
+      ]
     }
-    const ok = reasons.length === 0;
-    if (!ok) {
-      this.logger?.warn("SpecGenerator.validateSuggestion.failed", {
-        suggestionId: suggestion.id,
-        reasons
+  }
+};
+var dedupeActions = (actions) => {
+  const seen = new Set;
+  const ordered = [];
+  for (const action of actions) {
+    if (seen.has(action))
+      continue;
+    seen.add(action);
+    ordered.push(action);
+  }
+  return ordered;
+};
+// src/approval/integration.ts
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+
+class SpecSuggestionOrchestrator {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async submit(suggestion, session, approvalReason) {
+    await this.options.repository.create(suggestion);
+    if (session && this.options.approval) {
+      await this.options.approval.requestApproval({
+        sessionId: session.sessionId,
+        agentId: session.agentId,
+        tenantId: session.tenantId,
+        toolName: "evolution_apply_suggestion",
+        toolCallId: suggestion.id,
+        toolArgs: { suggestionId: suggestion.id },
+        reason: approvalReason ?? suggestion.proposal.summary,
+        payload: { suggestionId: suggestion.id }
       });
     }
-    return { ok, reasons };
+    return suggestion;
   }
-  intentToVerb(intent) {
-    switch (intent) {
-      case "error-spike":
-        return "Stabilize";
-      case "latency-regression":
-        return "Optimize";
-      case "missing-operation":
-        return "Introduce";
-      case "throughput-drop":
-        return "Rebalance";
-      default:
-        return "Adjust";
+  async approve(id, reviewer, notes) {
+    const suggestion = await this.ensureSuggestion(id);
+    await this.options.repository.updateStatus(id, "approved", {
+      reviewer,
+      notes,
+      decidedAt: new Date
+    });
+    if (this.options.writer) {
+      await this.options.writer.write({
+        ...suggestion,
+        status: "approved",
+        approvals: {
+          reviewer,
+          notes,
+          decidedAt: new Date,
+          status: "approved"
+        }
+      });
     }
   }
-  intentToPriority(intent) {
-    const severity = intent.confidence.score;
-    if (intent.type === "error-spike" || severity >= 0.8)
-      return "high";
-    if (severity >= 0.5)
-      return "medium";
-    return "low";
+  async reject(id, reviewer, notes) {
+    await this.options.repository.updateStatus(id, "rejected", {
+      reviewer,
+      notes,
+      decidedAt: new Date
+    });
   }
-  inferChangeType(intent) {
-    switch (intent.type) {
-      case "missing-operation":
-        return "new-spec";
-      case "schema-mismatch":
-        return "schema-update";
-      case "error-spike":
-        return "policy-update";
-      default:
-        return "revision";
-    }
+  list(filters) {
+    return this.options.repository.list(filters);
+  }
+  async ensureSuggestion(id) {
+    const suggestion = await this.options.repository.getById(id);
+    if (!suggestion)
+      throw new Error(`Spec suggestion ${id} not found`);
+    return suggestion;
   }
 }
-function mergeContract(base, patch) {
-  return {
-    ...base,
-    ...patch,
-    meta: { ...base.meta, ...patch.meta },
-    io: {
-      ...base.io,
-      ...patch.io
-    },
-    policy: {
-      ...base.policy,
-      ...patch.policy
-    },
-    telemetry: {
-      ...base.telemetry,
-      ...patch.telemetry
+
+class FileSystemSuggestionWriter {
+  outputDir;
+  filenameTemplate;
+  constructor(options = {}) {
+    this.outputDir = options.outputDir ?? join(process.cwd(), "packages/libs/contracts-spec/src/generated");
+    this.filenameTemplate = options.filenameTemplate ?? ((suggestion) => `${suggestion.target?.key ?? suggestion.intent.id}.v${suggestion.target?.version ?? "next"}.suggestion.json`);
+  }
+  async write(suggestion) {
+    await mkdir(this.outputDir, { recursive: true });
+    const filename = this.filenameTemplate(suggestion);
+    const filepath = join(this.outputDir, filename);
+    const payload = serializeSuggestion(suggestion);
+    await writeFile(filepath, JSON.stringify(payload, null, 2));
+    return filepath;
+  }
+}
+
+class InMemorySpecSuggestionRepository {
+  items = new Map;
+  async create(suggestion) {
+    this.items.set(suggestion.id, suggestion);
+  }
+  async getById(id) {
+    return this.items.get(id);
+  }
+  async updateStatus(id, status, metadata) {
+    const suggestion = await this.getById(id);
+    if (!suggestion)
+      return;
+    this.items.set(id, {
+      ...suggestion,
+      status,
+      approvals: {
+        reviewer: metadata?.reviewer,
+        notes: metadata?.notes,
+        decidedAt: metadata?.decidedAt,
+        status
+      }
+    });
+  }
+  async list(filters) {
+    const values = [...this.items.values()];
+    if (!filters)
+      return values;
+    return values.filter((item) => {
+      if (filters.status && item.status !== filters.status)
+        return false;
+      if (filters.operationKey && item.target?.key !== filters.operationKey)
+        return false;
+      return true;
+    });
+  }
+}
+function serializeSuggestion(suggestion) {
+  const { proposal, ...rest } = suggestion;
+  const { spec, ...proposalRest } = proposal;
+  return {
+    ...rest,
+    proposal: {
+      ...proposalRest,
+      specMeta: spec?.meta
     },
-    sideEffects: {
-      ...base.sideEffects,
-      ...patch.sideEffects
+    createdAt: suggestion.createdAt.toISOString(),
+    intent: {
+      ...suggestion.intent,
+      confidence: { ...suggestion.intent.confidence },
+      evidence: suggestion.intent.evidence
     }
   };
 }
 // src/generator/ai-spec-generator.ts
+import { randomUUID as randomUUID2 } from "crypto";
 import { generateText, Output } from "ai";
 import * as z from "zod";
-import { randomUUID as randomUUID3 } from "crypto";
 var SpecSuggestionProposalSchema = z.object({
   summary: z.string().describe("Brief summary of the proposed change"),
   rationale: z.string().describe("Detailed explanation of why this change is needed"),
@@ -906,7 +903,7 @@ Please provide an improved version with more specific recommendations.`;
       }
     };
     return {
-      id: randomUUID3(),
+      id: randomUUID2(),
       intent,
       target: intent.operation,
       proposal,
@@ -940,136 +937,139 @@ Please provide an improved version with more specific recommendations.`;
 function createAISpecGenerator(config) {
   return new AISpecGenerator(config);
 }
-// src/approval/integration.ts
-import { mkdir, writeFile } from "fs/promises";
-import { join } from "path";
+// src/generator/spec-generator.ts
+import { randomUUID as randomUUID3 } from "crypto";
 
-class SpecSuggestionOrchestrator {
-  options;
-  constructor(options) {
-    this.options = options;
+class SpecGenerator {
+  config;
+  logger;
+  clock;
+  getSpec;
+  constructor(options = {}) {
+    this.config = options.config ?? {};
+    this.logger = options.logger;
+    this.clock = options.clock ?? (() => new Date);
+    this.getSpec = options.getSpec;
   }
-  async submit(suggestion, session, approvalReason) {
-    await this.options.repository.create(suggestion);
-    if (session && this.options.approval) {
-      await this.options.approval.requestApproval({
-        sessionId: session.sessionId,
-        agentId: session.agentId,
-        tenantId: session.tenantId,
-        toolName: "evolution_apply_suggestion",
-        toolCallId: suggestion.id,
-        toolArgs: { suggestionId: suggestion.id },
-        reason: approvalReason ?? suggestion.proposal.summary,
-        payload: { suggestionId: suggestion.id }
-      });
-    }
+  generateFromIntent(intent, options = {}) {
+    const now = this.clock();
+    const summary = options.summary ?? `${this.intentToVerb(intent.type)} ${intent.operation?.key ?? "operation"}`;
+    const rationale = options.rationale ?? [
+      intent.description,
+      intent.metadata?.observedValue ? `Observed ${intent.metadata.observedValue}` : undefined
+    ].filter(Boolean).join(" \u2014 ");
+    const suggestion = {
+      id: randomUUID3(),
+      intent,
+      target: intent.operation,
+      proposal: {
+        summary,
+        rationale,
+        changeType: options.changeType ?? this.inferChangeType(intent),
+        kind: options.kind,
+        spec: options.spec,
+        diff: options.diff,
+        metadata: options.metadata
+      },
+      confidence: intent.confidence.score,
+      priority: this.intentToPriority(intent),
+      createdAt: now,
+      createdBy: options.createdBy ?? "auto-evolution",
+      status: options.status ?? "pending",
+      evidence: intent.evidence,
+      tags: options.tags
+    };
     return suggestion;
   }
-  async approve(id, reviewer, notes) {
-    const suggestion = await this.ensureSuggestion(id);
-    await this.options.repository.updateStatus(id, "approved", {
-      reviewer,
-      notes,
-      decidedAt: new Date
-    });
-    if (this.options.writer) {
-      await this.options.writer.write({
-        ...suggestion,
-        status: "approved",
-        approvals: {
-          reviewer,
-          notes,
-          decidedAt: new Date,
-          status: "approved"
-        }
-      });
+  generateVariant(operation, patch, intent, options = {}) {
+    if (!this.getSpec) {
+      throw new Error("SpecGenerator requires getSpec() to generate variants");
     }
+    const base = this.getSpec(operation.key, operation.version);
+    if (!base) {
+      throw new Error(`Cannot generate variant; spec ${operation.key}.v${operation.version} not found`);
+    }
+    const merged = mergeContract(base, patch);
+    return this.generateFromIntent(intent, { ...options, spec: merged });
   }
-  async reject(id, reviewer, notes) {
-    await this.options.repository.updateStatus(id, "rejected", {
-      reviewer,
-      notes,
-      decidedAt: new Date
-    });
-  }
-  list(filters) {
-    return this.options.repository.list(filters);
-  }
-  async ensureSuggestion(id) {
-    const suggestion = await this.options.repository.getById(id);
-    if (!suggestion)
-      throw new Error(`Spec suggestion ${id} not found`);
-    return suggestion;
-  }
-}
-
-class FileSystemSuggestionWriter {
-  outputDir;
-  filenameTemplate;
-  constructor(options = {}) {
-    this.outputDir = options.outputDir ?? join(process.cwd(), "packages/libs/contracts-spec/src/generated");
-    this.filenameTemplate = options.filenameTemplate ?? ((suggestion) => `${suggestion.target?.key ?? suggestion.intent.id}.v${suggestion.target?.version ?? "next"}.suggestion.json`);
-  }
-  async write(suggestion) {
-    await mkdir(this.outputDir, { recursive: true });
-    const filename = this.filenameTemplate(suggestion);
-    const filepath = join(this.outputDir, filename);
-    const payload = serializeSuggestion(suggestion);
-    await writeFile(filepath, JSON.stringify(payload, null, 2));
-    return filepath;
-  }
-}
-
-class InMemorySpecSuggestionRepository {
-  items = new Map;
-  async create(suggestion) {
-    this.items.set(suggestion.id, suggestion);
+  validateSuggestion(suggestion, config = this.config) {
+    const reasons = [];
+    if (config.minConfidence != null && suggestion.confidence < config.minConfidence) {
+      reasons.push(`Confidence ${suggestion.confidence.toFixed(2)} below minimum ${config.minConfidence}`);
+    }
+    if (config.requireApproval && suggestion.status === "approved") {
+      reasons.push("Suggestion cannot be auto-approved when approval is required");
+    }
+    if (suggestion.proposal.spec && !suggestion.proposal.spec.meta?.key) {
+      reasons.push("Proposal spec must include meta.key");
+    }
+    if (!suggestion.proposal.summary) {
+      reasons.push("Proposal summary is required");
+    }
+    const ok = reasons.length === 0;
+    if (!ok) {
+      this.logger?.warn("SpecGenerator.validateSuggestion.failed", {
+        suggestionId: suggestion.id,
+        reasons
+      });
+    }
+    return { ok, reasons };
   }
-  async getById(id) {
-    return this.items.get(id);
+  intentToVerb(intent) {
+    switch (intent) {
+      case "error-spike":
+        return "Stabilize";
+      case "latency-regression":
+        return "Optimize";
+      case "missing-operation":
+        return "Introduce";
+      case "throughput-drop":
+        return "Rebalance";
+      default:
+        return "Adjust";
+    }
   }
-  async updateStatus(id, status, metadata) {
-    const suggestion = await this.getById(id);
-    if (!suggestion)
-      return;
-    this.items.set(id, {
-      ...suggestion,
-      status,
-      approvals: {
-        reviewer: metadata?.reviewer,
-        notes: metadata?.notes,
-        decidedAt: metadata?.decidedAt,
-        status
-      }
-    });
+  intentToPriority(intent) {
+    const severity = intent.confidence.score;
+    if (intent.type === "error-spike" || severity >= 0.8)
+      return "high";
+    if (severity >= 0.5)
+      return "medium";
+    return "low";
   }
-  async list(filters) {
-    const values = [...this.items.values()];
-    if (!filters)
-      return values;
-    return values.filter((item) => {
-      if (filters.status && item.status !== filters.status)
-        return false;
-      if (filters.operationKey && item.target?.key !== filters.operationKey)
-        return false;
-      return true;
-    });
+  inferChangeType(intent) {
+    switch (intent.type) {
+      case "missing-operation":
+        return "new-spec";
+      case "schema-mismatch":
+        return "schema-update";
+      case "error-spike":
+        return "policy-update";
+      default:
+        return "revision";
+    }
   }
 }
-function serializeSuggestion(suggestion) {
-  const { proposal, ...rest } = suggestion;
-  const { spec, ...proposalRest } = proposal;
+function mergeContract(base, patch) {
   return {
-    ...rest,
-    proposal: {
-      ...proposalRest,
-      specMeta: spec?.meta
+    ...base,
+    ...patch,
+    meta: { ...base.meta, ...patch.meta },
+    io: {
+      ...base.io,
+      ...patch.io
     },
-    createdAt: suggestion.createdAt.toISOString(),
-    intent: {
-      ...suggestion.intent,
-      confidence: { ...suggestion.intent.confidence },
-      evidence: suggestion.intent.evidence
+    policy: {
+      ...base.policy,
+      ...patch.policy
+    },
+    telemetry: {
+      ...base.telemetry,
+      ...patch.telemetry
+    },
+    sideEffects: {
+      ...base.sideEffects,
+      ...patch.sideEffects
     }
   };
 }