@lssm/lib.evolution 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,50 @@
+# @lssm/lib.evolution
+
+**Safe regeneration for ContractSpec** — Evolve specs automatically while preserving invariants.
+
+Auto-evolution utilities that analyze telemetry, suggest spec improvements, and route changes through approval workflows. Regenerate code safely, one module at a time.
+
+## Capabilities:
+
+- Analyze telemetry to find anomalous specs
+- Convert detected intent into spec suggestions
+- Route suggestions through the AI approval workflow
+- Persist approved specs back into the codebase
+
+> Phase 3 anchor library – pairs with `@lssm/lib.observability` and `@lssm/lib.growth`.
+
+## Usage
+
+```ts
+import {
+  SpecAnalyzer,
+  SpecGenerator,
+  SpecSuggestionOrchestrator,
+} from '@lssm/lib.evolution';
+
+const analyzer = new SpecAnalyzer();
+const stats = analyzer.analyzeSpecUsage(samples);
+const anomalies = analyzer.detectAnomalies(stats);
+
+const generator = new SpecGenerator({ getSpec });
+const suggestion = generator.generateFromIntent(anomalies[0]);
+
+await orchestrator.submit(suggestion, { agent: 'auto-evolve' });
+```
+
+See `app/docs/libraries/evolution` in `@lssm/app.web-contractspec-landing` for full docs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/ai-agent/dist/approval/index.js

@@ -0,0 +1 @@
+import"./workflow.js";

package/dist/ai-agent/dist/approval/workflow.js

@@ -0,0 +1 @@
+import{randomUUID as e}from"node:crypto";

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

@@ -0,0 +1,34 @@
+import { IntentPattern, OperationMetricSample, OptimizationHint, SpecAnomaly, SpecUsageStats } from "../types.js";
+import { LifecycleStage } from "@lssm/lib.lifecycle";
+import { Logger } from "@lssm/lib.observability";
+
+//#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

@@ -0,0 +1 @@
+import"../observability/dist/index.js";import{e}from"../lifecycle/dist/types/stages.js";import"../lifecycle/dist/index.js";import{randomUUID as t}from"node:crypto";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(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,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=t=>t<=2?`early`:t===e.ProductMarketFit?`pmf`:t===e.GrowthScaleUp||t===e.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};

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

@@ -0,0 +1 @@
+import"../ai-agent/dist/approval/index.js";import{mkdir as e,writeFile as t}from"node:fs/promises";import{join as n}from"node:path";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/contractspec/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};

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/ai-spec-generator.js

@@ -0,0 +1,19 @@
+import{randomUUID as e}from"node:crypto";import{Output as t,generateText as n}from"ai";import{z as r}from"zod";const i=r.object({summary:r.string().describe(`Brief summary of the proposed change`),rationale:r.string().describe(`Detailed explanation of why this change is needed`),changeType:r.enum([`new-spec`,`revision`,`policy-update`,`schema-update`]).describe(`Type of change being proposed`),recommendedActions:r.array(r.string()).describe(`List of specific actions to implement the change`),estimatedImpact:r.enum([`low`,`medium`,`high`]).describe(`Estimated impact of implementing this change`),riskLevel:r.enum([`low`,`medium`,`high`]).describe(`Risk level associated with this change`),diff:r.string().optional().describe(`Optional diff or code snippet showing the change`)});var a=class{model;config;systemPrompt;constructor(e){this.model=e.model,this.config=e.evolutionConfig??{},this.systemPrompt=e.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(e,r={}){let a=this.buildPrompt(e,r),{output:o}=await n({model:this.model,system:this.systemPrompt,prompt:a,output:t.object({schema:i})});return this.buildSuggestion(e,o)}async generateBatch(e,t={}){let n=t.maxConcurrent??3,r=[];for(let t=0;t<e.length;t+=n){let i=e.slice(t,t+n),a=await Promise.all(i.map(e=>this.generateFromIntent(e)));r.push(...a)}return r}async enhanceSuggestion(e){let r=`Review and enhance this spec suggestion:
+
+Intent: ${e.intent.type} - ${e.intent.description}
+Current Summary: ${e.proposal.summary}
+Current Rationale: ${e.proposal.rationale}
+
+Evidence:
+${e.evidence.map(e=>`- ${e.type}: ${e.description}`).join(`
+`)}
+
+Please provide an improved version with more specific recommendations.`,{output:a}=await n({model:this.model,system:this.systemPrompt,prompt:r,output:t.object({schema:i})});return{...e,proposal:{...e.proposal,summary:a.summary,rationale:a.rationale,changeType:a.changeType,diff:a.diff,metadata:{...e.proposal.metadata,aiEnhanced:!0,recommendedActions:a.recommendedActions,estimatedImpact:a.estimatedImpact,riskLevel:a.riskLevel}}}}buildPrompt(e,t){let n=[`Analyze this intent pattern and generate a spec suggestion:`,``,`Intent Type: ${e.type}`,`Description: ${e.description}`,`Confidence: ${(e.confidence.score*100).toFixed(0)}% (sample size: ${e.confidence.sampleSize})`];if(e.operation&&n.push(`Operation: ${e.operation.name} v${e.operation.version}`),e.evidence.length>0){n.push(``,`Evidence:`);for(let t of e.evidence)n.push(`- [${t.type}] ${t.description}`)}return e.metadata&&n.push(``,`Metadata: ${JSON.stringify(e.metadata,null,2)}`),t.existingSpec&&n.push(``,`Existing Spec:`,"```json",JSON.stringify(t.existingSpec,null,2),"```"),t.additionalContext&&n.push(``,`Additional Context:`,t.additionalContext),n.join(`
+`)}buildSuggestion(t,n){let r=new Date,i={summary:n.summary,rationale:n.rationale,changeType:n.changeType,diff:n.diff,metadata:{aiGenerated:!0,recommendedActions:n.recommendedActions,estimatedImpact:n.estimatedImpact,riskLevel:n.riskLevel}};return{id:e(),intent:t,target:t.operation,proposal:i,confidence:t.confidence.score,priority:this.calculatePriority(t,n),createdAt:r,createdBy:`ai-spec-generator`,status:this.determineInitialStatus(t),evidence:t.evidence,tags:[`ai-generated`,t.type]}}calculatePriority(e,t){let n=t.estimatedImpact===`high`?1:t.estimatedImpact===`medium`?.5:.25,r=e.confidence.score,i=e.type===`error-spike`?.3:e.type===`latency-regression`?.2:0,a=n*.4+r*.4+i;return a>=.7?`high`:a>=.4?`medium`:`low`}determineInitialStatus(e){return this.config.autoApproveThreshold&&e.confidence.score>=this.config.autoApproveThreshold&&!this.config.requireApproval?`approved`:`pending`}};function o(e){return new a(e)}export{a as AISpecGenerator,o as createAISpecGenerator};

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

@@ -0,0 +1,46 @@
+import { EvolutionConfig, IntentPattern, OperationCoordinate, SpecSuggestion, SpecSuggestionProposal, SuggestionStatus } from "../types.js";
+import { ContractSpec, ResourceRefDescriptor } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/lib.schema";
+import { Logger } from "@lssm/lib.observability";
+
+//#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

@@ -0,0 +1 @@
+import"../observability/dist/index.js";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};

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/index.js

@@ -0,0 +1 @@
+import{SpecAnalyzer as e}from"./analyzer/spec-analyzer.js";import{SpecGenerator as t}from"./generator/spec-generator.js";import{AISpecGenerator as n,createAISpecGenerator as r}from"./generator/ai-spec-generator.js";import{FileSystemSuggestionWriter as i,InMemorySpecSuggestionRepository as a,SpecSuggestionOrchestrator as o}from"./approval/integration.js";export{n as AISpecGenerator,i as FileSystemSuggestionWriter,a as InMemorySpecSuggestionRepository,e as SpecAnalyzer,t as SpecGenerator,o as SpecSuggestionOrchestrator,r as createAISpecGenerator};

package/dist/lifecycle/dist/index.js

@@ -0,0 +1 @@
+import{e,n as t}from"./types/stages.js";import"./types/axes.js";import"./types/signals.js";import"./types/milestones.js";import"./utils/formatters.js";

package/dist/lifecycle/dist/types/axes.js

@@ -0,0 +1 @@
+(function(e){return e.Sketch=`Sketch`,e.Prototype=`Prototype`,e.Mvp=`MVP`,e.V1=`V1`,e.Ecosystem=`Ecosystem`,e})({}),function(e){return e.Solo=`Solo`,e.TinyTeam=`TinyTeam`,e.FunctionalOrg=`FunctionalOrg`,e.MultiTeam=`MultiTeam`,e.Bureaucratic=`Bureaucratic`,e}({}),function(e){return e.Bootstrapped=`Bootstrapped`,e.PreSeed=`PreSeed`,e.Seed=`Seed`,e.SeriesAorB=`SeriesAorB`,e.LateStage=`LateStage`,e}({});

package/dist/lifecycle/dist/types/milestones.js

@@ -0,0 +1 @@
+import"./stages.js";

package/dist/lifecycle/dist/types/signals.js

@@ -0,0 +1 @@
+import"./stages.js";

package/dist/lifecycle/dist/types/stages.js

@@ -0,0 +1 @@
+let e=function(e){return e[e.Exploration=0]=`Exploration`,e[e.ProblemSolutionFit=1]=`ProblemSolutionFit`,e[e.MvpEarlyTraction=2]=`MvpEarlyTraction`,e[e.ProductMarketFit=3]=`ProductMarketFit`,e[e.GrowthScaleUp=4]=`GrowthScaleUp`,e[e.ExpansionPlatform=5]=`ExpansionPlatform`,e[e.MaturityRenewal=6]=`MaturityRenewal`,e}({});e.Exploration,e.ProblemSolutionFit,e.MvpEarlyTraction,e.ProductMarketFit,e.GrowthScaleUp,e.ExpansionPlatform,e.MaturityRenewal;const t={[e.Exploration]:{id:e.Exploration,order:0,slug:`exploration`,name:`Exploration / Ideation`,question:`Is there a problem worth my time?`,signals:[`20+ discovery interviews`,`Clear problem statement`,`Named ICP`],traps:[`Branding before discovery`,`Premature tooling decisions`],focusAreas:[`Customer discovery`,`Problem definition`,`Segment clarity`]},[e.ProblemSolutionFit]:{id:e.ProblemSolutionFit,order:1,slug:`problem-solution-fit`,name:`Problem–Solution Fit`,question:`Do people care enough about this solution?`,signals:[`Prototype reuse`,`Referral energy`,`Pre-pay interest`],traps:[`“Market is huge” without users`,`Skipping qualitative loops`],focusAreas:[`Solution hypothesis`,`Value messaging`,`Feedback capture`]},[e.MvpEarlyTraction]:{id:e.MvpEarlyTraction,order:2,slug:`mvp-early-traction`,name:`MVP & Early Traction`,question:`Can we get real usage and learn fast?`,signals:[`20–50 named active users`,`Weekly releases`,`Noisy feedback`],traps:[`Overbuilt infra for 10 users`,`Undefined retention metric`],focusAreas:[`Activation`,`Cohort tracking`,`Feedback rituals`]},[e.ProductMarketFit]:{id:e.ProductMarketFit,order:3,slug:`product-market-fit`,name:`Product–Market Fit`,question:`Is this pulling us forward?`,signals:[`Retention without heroics`,`Organic word-of-mouth`,`Value stories`],traps:[`Hero growth that does not scale`,`Ignoring churn signals`],focusAreas:[`Retention`,`Reliability`,`ICP clarity`]},[e.GrowthScaleUp]:{id:e.GrowthScaleUp,order:4,slug:`growth-scale-up`,name:`Growth / Scale-up`,question:`Can we grow this repeatably?`,signals:[`Predictable channels`,`Specialized hires`,`Unit economics on track`],traps:[`Paid spend masking retention gaps`,`Infra debt blocking launches`],focusAreas:[`Ops systems`,`Growth loops`,`Reliability engineering`]},[e.ExpansionPlatform]:{id:e.ExpansionPlatform,order:5,slug:`expansion-platform`,name:`Expansion / Platform`,question:`What is the next growth curve?`,signals:[`Stable core metrics`,`Partner/API demand`,`Ecosystem pull`],traps:[`Platform theater before wedge is solid`],focusAreas:[`Partnerships`,`APIs`,`New market validation`]},[e.MaturityRenewal]:{id:e.MaturityRenewal,order:6,slug:`maturity-renewal`,name:`Maturity / Renewal`,question:`Optimize, reinvent, or sunset?`,signals:[`Margin focus`,`Portfolio bets`,`Narrative refresh`],traps:[`Assuming past success is enough`],focusAreas:[`Cost optimization`,`Reinvention bets`,`Sunset planning`]}};export{e,t as n};

package/dist/lifecycle/dist/utils/formatters.js

@@ -0,0 +1 @@
+import"../types/stages.js";

package/dist/observability/dist/index.js

@@ -0,0 +1 @@
+import"./tracing/index.js";import{i as e,n as t,t as n}from"./metrics/index.js";import{n as r}from"./logging/index.js";import"./tracing/middleware.js";import"./intent/detector.js";import"./pipeline/evolution-pipeline.js";import"./pipeline/lifecycle-pipeline.js";

package/dist/observability/dist/intent/detector.js

@@ -0,0 +1 @@
+import{randomUUID as e}from"node:crypto";

package/dist/observability/dist/lifecycle/dist/index.js

@@ -0,0 +1 @@
+import"./types/stages.js";import"./utils/formatters.js";import"./types/axes.js";import"./types/signals.js";import"./types/milestones.js";

package/dist/observability/dist/lifecycle/dist/types/axes.js

@@ -0,0 +1 @@
+(function(e){return e.Sketch=`Sketch`,e.Prototype=`Prototype`,e.Mvp=`MVP`,e.V1=`V1`,e.Ecosystem=`Ecosystem`,e})({}),function(e){return e.Solo=`Solo`,e.TinyTeam=`TinyTeam`,e.FunctionalOrg=`FunctionalOrg`,e.MultiTeam=`MultiTeam`,e.Bureaucratic=`Bureaucratic`,e}({}),function(e){return e.Bootstrapped=`Bootstrapped`,e.PreSeed=`PreSeed`,e.Seed=`Seed`,e.SeriesAorB=`SeriesAorB`,e.LateStage=`LateStage`,e}({});

package/dist/observability/dist/lifecycle/dist/types/milestones.js

@@ -0,0 +1 @@
+import"./stages.js";

package/dist/observability/dist/lifecycle/dist/types/signals.js

@@ -0,0 +1 @@
+import"./stages.js";

package/dist/observability/dist/lifecycle/dist/types/stages.js

@@ -0,0 +1 @@
+let e=function(e){return e[e.Exploration=0]=`Exploration`,e[e.ProblemSolutionFit=1]=`ProblemSolutionFit`,e[e.MvpEarlyTraction=2]=`MvpEarlyTraction`,e[e.ProductMarketFit=3]=`ProductMarketFit`,e[e.GrowthScaleUp=4]=`GrowthScaleUp`,e[e.ExpansionPlatform=5]=`ExpansionPlatform`,e[e.MaturityRenewal=6]=`MaturityRenewal`,e}({});e.Exploration,e.ProblemSolutionFit,e.MvpEarlyTraction,e.ProductMarketFit,e.GrowthScaleUp,e.ExpansionPlatform,e.MaturityRenewal,e.Exploration,e.Exploration,e.ProblemSolutionFit,e.ProblemSolutionFit,e.MvpEarlyTraction,e.MvpEarlyTraction,e.ProductMarketFit,e.ProductMarketFit,e.GrowthScaleUp,e.GrowthScaleUp,e.ExpansionPlatform,e.ExpansionPlatform,e.MaturityRenewal,e.MaturityRenewal;

package/dist/observability/dist/lifecycle/dist/utils/formatters.js

@@ -0,0 +1 @@
+import"../types/stages.js";

package/dist/observability/dist/logging/index.js

@@ -0,0 +1 @@
+import{context as e,trace as t}from"@opentelemetry/api";var n=class{constructor(e){this.serviceName=e}log(n,r,i={}){let a=t.getSpan(e.active()),o=a?.spanContext().traceId,s=a?.spanContext().spanId,c={timestamp:new Date().toISOString(),service:this.serviceName,level:n,message:r,traceId:o,spanId:s,...i};console.log(JSON.stringify(c))}debug(e,t){this.log(`debug`,e,t)}info(e,t){this.log(`info`,e,t)}warn(e,t){this.log(`warn`,e,t)}error(e,t){this.log(`error`,e,t)}};new n(process.env.OTEL_SERVICE_NAME||`unknown-service`);export{n};

package/dist/observability/dist/metrics/index.js

@@ -0,0 +1 @@
+import{metrics as e}from"@opentelemetry/api";function t(t=`@lssm/lib.observability`){return e.getMeter(t)}function n(e,n,r){return t(r).createCounter(e,{description:n})}function r(e,n,r){return t(r).createHistogram(e,{description:n})}n(`http_requests_total`,`Total HTTP requests`),r(`http_request_duration_seconds`,`HTTP request duration`),n(`operation_errors_total`,`Total operation errors`),r(`workflow_duration_seconds`,`Workflow execution duration`);export{r as i,n,t};

package/dist/observability/dist/pipeline/evolution-pipeline.js

@@ -0,0 +1 @@
+import"../intent/detector.js";import"node:events";

package/dist/observability/dist/pipeline/lifecycle-pipeline.js

@@ -0,0 +1 @@
+import"../metrics/index.js";import"../lifecycle/dist/utils/formatters.js";import"../lifecycle/dist/index.js";import"node:events";

package/dist/observability/dist/tracing/index.js

@@ -0,0 +1 @@
+import{context as e,trace as t}from"@opentelemetry/api";

package/dist/observability/dist/tracing/middleware.js

@@ -0,0 +1 @@
+import"./index.js";import"../metrics/index.js";

package/dist/types.d.ts

@@ -0,0 +1,131 @@
+import { ContractSpec, OpKind, ResourceRefDescriptor } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/lib.schema";
+import { LifecycleStage } from "@lssm/lib.lifecycle";
+
+//#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

@@ -0,0 +1,49 @@
+{
+  "name": "@lssm/lib.evolution",
+  "version": "0.0.0-canary-20251206160926",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "ai": "beta",
+    "zod": "^4.1.13",
+    "@lssm/lib.ai-agent": "workspace:*",
+    "@lssm/lib.contracts": "workspace:*",
+    "@lssm/lib.lifecycle": "workspace:*",
+    "@lssm/lib.observability": "workspace:*",
+    "@lssm/lib.schema": "workspace:*"
+  },
+  "peerDependencies": {
+    "@prisma/client": "7.1.0"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}