@lssm/lib.evolution 0.0.0-canary-20251217054315 → 0.0.0-canary-20251217060433

package/dist/analyzer/spec-analyzer.d.ts

@@ -0,0 +1,34 @@
+import { IntentPattern, OperationMetricSample, OptimizationHint, SpecAnomaly, SpecUsageStats } from "../types.js";
+import { Logger } from "@lssm/lib.observability";
+import { LifecycleStage } from "@lssm/lib.lifecycle";
+
+//#region src/analyzer/spec-analyzer.d.ts
+interface SpecAnalyzerOptions {
+  logger?: Logger;
+  minSampleSize?: number;
+  errorRateThreshold?: number;
+  latencyP99ThresholdMs?: number;
+  throughputDropThreshold?: number;
+}
+declare class SpecAnalyzer {
+  private readonly logger?;
+  private readonly minSampleSize;
+  private readonly errorRateThreshold;
+  private readonly latencyP99ThresholdMs;
+  private readonly throughputDropThreshold;
+  constructor(options?: SpecAnalyzerOptions);
+  analyzeSpecUsage(samples: OperationMetricSample[]): SpecUsageStats[];
+  detectAnomalies(stats: SpecUsageStats[], baseline?: SpecUsageStats[]): SpecAnomaly[];
+  toIntentPatterns(anomalies: SpecAnomaly[], stats: SpecUsageStats[]): IntentPattern[];
+  suggestOptimizations(stats: SpecUsageStats[], anomalies: SpecAnomaly[], lifecycleContext?: {
+    stage: LifecycleStage;
+  }): OptimizationHint[];
+  private operationKey;
+  private buildUsageStats;
+  private toSeverity;
+  private mapMetricToIntent;
+  private groupByOperation;
+  private applyLifecycleContext;
+}
+//#endregion
+export { SpecAnalyzer, SpecAnalyzerOptions };

package/dist/analyzer/spec-analyzer.js

@@ -1 +1 @@
-import"@lssm/lib.observability";import{randomUUID as e}from"node:crypto";import{LifecycleStage as t}from"@lssm/lib.lifecycle";const n={minSampleSize:50,errorRateThreshold:.05,latencyP99ThresholdMs:750};var r=class{logger;minSampleSize;errorRateThreshold;latencyP99ThresholdMs;throughputDropThreshold;constructor(e={}){this.logger=e.logger,this.minSampleSize=e.minSampleSize??n.minSampleSize,this.errorRateThreshold=e.errorRateThreshold??n.errorRateThreshold,this.latencyP99ThresholdMs=e.latencyP99ThresholdMs??n.latencyP99ThresholdMs,this.throughputDropThreshold=e.throughputDropThreshold??.2}analyzeSpecUsage(e){if(!e.length)return this.logger?.debug(`SpecAnalyzer.analyzeSpecUsage.skip`,{reason:`no-samples`}),[];let t=new Map;for(let n of e){let e=this.operationKey(n),r=t.get(e)??[];r.push(n),t.set(e,r)}return[...t.values()].filter(e=>{let t=e.length>=this.minSampleSize;return t||this.logger?.debug(`SpecAnalyzer.analyzeSpecUsage.skipOperation`,{operation:this.operationKey(e[0]),sampleSize:e.length,minSampleSize:this.minSampleSize}),t}).map(e=>this.buildUsageStats(e))}detectAnomalies(e,t){let n=[];if(!e.length)return this.logger?.debug(`SpecAnalyzer.detectAnomalies.skip`,{reason:`no-stats`}),n;let r=new Map((t??[]).map(e=>[this.operationKey(e.operation),e]));for(let t of e){let e=[];if(t.errorRate>=this.errorRateThreshold){e.push({type:`telemetry`,description:`Error rate ${t.errorRate.toFixed(2)} exceeded threshold ${this.errorRateThreshold}`,data:{errorRate:t.errorRate}}),n.push({operation:t.operation,severity:this.toSeverity(t.errorRate/this.errorRateThreshold),metric:`error-rate`,description:`Error rate spike`,detectedAt:new Date,threshold:this.errorRateThreshold,observedValue:t.errorRate,evidence:e});continue}if(t.p99LatencyMs>=this.latencyP99ThresholdMs){e.push({type:`telemetry`,description:`P99 latency ${t.p99LatencyMs}ms exceeded threshold ${this.latencyP99ThresholdMs}ms`,data:{p99LatencyMs:t.p99LatencyMs}}),n.push({operation:t.operation,severity:this.toSeverity(t.p99LatencyMs/this.latencyP99ThresholdMs),metric:`latency`,description:`Latency regression detected`,detectedAt:new Date,threshold:this.latencyP99ThresholdMs,observedValue:t.p99LatencyMs,evidence:e});continue}let i=r.get(this.operationKey(t.operation));if(i){let r=(i.totalCalls-t.totalCalls)/i.totalCalls;r>=this.throughputDropThreshold&&(e.push({type:`telemetry`,description:`Throughput dropped by ${(r*100).toFixed(1)}% compared to baseline`,data:{baselineCalls:i.totalCalls,currentCalls:t.totalCalls}}),n.push({operation:t.operation,severity:this.toSeverity(r/this.throughputDropThreshold),metric:`throughput`,description:`Usage drop detected`,detectedAt:new Date,threshold:this.throughputDropThreshold,observedValue:r,evidence:e}))}}return n}toIntentPatterns(t,n){let r=new Map(n.map(e=>[this.operationKey(e.operation),e]));return t.map(t=>{let n=r.get(this.operationKey(t.operation)),i={score:Math.min(1,(t.observedValue??0)/(t.threshold??1)),sampleSize:n?.totalCalls??0,pValue:void 0};return{id:e(),type:this.mapMetricToIntent(t.metric),description:t.description,operation:t.operation,confidence:i,metadata:{observedValue:t.observedValue,threshold:t.threshold},evidence:t.evidence}})}suggestOptimizations(e,t,n){let r=new Map(this.groupByOperation(t)),i=[];for(let t of e){let e=this.operationKey(t.operation),a=r.get(e)??[];for(let e of a)if(e.metric===`latency`)i.push(this.applyLifecycleContext({operation:t.operation,category:`performance`,summary:`Latency regression detected`,justification:`P99 latency at ${t.p99LatencyMs}ms`,recommendedActions:[`Add batching or caching layer`,`Replay golden tests to capture slow inputs`]},n?.stage));else if(e.metric===`error-rate`){let e=Object.entries(t.topErrors).sort((e,t)=>t[1]-e[1])[0]?.[0];i.push(this.applyLifecycleContext({operation:t.operation,category:`error-handling`,summary:`Error spike detected`,justification:e?`Dominant error code ${e}`:`Increase in failures`,recommendedActions:[`Generate regression spec from failing payloads`,`Add policy guardrails before rollout`]},n?.stage))}else e.metric===`throughput`&&i.push(this.applyLifecycleContext({operation:t.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`]},n?.stage))}return i}operationKey(e){let t=`operation`in e?e.operation:e;return`${t.name}.v${t.version}${t.tenantId?`@${t.tenantId}`:``}`}buildUsageStats(e){let t=e.map(e=>e.durationMs).sort((e,t)=>e-t),n=e.filter(e=>!e.success),r=e.length,a=(r-n.length)/r,o=n.length/r,s=t.reduce((e,t)=>e+t,0)/r,c=n.reduce((e,t)=>(t.errorCode&&(e[t.errorCode]=(e[t.errorCode]??0)+1),e),{}),l=e.map(e=>e.timestamp.getTime()),u=new Date(Math.min(...l)),d=new Date(Math.max(...l));return{operation:e[0].operation,totalCalls:r,successRate:a,errorRate:o,averageLatencyMs:s,p95LatencyMs:i(t,.95),p99LatencyMs:i(t,.99),maxLatencyMs:Math.max(...t),lastSeenAt:d,windowStart:u,windowEnd:d,topErrors:c}}toSeverity(e){return e>=2?`high`:e>=1.3?`medium`:`low`}mapMetricToIntent(e){switch(e){case`error-rate`:return`error-spike`;case`latency`:return`latency-regression`;case`throughput`:return`throughput-drop`;default:return`schema-mismatch`}}groupByOperation(e){let t=new Map;for(let n of e){let e=this.operationKey(n.operation),r=t.get(e)??[];r.push(n),t.set(e,r)}return t}applyLifecycleContext(e,t){if(t===void 0)return e;let n=o[a(t)]?.[e.category];return n?{...e,lifecycleStage:t,lifecycleNotes:n.message,recommendedActions:s([...e.recommendedActions,...n.supplementalActions])}:{...e,lifecycleStage:t}}};function i(e,t){return e.length?e.length===1?e[0]:e[Math.min(e.length-1,Math.floor(t*e.length))]:0}const a=e=>e<=2?`early`:e===t.ProductMarketFit?`pmf`:e===t.GrowthScaleUp||e===t.ExpansionPlatform?`scale`:`mature`,o={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`]}}},s=e=>{let t=new Set,n=[];for(let r of e)t.has(r)||(t.add(r),n.push(r));return n};export{r as SpecAnalyzer};
+import{Logger as e}from"@lssm/lib.observability";import{randomUUID as t}from"node:crypto";import{LifecycleStage as n}from"@lssm/lib.lifecycle";const r={minSampleSize:50,errorRateThreshold:.05,latencyP99ThresholdMs:750};var i=class{logger;minSampleSize;errorRateThreshold;latencyP99ThresholdMs;throughputDropThreshold;constructor(e={}){this.logger=e.logger,this.minSampleSize=e.minSampleSize??r.minSampleSize,this.errorRateThreshold=e.errorRateThreshold??r.errorRateThreshold,this.latencyP99ThresholdMs=e.latencyP99ThresholdMs??r.latencyP99ThresholdMs,this.throughputDropThreshold=e.throughputDropThreshold??.2}analyzeSpecUsage(e){if(!e.length)return this.logger?.debug(`SpecAnalyzer.analyzeSpecUsage.skip`,{reason:`no-samples`}),[];let t=new Map;for(let n of e){let e=this.operationKey(n),r=t.get(e)??[];r.push(n),t.set(e,r)}return[...t.values()].filter(e=>{let t=e.length>=this.minSampleSize;return t||this.logger?.debug(`SpecAnalyzer.analyzeSpecUsage.skipOperation`,{operation:this.operationKey(e[0]),sampleSize:e.length,minSampleSize:this.minSampleSize}),t}).map(e=>this.buildUsageStats(e))}detectAnomalies(e,t){let n=[];if(!e.length)return this.logger?.debug(`SpecAnalyzer.detectAnomalies.skip`,{reason:`no-stats`}),n;let r=new Map((t??[]).map(e=>[this.operationKey(e.operation),e]));for(let t of e){let e=[];if(t.errorRate>=this.errorRateThreshold){e.push({type:`telemetry`,description:`Error rate ${t.errorRate.toFixed(2)} exceeded threshold ${this.errorRateThreshold}`,data:{errorRate:t.errorRate}}),n.push({operation:t.operation,severity:this.toSeverity(t.errorRate/this.errorRateThreshold),metric:`error-rate`,description:`Error rate spike`,detectedAt:new Date,threshold:this.errorRateThreshold,observedValue:t.errorRate,evidence:e});continue}if(t.p99LatencyMs>=this.latencyP99ThresholdMs){e.push({type:`telemetry`,description:`P99 latency ${t.p99LatencyMs}ms exceeded threshold ${this.latencyP99ThresholdMs}ms`,data:{p99LatencyMs:t.p99LatencyMs}}),n.push({operation:t.operation,severity:this.toSeverity(t.p99LatencyMs/this.latencyP99ThresholdMs),metric:`latency`,description:`Latency regression detected`,detectedAt:new Date,threshold:this.latencyP99ThresholdMs,observedValue:t.p99LatencyMs,evidence:e});continue}let i=r.get(this.operationKey(t.operation));if(i){let r=(i.totalCalls-t.totalCalls)/i.totalCalls;r>=this.throughputDropThreshold&&(e.push({type:`telemetry`,description:`Throughput dropped by ${(r*100).toFixed(1)}% compared to baseline`,data:{baselineCalls:i.totalCalls,currentCalls:t.totalCalls}}),n.push({operation:t.operation,severity:this.toSeverity(r/this.throughputDropThreshold),metric:`throughput`,description:`Usage drop detected`,detectedAt:new Date,threshold:this.throughputDropThreshold,observedValue:r,evidence:e}))}}return n}toIntentPatterns(e,n){let r=new Map(n.map(e=>[this.operationKey(e.operation),e]));return e.map(e=>{let n=r.get(this.operationKey(e.operation)),i={score:Math.min(1,(e.observedValue??0)/(e.threshold??1)),sampleSize:n?.totalCalls??0,pValue:void 0};return{id:t(),type:this.mapMetricToIntent(e.metric),description:e.description,operation:e.operation,confidence:i,metadata:{observedValue:e.observedValue,threshold:e.threshold},evidence:e.evidence}})}suggestOptimizations(e,t,n){let r=new Map(this.groupByOperation(t)),i=[];for(let t of e){let e=this.operationKey(t.operation),a=r.get(e)??[];for(let e of a)if(e.metric===`latency`)i.push(this.applyLifecycleContext({operation:t.operation,category:`performance`,summary:`Latency regression detected`,justification:`P99 latency at ${t.p99LatencyMs}ms`,recommendedActions:[`Add batching or caching layer`,`Replay golden tests to capture slow inputs`]},n?.stage));else if(e.metric===`error-rate`){let e=Object.entries(t.topErrors).sort((e,t)=>t[1]-e[1])[0]?.[0];i.push(this.applyLifecycleContext({operation:t.operation,category:`error-handling`,summary:`Error spike detected`,justification:e?`Dominant error code ${e}`:`Increase in failures`,recommendedActions:[`Generate regression spec from failing payloads`,`Add policy guardrails before rollout`]},n?.stage))}else e.metric===`throughput`&&i.push(this.applyLifecycleContext({operation:t.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`]},n?.stage))}return i}operationKey(e){let t=`operation`in e?e.operation:e;return`${t.name}.v${t.version}${t.tenantId?`@${t.tenantId}`:``}`}buildUsageStats(e){let t=e.map(e=>e.durationMs).sort((e,t)=>e-t),n=e.filter(e=>!e.success),r=e.length,i=(r-n.length)/r,o=n.length/r,s=t.reduce((e,t)=>e+t,0)/r,c=n.reduce((e,t)=>(t.errorCode&&(e[t.errorCode]=(e[t.errorCode]??0)+1),e),{}),l=e.map(e=>e.timestamp.getTime()),u=new Date(Math.min(...l)),d=new Date(Math.max(...l));return{operation:e[0].operation,totalCalls:r,successRate:i,errorRate:o,averageLatencyMs:s,p95LatencyMs:a(t,.95),p99LatencyMs:a(t,.99),maxLatencyMs:Math.max(...t),lastSeenAt:d,windowStart:u,windowEnd:d,topErrors:c}}toSeverity(e){return e>=2?`high`:e>=1.3?`medium`:`low`}mapMetricToIntent(e){switch(e){case`error-rate`:return`error-spike`;case`latency`:return`latency-regression`;case`throughput`:return`throughput-drop`;default:return`schema-mismatch`}}groupByOperation(e){let t=new Map;for(let n of e){let e=this.operationKey(n.operation),r=t.get(e)??[];r.push(n),t.set(e,r)}return t}applyLifecycleContext(e,t){if(t===void 0)return e;let n=s[o(t)]?.[e.category];return n?{...e,lifecycleStage:t,lifecycleNotes:n.message,recommendedActions:c([...e.recommendedActions,...n.supplementalActions])}:{...e,lifecycleStage:t}}};function a(e,t){return e.length?e.length===1?e[0]:e[Math.min(e.length-1,Math.floor(t*e.length))]:0}const o=e=>e<=2?`early`:e===n.ProductMarketFit?`pmf`:e===n.GrowthScaleUp||e===n.ExpansionPlatform?`scale`:`mature`,s={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`]}}},c=e=>{let t=new Set,n=[];for(let r of e)t.has(r)||(t.add(r),n.push(r));return n};export{i as SpecAnalyzer};

package/dist/approval/integration.d.ts

@@ -0,0 +1,42 @@
+import { SpecSuggestion, SpecSuggestionFilters, SpecSuggestionRepository, SpecSuggestionWriter, SuggestionStatus } from "../types.js";
+import { ApprovalWorkflow } from "@lssm/lib.ai-agent/approval";
+import { AgentSessionState } from "@lssm/lib.ai-agent/types";
+
+//#region src/approval/integration.d.ts
+interface SpecSuggestionOrchestratorOptions {
+  repository: SpecSuggestionRepository;
+  approval?: ApprovalWorkflow;
+  writer?: SpecSuggestionWriter;
+}
+declare class SpecSuggestionOrchestrator {
+  private readonly options;
+  constructor(options: SpecSuggestionOrchestratorOptions);
+  submit(suggestion: SpecSuggestion, session?: AgentSessionState, approvalReason?: string): Promise<SpecSuggestion>;
+  approve(id: string, reviewer: string, notes?: string): Promise<void>;
+  reject(id: string, reviewer: string, notes?: string): Promise<void>;
+  list(filters?: SpecSuggestionFilters): Promise<SpecSuggestion[]>;
+  private ensureSuggestion;
+}
+interface FileSystemSuggestionWriterOptions {
+  outputDir?: string;
+  filenameTemplate?: (suggestion: SpecSuggestion) => string;
+}
+declare class FileSystemSuggestionWriter implements SpecSuggestionWriter {
+  private readonly outputDir;
+  private readonly filenameTemplate;
+  constructor(options?: FileSystemSuggestionWriterOptions);
+  write(suggestion: SpecSuggestion): Promise<string>;
+}
+declare class InMemorySpecSuggestionRepository implements SpecSuggestionRepository {
+  private readonly items;
+  create(suggestion: SpecSuggestion): Promise<void>;
+  getById(id: string): Promise<SpecSuggestion | undefined>;
+  updateStatus(id: string, status: SuggestionStatus, metadata?: {
+    reviewer?: string;
+    notes?: string;
+    decidedAt?: Date;
+  }): Promise<void>;
+  list(filters?: SpecSuggestionFilters): Promise<SpecSuggestion[]>;
+}
+//#endregion
+export { FileSystemSuggestionWriter, FileSystemSuggestionWriterOptions, InMemorySpecSuggestionRepository, SpecSuggestionOrchestrator, SpecSuggestionOrchestratorOptions };

package/dist/approval/integration.js

@@ -1 +1 @@
-import{mkdir as e,writeFile as t}from"node:fs/promises";import{join as n}from"node:path";import"@lssm/lib.ai-agent/approval";var r=class{constructor(e){this.options=e}async submit(e,t,n){return await this.options.repository.create(e),t&&this.options.approval&&await this.options.approval.requestApproval({sessionId:t.sessionId,agentId:t.agentId,tenantId:t.tenantId,toolName:`evolution.apply_suggestion`,toolCallId:e.id,toolArgs:{suggestionId:e.id},reason:n??e.proposal.summary,payload:{suggestionId:e.id}}),e}async approve(e,t,n){let r=await this.ensureSuggestion(e);await this.options.repository.updateStatus(e,`approved`,{reviewer:t,notes:n,decidedAt:new Date}),this.options.writer&&await this.options.writer.write({...r,status:`approved`,approvals:{reviewer:t,notes:n,decidedAt:new Date,status:`approved`}})}async reject(e,t,n){await this.options.repository.updateStatus(e,`rejected`,{reviewer:t,notes:n,decidedAt:new Date})}list(e){return this.options.repository.list(e)}async ensureSuggestion(e){let t=await this.options.repository.getById(e);if(!t)throw Error(`Spec suggestion ${e} not found`);return t}},i=class{outputDir;filenameTemplate;constructor(e={}){this.outputDir=e.outputDir??n(process.cwd(),`packages/libs/contracts/src/generated`),this.filenameTemplate=e.filenameTemplate??(e=>`${e.target?.name??e.intent.id}.v${e.target?.version??`next`}.suggestion.json`)}async write(r){await e(this.outputDir,{recursive:!0});let i=this.filenameTemplate(r),a=n(this.outputDir,i),s=o(r);return await t(a,JSON.stringify(s,null,2)),a}},a=class{items=new Map;async create(e){this.items.set(e.id,e)}async getById(e){return this.items.get(e)}async updateStatus(e,t,n){let r=await this.getById(e);r&&this.items.set(e,{...r,status:t,approvals:{reviewer:n?.reviewer,notes:n?.notes,decidedAt:n?.decidedAt,status:t}})}async list(e){let t=[...this.items.values()];return e?t.filter(t=>!(e.status&&t.status!==e.status||e.operationName&&t.target?.name!==e.operationName)):t}};function o(e){let{proposal:t,...n}=e,{spec:r,...i}=t;return{...n,proposal:{...i,specMeta:r?.meta},createdAt:e.createdAt.toISOString(),intent:{...e.intent,confidence:{...e.intent.confidence},evidence:e.intent.evidence}}}export{i as FileSystemSuggestionWriter,a as InMemorySpecSuggestionRepository,r as SpecSuggestionOrchestrator};
+import{mkdir as e,writeFile as t}from"node:fs/promises";import{join as n}from"node:path";import{ApprovalWorkflow as r}from"@lssm/lib.ai-agent/approval";var i=class{constructor(e){this.options=e}async submit(e,t,n){return await this.options.repository.create(e),t&&this.options.approval&&await this.options.approval.requestApproval({sessionId:t.sessionId,agentId:t.agentId,tenantId:t.tenantId,toolName:`evolution.apply_suggestion`,toolCallId:e.id,toolArgs:{suggestionId:e.id},reason:n??e.proposal.summary,payload:{suggestionId:e.id}}),e}async approve(e,t,n){let r=await this.ensureSuggestion(e);await this.options.repository.updateStatus(e,`approved`,{reviewer:t,notes:n,decidedAt:new Date}),this.options.writer&&await this.options.writer.write({...r,status:`approved`,approvals:{reviewer:t,notes:n,decidedAt:new Date,status:`approved`}})}async reject(e,t,n){await this.options.repository.updateStatus(e,`rejected`,{reviewer:t,notes:n,decidedAt:new Date})}list(e){return this.options.repository.list(e)}async ensureSuggestion(e){let t=await this.options.repository.getById(e);if(!t)throw Error(`Spec suggestion ${e} not found`);return t}},a=class{outputDir;filenameTemplate;constructor(e={}){this.outputDir=e.outputDir??n(process.cwd(),`packages/libs/contracts/src/generated`),this.filenameTemplate=e.filenameTemplate??(e=>`${e.target?.name??e.intent.id}.v${e.target?.version??`next`}.suggestion.json`)}async write(r){await e(this.outputDir,{recursive:!0});let i=this.filenameTemplate(r),a=n(this.outputDir,i),o=s(r);return await t(a,JSON.stringify(o,null,2)),a}},o=class{items=new Map;async create(e){this.items.set(e.id,e)}async getById(e){return this.items.get(e)}async updateStatus(e,t,n){let r=await this.getById(e);r&&this.items.set(e,{...r,status:t,approvals:{reviewer:n?.reviewer,notes:n?.notes,decidedAt:n?.decidedAt,status:t}})}async list(e){let t=[...this.items.values()];return e?t.filter(t=>!(e.status&&t.status!==e.status||e.operationName&&t.target?.name!==e.operationName)):t}};function s(e){let{proposal:t,...n}=e,{spec:r,...i}=t;return{...n,proposal:{...i,specMeta:r?.meta},createdAt:e.createdAt.toISOString(),intent:{...e.intent,confidence:{...e.intent.confidence},evidence:e.intent.evidence}}}export{a as FileSystemSuggestionWriter,o as InMemorySpecSuggestionRepository,i as SpecSuggestionOrchestrator};

package/dist/generator/ai-spec-generator.d.ts

@@ -0,0 +1,55 @@
+import { EvolutionConfig, IntentPattern, SpecSuggestion } from "../types.js";
+import { LanguageModel } from "ai";
+
+//#region src/generator/ai-spec-generator.d.ts
+
+/**
+ * Configuration for the AI-powered spec generator.
+ */
+interface AISpecGeneratorConfig {
+  /** AI SDK language model */
+  model: LanguageModel;
+  /** Evolution configuration */
+  evolutionConfig?: EvolutionConfig;
+  /** Custom system prompt */
+  systemPrompt?: string;
+}
+/**
+ * AI-powered spec generator using AI SDK v6.
+ *
+ * Uses structured output (Output.object) to generate
+ * well-formed spec suggestions from intent patterns.
+ */
+declare class AISpecGenerator {
+  private readonly model;
+  private readonly config;
+  private readonly systemPrompt;
+  constructor(options: AISpecGeneratorConfig);
+  /**
+   * Generate a spec suggestion from an intent pattern using AI.
+   */
+  generateFromIntent(intent: IntentPattern, options?: {
+    additionalContext?: string;
+    existingSpec?: Record<string, unknown>;
+  }): Promise<SpecSuggestion>;
+  /**
+   * Generate multiple suggestions for a batch of intents.
+   */
+  generateBatch(intents: IntentPattern[], options?: {
+    maxConcurrent?: number;
+  }): Promise<SpecSuggestion[]>;
+  /**
+   * Validate and enhance an existing suggestion using AI.
+   */
+  enhanceSuggestion(suggestion: SpecSuggestion): Promise<SpecSuggestion>;
+  private buildPrompt;
+  private buildSuggestion;
+  private calculatePriority;
+  private determineInitialStatus;
+}
+/**
+ * Create an AI-powered spec generator.
+ */
+declare function createAISpecGenerator(config: AISpecGeneratorConfig): AISpecGenerator;
+//#endregion
+export { AISpecGenerator, AISpecGeneratorConfig, createAISpecGenerator };

package/dist/generator/spec-generator.d.ts

@@ -0,0 +1,46 @@
+import { EvolutionConfig, IntentPattern, OperationCoordinate, SpecSuggestion, SpecSuggestionProposal, SuggestionStatus } from "../types.js";
+import { Logger } from "@lssm/lib.observability";
+import { ContractSpec, ResourceRefDescriptor } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/lib.schema";
+
+//#region src/generator/spec-generator.d.ts
+type AnyContract = ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+interface SpecGeneratorOptions {
+  config?: EvolutionConfig;
+  logger?: Logger;
+  clock?: () => Date;
+  getSpec?: (name: string, version?: number) => AnyContract | undefined;
+}
+interface GenerateSpecOptions {
+  summary?: string;
+  rationale?: string;
+  changeType?: SpecSuggestionProposal['changeType'];
+  kind?: SpecSuggestionProposal['kind'];
+  spec?: AnyContract;
+  diff?: string;
+  metadata?: Record<string, unknown>;
+  status?: SuggestionStatus;
+  tags?: string[];
+  createdBy?: string;
+}
+type SpecPatch = Partial<ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>> & {
+  meta?: Partial<AnyContract['meta']>;
+};
+declare class SpecGenerator {
+  private readonly config;
+  private readonly logger?;
+  private readonly clock;
+  private readonly getSpec?;
+  constructor(options?: SpecGeneratorOptions);
+  generateFromIntent(intent: IntentPattern, options?: GenerateSpecOptions): SpecSuggestion;
+  generateVariant(operation: OperationCoordinate, patch: SpecPatch, intent: IntentPattern, options?: Omit<GenerateSpecOptions, 'spec'>): SpecSuggestion;
+  validateSuggestion(suggestion: SpecSuggestion, config?: EvolutionConfig): {
+    ok: boolean;
+    reasons: string[];
+  };
+  private intentToVerb;
+  private intentToPriority;
+  private inferChangeType;
+}
+//#endregion
+export { GenerateSpecOptions, SpecGenerator, SpecGeneratorOptions, SpecPatch };

package/dist/generator/spec-generator.js

@@ -1 +1 @@
-import"@lssm/lib.observability";import{randomUUID as e}from"node:crypto";var t=class{config;logger;clock;getSpec;constructor(e={}){this.config=e.config??{},this.logger=e.logger,this.clock=e.clock??(()=>new Date),this.getSpec=e.getSpec}generateFromIntent(t,n={}){let r=this.clock(),i=n.summary??`${this.intentToVerb(t.type)} ${t.operation?.name??`operation`}`,a=n.rationale??[t.description,t.metadata?.observedValue?`Observed ${t.metadata.observedValue}`:void 0].filter(Boolean).join(` — `);return{id:e(),intent:t,target:t.operation,proposal:{summary:i,rationale:a,changeType:n.changeType??this.inferChangeType(t),kind:n.kind,spec:n.spec,diff:n.diff,metadata:n.metadata},confidence:t.confidence.score,priority:this.intentToPriority(t),createdAt:r,createdBy:n.createdBy??`auto-evolution`,status:n.status??`pending`,evidence:t.evidence,tags:n.tags}}generateVariant(e,t,r,i={}){if(!this.getSpec)throw Error(`SpecGenerator requires getSpec() to generate variants`);let a=this.getSpec(e.name,e.version);if(!a)throw Error(`Cannot generate variant; spec ${e.name}.v${e.version} not found`);let o=n(a,t);return this.generateFromIntent(r,{...i,spec:o})}validateSuggestion(e,t=this.config){let n=[];t.minConfidence!=null&&e.confidence<t.minConfidence&&n.push(`Confidence ${e.confidence.toFixed(2)} below minimum ${t.minConfidence}`),t.requireApproval&&e.status===`approved`&&n.push(`Suggestion cannot be auto-approved when approval is required`),e.proposal.spec&&!e.proposal.spec.meta?.name&&n.push(`Proposal spec must include meta.name`),e.proposal.summary||n.push(`Proposal summary is required`);let r=n.length===0;return r||this.logger?.warn(`SpecGenerator.validateSuggestion.failed`,{suggestionId:e.id,reasons:n}),{ok:r,reasons:n}}intentToVerb(e){switch(e){case`error-spike`:return`Stabilize`;case`latency-regression`:return`Optimize`;case`missing-operation`:return`Introduce`;case`throughput-drop`:return`Rebalance`;default:return`Adjust`}}intentToPriority(e){let t=e.confidence.score;return e.type===`error-spike`||t>=.8?`high`:t>=.5?`medium`:`low`}inferChangeType(e){switch(e.type){case`missing-operation`:return`new-spec`;case`schema-mismatch`:return`schema-update`;case`error-spike`:return`policy-update`;default:return`revision`}}};function n(e,t){return{...e,...t,meta:{...e.meta,...t.meta},io:{...e.io,...t.io},policy:{...e.policy,...t.policy},telemetry:{...e.telemetry,...t.telemetry},sideEffects:{...e.sideEffects,...t.sideEffects}}}export{t as SpecGenerator};
+import{Logger as e}from"@lssm/lib.observability";import{randomUUID as t}from"node:crypto";var n=class{config;logger;clock;getSpec;constructor(e={}){this.config=e.config??{},this.logger=e.logger,this.clock=e.clock??(()=>new Date),this.getSpec=e.getSpec}generateFromIntent(e,n={}){let r=this.clock(),i=n.summary??`${this.intentToVerb(e.type)} ${e.operation?.name??`operation`}`,a=n.rationale??[e.description,e.metadata?.observedValue?`Observed ${e.metadata.observedValue}`:void 0].filter(Boolean).join(` — `);return{id:t(),intent:e,target:e.operation,proposal:{summary:i,rationale:a,changeType:n.changeType??this.inferChangeType(e),kind:n.kind,spec:n.spec,diff:n.diff,metadata:n.metadata},confidence:e.confidence.score,priority:this.intentToPriority(e),createdAt:r,createdBy:n.createdBy??`auto-evolution`,status:n.status??`pending`,evidence:e.evidence,tags:n.tags}}generateVariant(e,t,n,i={}){if(!this.getSpec)throw Error(`SpecGenerator requires getSpec() to generate variants`);let a=this.getSpec(e.name,e.version);if(!a)throw Error(`Cannot generate variant; spec ${e.name}.v${e.version} not found`);let o=r(a,t);return this.generateFromIntent(n,{...i,spec:o})}validateSuggestion(e,t=this.config){let n=[];t.minConfidence!=null&&e.confidence<t.minConfidence&&n.push(`Confidence ${e.confidence.toFixed(2)} below minimum ${t.minConfidence}`),t.requireApproval&&e.status===`approved`&&n.push(`Suggestion cannot be auto-approved when approval is required`),e.proposal.spec&&!e.proposal.spec.meta?.name&&n.push(`Proposal spec must include meta.name`),e.proposal.summary||n.push(`Proposal summary is required`);let r=n.length===0;return r||this.logger?.warn(`SpecGenerator.validateSuggestion.failed`,{suggestionId:e.id,reasons:n}),{ok:r,reasons:n}}intentToVerb(e){switch(e){case`error-spike`:return`Stabilize`;case`latency-regression`:return`Optimize`;case`missing-operation`:return`Introduce`;case`throughput-drop`:return`Rebalance`;default:return`Adjust`}}intentToPriority(e){let t=e.confidence.score;return e.type===`error-spike`||t>=.8?`high`:t>=.5?`medium`:`low`}inferChangeType(e){switch(e.type){case`missing-operation`:return`new-spec`;case`schema-mismatch`:return`schema-update`;case`error-spike`:return`policy-update`;default:return`revision`}}};function r(e,t){return{...e,...t,meta:{...e.meta,...t.meta},io:{...e.io,...t.io},policy:{...e.policy,...t.policy},telemetry:{...e.telemetry,...t.telemetry},sideEffects:{...e.sideEffects,...t.sideEffects}}}export{n as SpecGenerator};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { AnomalySeverity, EvolutionConfig, IntentPattern, OperationCoordinate, OperationMetricSample, OptimizationHint, PatternConfidence, SpecAnomaly, SpecSuggestion, SpecSuggestionFilters, SpecSuggestionProposal, SpecSuggestionRepository, SpecSuggestionWriter, SpecUsageStats, SuggestionEvidence, SuggestionStatus } from "./types.js";
+import { SpecAnalyzer, SpecAnalyzerOptions } from "./analyzer/spec-analyzer.js";
+import { GenerateSpecOptions, SpecGenerator, SpecGeneratorOptions, SpecPatch } from "./generator/spec-generator.js";
+import { AISpecGenerator, AISpecGeneratorConfig, createAISpecGenerator } from "./generator/ai-spec-generator.js";
+import { FileSystemSuggestionWriter, FileSystemSuggestionWriterOptions, InMemorySpecSuggestionRepository, SpecSuggestionOrchestrator, SpecSuggestionOrchestratorOptions } from "./approval/integration.js";
+export { AISpecGenerator, AISpecGeneratorConfig, AnomalySeverity, EvolutionConfig, FileSystemSuggestionWriter, FileSystemSuggestionWriterOptions, GenerateSpecOptions, InMemorySpecSuggestionRepository, IntentPattern, OperationCoordinate, OperationMetricSample, OptimizationHint, PatternConfidence, SpecAnalyzer, SpecAnalyzerOptions, SpecAnomaly, SpecGenerator, SpecGeneratorOptions, SpecPatch, SpecSuggestion, SpecSuggestionFilters, SpecSuggestionOrchestrator, SpecSuggestionOrchestratorOptions, SpecSuggestionProposal, SpecSuggestionRepository, SpecSuggestionWriter, SpecUsageStats, SuggestionEvidence, SuggestionStatus, createAISpecGenerator };

package/dist/types.d.ts

@@ -0,0 +1,131 @@
+import { LifecycleStage } from "@lssm/lib.lifecycle";
+import { ContractSpec, OpKind, ResourceRefDescriptor } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/lib.schema";
+
+//#region src/types.d.ts
+type AnomalySeverity = 'low' | 'medium' | 'high';
+type SuggestionStatus = 'pending' | 'approved' | 'rejected';
+interface OperationCoordinate {
+  name: string;
+  version: number;
+  tenantId?: string;
+}
+interface OperationMetricSample {
+  operation: OperationCoordinate;
+  durationMs: number;
+  success: boolean;
+  timestamp: Date;
+  payloadSizeBytes?: number;
+  errorCode?: string;
+  errorMessage?: string;
+  actor?: string;
+  channel?: string;
+  traceId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface SpecUsageStats {
+  operation: OperationCoordinate;
+  totalCalls: number;
+  successRate: number;
+  errorRate: number;
+  averageLatencyMs: number;
+  p95LatencyMs: number;
+  p99LatencyMs: number;
+  maxLatencyMs: number;
+  lastSeenAt: Date;
+  windowStart: Date;
+  windowEnd: Date;
+  topErrors: Record<string, number>;
+}
+interface SuggestionEvidence {
+  type: 'telemetry' | 'user-feedback' | 'simulation' | 'test';
+  description: string;
+  data?: Record<string, unknown>;
+}
+interface SpecAnomaly {
+  operation: OperationCoordinate;
+  severity: AnomalySeverity;
+  metric: 'latency' | 'error-rate' | 'throughput' | 'policy' | 'schema';
+  description: string;
+  detectedAt: Date;
+  threshold?: number;
+  observedValue?: number;
+  evidence: SuggestionEvidence[];
+}
+interface PatternConfidence {
+  score: number;
+  sampleSize: number;
+  pValue?: number;
+}
+interface IntentPattern {
+  id: string;
+  type: 'latency-regression' | 'error-spike' | 'missing-operation' | 'chained-intent' | 'throughput-drop' | 'schema-mismatch';
+  description: string;
+  operation?: OperationCoordinate;
+  confidence: PatternConfidence;
+  metadata?: Record<string, unknown>;
+  evidence: SuggestionEvidence[];
+}
+interface SpecSuggestionProposal {
+  summary: string;
+  rationale: string;
+  changeType: 'new-spec' | 'revision' | 'policy-update' | 'schema-update';
+  kind?: OpKind;
+  spec?: ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+  diff?: string;
+  metadata?: Record<string, unknown>;
+}
+interface SpecSuggestion {
+  id: string;
+  intent: IntentPattern;
+  target?: OperationCoordinate;
+  proposal: SpecSuggestionProposal;
+  confidence: number;
+  createdAt: Date;
+  createdBy: string;
+  status: SuggestionStatus;
+  evidence: SuggestionEvidence[];
+  priority: 'low' | 'medium' | 'high';
+  tags?: string[];
+  approvals?: {
+    reviewer?: string;
+    notes?: string;
+    decidedAt?: Date;
+    status?: SuggestionStatus;
+  };
+}
+interface EvolutionConfig {
+  minConfidence?: number;
+  autoApproveThreshold?: number;
+  maxSuggestionsPerOperation?: number;
+  requireApproval?: boolean;
+  maxConcurrentExperiments?: number;
+}
+interface SpecSuggestionFilters {
+  status?: SuggestionStatus;
+  operationName?: string;
+}
+interface SpecSuggestionRepository {
+  create(suggestion: SpecSuggestion): Promise<void>;
+  getById(id: string): Promise<SpecSuggestion | undefined>;
+  updateStatus(id: string, status: SuggestionStatus, metadata?: {
+    reviewer?: string;
+    notes?: string;
+    decidedAt?: Date;
+  }): Promise<void>;
+  list(filters?: SpecSuggestionFilters): Promise<SpecSuggestion[]>;
+}
+interface SpecSuggestionWriter {
+  write(suggestion: SpecSuggestion): Promise<string>;
+}
+interface OptimizationHint {
+  operation: OperationCoordinate;
+  category: 'schema' | 'policy' | 'performance' | 'error-handling';
+  summary: string;
+  justification: string;
+  recommendedActions: string[];
+  lifecycleStage?: LifecycleStage;
+  lifecycleNotes?: string;
+}
+//#endregion
+export { AnomalySeverity, EvolutionConfig, IntentPattern, OperationCoordinate, OperationMetricSample, OptimizationHint, PatternConfidence, SpecAnomaly, SpecSuggestion, SpecSuggestionFilters, SpecSuggestionProposal, SpecSuggestionRepository, SpecSuggestionWriter, SpecUsageStats, SuggestionEvidence, SuggestionStatus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.evolution",
-  "version": "0.0.0-canary-20251217054315",
+  "version": "0.0.0-canary-20251217060433",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -25,23 +25,23 @@
   "dependencies": {
     "ai": "beta",
     "zod": "^4.1.13",
-    "@lssm/lib.ai-agent": "0.0.0-canary-20251217054315",
-    "@lssm/lib.contracts": "0.0.0-canary-20251217054315",
-    "@lssm/lib.lifecycle": "0.0.0-canary-20251217054315",
-    "@lssm/lib.observability": "0.0.0-canary-20251217054315",
-    "@lssm/lib.schema": "0.0.0-canary-20251217054315"
+    "@lssm/lib.ai-agent": "0.0.0-canary-20251217060433",
+    "@lssm/lib.contracts": "0.0.0-canary-20251217060433",
+    "@lssm/lib.lifecycle": "0.0.0-canary-20251217060433",
+    "@lssm/lib.observability": "0.0.0-canary-20251217060433",
+    "@lssm/lib.schema": "0.0.0-canary-20251217060433"
   },
   "peerDependencies": {
     "@prisma/client": "7.1.0"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217054315",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217054315",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251217060433",
+    "@lssm/tool.typescript": "0.0.0-canary-20251217060433",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },
   "exports": {
-    ".": "./src/index.ts",
+    ".": "./dist/index.js",
     "./*": "./*"
   },
   "publishConfig": {