@contractspec/lib.evolution 1.57.0 → 1.58.0

package/dist/node/index.js

@@ -0,0 +1,1068 @@
+// src/analyzer/spec-analyzer.ts
+import { randomUUID } from "node: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 [];
+    }
+    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));
+  }
+  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
+      };
+    });
+  }
+  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;
+  }
+  operationKey(op) {
+    const coordinate = "operation" in op ? op.operation : op;
+    return `${coordinate.key}.v${coordinate.version}${coordinate.tenantId ? `@${coordinate.tenantId}` : ""}`;
+  }
+  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
+      ])
+    };
+  }
+}
+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";
+  }
+  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 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}");
+  }
+  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;
+    }
+  });
+  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 `(${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 [
+      {
+        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 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;
+  }
+  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 "node: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;
+  }
+  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(" — ");
+    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
+    };
+    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 });
+  }
+  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 };
+  }
+  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";
+    }
+  }
+  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";
+  }
+  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 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
+    },
+    sideEffects: {
+      ...base.sideEffects,
+      ...patch.sideEffects
+    }
+  };
+}
+// src/generator/ai-spec-generator.ts
+import { generateText, Output } from "ai";
+import * as z from "zod";
+import { randomUUID as randomUUID3 } from "node: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"),
+  changeType: z.enum(["new-spec", "revision", "policy-update", "schema-update"]).describe("Type of change being proposed"),
+  recommendedActions: z.array(z.string()).describe("List of specific actions to implement the change"),
+  estimatedImpact: z.enum(["low", "medium", "high"]).describe("Estimated impact of implementing this change"),
+  riskLevel: z.enum(["low", "medium", "high"]).describe("Risk level associated with this change"),
+  diff: z.string().optional().describe("Optional diff or code snippet showing the change")
+});
+
+class AISpecGenerator {
+  model;
+  config;
+  systemPrompt;
+  constructor(options) {
+    this.model = options.model;
+    this.config = options.evolutionConfig ?? {};
+    this.systemPrompt = options.systemPrompt ?? `You are a ContractSpec evolution expert. Your role is to analyze telemetry data, anomalies, and usage patterns to suggest improvements to API contracts and specifications.
+
+When generating suggestions:
+1. Be specific and actionable
+2. Consider backwards compatibility
+3. Prioritize stability and reliability
+4. Explain the rationale clearly
+5. Estimate impact and risk accurately`;
+  }
+  async generateFromIntent(intent, options = {}) {
+    const prompt = this.buildPrompt(intent, options);
+    const { output } = await generateText({
+      model: this.model,
+      system: this.systemPrompt,
+      prompt,
+      output: Output.object({
+        schema: SpecSuggestionProposalSchema
+      })
+    });
+    return this.buildSuggestion(intent, output);
+  }
+  async generateBatch(intents, options = {}) {
+    const maxConcurrent = options.maxConcurrent ?? 3;
+    const results = [];
+    for (let i = 0;i < intents.length; i += maxConcurrent) {
+      const batch = intents.slice(i, i + maxConcurrent);
+      const batchResults = await Promise.all(batch.map((intent) => this.generateFromIntent(intent)));
+      results.push(...batchResults);
+    }
+    return results;
+  }
+  async enhanceSuggestion(suggestion) {
+    const prompt = `Review and enhance this spec suggestion:
+
+Intent: ${suggestion.intent.type} - ${suggestion.intent.description}
+Current Summary: ${suggestion.proposal.summary}
+Current Rationale: ${suggestion.proposal.rationale}
+
+Evidence:
+${suggestion.evidence.map((e) => `- ${e.type}: ${e.description}`).join(`
+`)}
+
+Please provide an improved version with more specific recommendations.`;
+    const { output } = await generateText({
+      model: this.model,
+      system: this.systemPrompt,
+      prompt,
+      output: Output.object({
+        schema: SpecSuggestionProposalSchema
+      })
+    });
+    return {
+      ...suggestion,
+      proposal: {
+        ...suggestion.proposal,
+        summary: output.summary,
+        rationale: output.rationale,
+        changeType: output.changeType,
+        diff: output.diff,
+        metadata: {
+          ...suggestion.proposal.metadata,
+          aiEnhanced: true,
+          recommendedActions: output.recommendedActions,
+          estimatedImpact: output.estimatedImpact,
+          riskLevel: output.riskLevel
+        }
+      }
+    };
+  }
+  buildPrompt(intent, options) {
+    const parts = [
+      `Analyze this intent pattern and generate a spec suggestion:`,
+      ``,
+      `Intent Type: ${intent.type}`,
+      `Description: ${intent.description}`,
+      `Confidence: ${(intent.confidence.score * 100).toFixed(0)}% (sample size: ${intent.confidence.sampleSize})`
+    ];
+    if (intent.operation) {
+      parts.push(`Operation: ${intent.operation.key} v${intent.operation.version}`);
+    }
+    if (intent.evidence.length > 0) {
+      parts.push(``, `Evidence:`);
+      for (const evidence of intent.evidence) {
+        parts.push(`- [${evidence.type}] ${evidence.description}`);
+      }
+    }
+    if (intent.metadata) {
+      parts.push(``, `Metadata: ${JSON.stringify(intent.metadata, null, 2)}`);
+    }
+    if (options.existingSpec) {
+      parts.push(``, `Existing Spec:`, "```json", JSON.stringify(options.existingSpec, null, 2), "```");
+    }
+    if (options.additionalContext) {
+      parts.push(``, `Additional Context:`, options.additionalContext);
+    }
+    return parts.join(`
+`);
+  }
+  buildSuggestion(intent, aiOutput) {
+    const now = new Date;
+    const proposal = {
+      summary: aiOutput.summary,
+      rationale: aiOutput.rationale,
+      changeType: aiOutput.changeType,
+      diff: aiOutput.diff,
+      metadata: {
+        aiGenerated: true,
+        recommendedActions: aiOutput.recommendedActions,
+        estimatedImpact: aiOutput.estimatedImpact,
+        riskLevel: aiOutput.riskLevel
+      }
+    };
+    return {
+      id: randomUUID3(),
+      intent,
+      target: intent.operation,
+      proposal,
+      confidence: intent.confidence.score,
+      priority: this.calculatePriority(intent, aiOutput),
+      createdAt: now,
+      createdBy: "ai-spec-generator",
+      status: this.determineInitialStatus(intent),
+      evidence: intent.evidence,
+      tags: ["ai-generated", intent.type]
+    };
+  }
+  calculatePriority(intent, aiOutput) {
+    const impactScore = aiOutput.estimatedImpact === "high" ? 1 : aiOutput.estimatedImpact === "medium" ? 0.5 : 0.25;
+    const intentScore = intent.confidence.score;
+    const urgency = intent.type === "error-spike" ? 0.3 : intent.type === "latency-regression" ? 0.2 : 0;
+    const combined = impactScore * 0.4 + intentScore * 0.4 + urgency;
+    if (combined >= 0.7)
+      return "high";
+    if (combined >= 0.4)
+      return "medium";
+    return "low";
+  }
+  determineInitialStatus(intent) {
+    if (this.config.autoApproveThreshold && intent.confidence.score >= this.config.autoApproveThreshold && !this.config.requireApproval) {
+      return "approved";
+    }
+    return "pending";
+  }
+}
+function createAISpecGenerator(config) {
+  return new AISpecGenerator(config);
+}
+// src/approval/integration.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node: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 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"
+        }
+      });
+    }
+  }
+  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/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
+    },
+    createdAt: suggestion.createdAt.toISOString(),
+    intent: {
+      ...suggestion.intent,
+      confidence: { ...suggestion.intent.confidence },
+      evidence: suggestion.intent.evidence
+    }
+  };
+}
+export {
+  createAISpecGenerator,
+  SpecSuggestionOrchestrator,
+  SpecGenerator,
+  SpecAnalyzer,
+  PosthogTelemetryReader,
+  InMemorySpecSuggestionRepository,
+  FileSystemSuggestionWriter,
+  AISpecGenerator
+};