@lssm/example.analytics-dashboard 0.0.0-canary-20251217060433 → 0.0.0-canary-20251217062139

package/dist/libs/contracts/dist/docs/tech/PHASE_1_QUICKSTART.docblock.js

@@ -0,0 +1,398 @@
+import { a } from "../registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech/PHASE_1_QUICKSTART.docblock.js
+const t = [{
+	id: `docs.tech.PHASE_1_QUICKSTART`,
+	title: `Phase 1: API Reference Index`,
+	summary: `Quick reference for all new Phase 1 APIs.`,
+	kind: `reference`,
+	visibility: `public`,
+	route: `/docs/tech/PHASE_1_QUICKSTART`,
+	tags: [`tech`, `PHASE_1_QUICKSTART`],
+	body: `# Phase 1: API Reference Index
+
+Quick reference for all new Phase 1 APIs.
+
+---
+
+## @lssm/lib.multi-tenancy
+
+### RLS
+\`\`\`typescript
+import { createRlsMiddleware, type TenantIdProvider } from '@lssm/lib.multi-tenancy/rls';
+\`\`\`
+
+### Provisioning
+\`\`\`typescript
+import { 
+  TenantProvisioningService,
+  type CreateTenantInput,
+  type TenantProvisioningConfig 
+} from '@lssm/lib.multi-tenancy/provisioning';
+\`\`\`
+
+### Isolation
+\`\`\`typescript
+import { IsolationValidator } from '@lssm/lib.multi-tenancy/isolation';
+\`\`\`
+
+---
+
+## @lssm/lib.observability
+
+### Tracing
+\`\`\`typescript
+import { 
+  getTracer,
+  traceAsync,
+  traceSync,
+  createTracingMiddleware 
+} from '@lssm/lib.observability/tracing';
+\`\`\`
+
+### Metrics
+\`\`\`typescript
+import {
+  getMeter,
+  createCounter,
+  createUpDownCounter,
+  createHistogram,
+  standardMetrics
+} from '@lssm/lib.observability/metrics';
+\`\`\`
+
+### Logging
+\`\`\`typescript
+import {
+  Logger,
+  logger,
+  type LogLevel,
+  type LogEntry
+} from '@lssm/lib.observability/logging';
+\`\`\`
+
+---
+
+## @lssm/lib.resilience
+
+### Circuit Breaker
+\`\`\`typescript
+import {
+  CircuitBreaker,
+  type CircuitState,
+  type CircuitBreakerConfig
+} from '@lssm/lib.resilience/circuit-breaker';
+\`\`\`
+
+### Retry
+\`\`\`typescript
+import { retry } from '@lssm/lib.resilience/retry';
+\`\`\`
+
+### Timeout
+\`\`\`typescript
+import { timeout } from '@lssm/lib.resilience/timeout';
+\`\`\`
+
+### Fallback
+\`\`\`typescript
+import { fallback } from '@lssm/lib.resilience/fallback';
+\`\`\`
+
+---
+
+## Enhanced: @lssm/lib.contracts
+
+### DataViews
+\`\`\`typescript
+import { DataViewQueryGenerator } from '@lssm/lib.contracts/data-views/query-generator';
+import { DataViewRuntime } from '@lssm/lib.contracts/data-views/runtime';
+\`\`\`
+
+### Workflows
+\`\`\`typescript
+import { SLAMonitor, type SLABreachEvent } from '@lssm/lib.contracts/workflow/sla-monitor';
+import { PrismaStateStore } from '@lssm/lib.contracts/workflow/adapters/db-adapter';
+\`\`\`
+
+---
+
+## Enhanced: @lssm/lib.design-system
+
+### DataView Components
+\`\`\`typescript
+import { DataViewRenderer } from '@lssm/lib.design-system/components/data-view/DataViewRenderer';
+// Also available: DataViewList, DataViewTable, DataViewDetail
+\`\`\`
+
+---
+
+## Usage Examples
+
+### Complete Workflow with All Features
+
+\`\`\`typescript
+import { WorkflowRunner } from '@lssm/lib.contracts/workflow/runner';
+import { PrismaStateStore } from '@lssm/lib.contracts/workflow/adapters/db-adapter';
+import { SLAMonitor } from '@lssm/lib.contracts/workflow/sla-monitor';
+import { CircuitBreaker } from '@lssm/lib.resilience/circuit-breaker';
+import { traceAsync } from '@lssm/lib.observability/tracing';
+
+const runner = new WorkflowRunner({
+  registry,
+  stateStore: new PrismaStateStore(db),
+  opExecutor: async (op, input, ctx) => {
+    return traceAsync(\`op.\${op.name}\`, async (span) => {
+      span.setAttribute('operation', op.name);
+      const breaker = getCircuitBreaker(op.name);
+      return breaker.execute(() => executeOperation(op, input, ctx));
+    });
+  },
+  eventEmitter: (event, payload) => {
+    if (event.startsWith('workflow.')) {
+      logger.info(event, payload);
+    }
+  },
+});
+
+const monitor = new SLAMonitor((event, payload) => {
+  logger.warn('SLA_BREACH', payload);
+  alertOps(payload);
+});
+
+// Start workflow
+const workflowId = await runner.start('payment.flow', 1);
+
+// Monitor SLA
+const state = await runner.getState(workflowId);
+const spec = registry.get('payment.flow', 1);
+monitor.check(state, spec!);
+\`\`\`
+
+### Complete DataView with Observability
+
+\`\`\`typescript
+import { DataViewRenderer } from '@lssm/lib.design-system';
+import { DataViewQueryGenerator } from '@lssm/lib.contracts/data-views/query-generator';
+import { traceAsync } from '@lssm/lib.observability/tracing';
+import { MyDataView } from './specs/users.data-view';
+
+export function UserListPage() {
+  const [page, setPage] = useState(1);
+  const [users, setUsers] = useState([]);
+
+  const loadUsers = async () => {
+    return traceAsync('load_users', async (span) => {
+      const generator = new DataViewQueryGenerator(MyDataView);
+      const query = generator.generate({ pagination: { page, pageSize: 20 } });
+      
+      span.setAttribute('page', page);
+      const result = await api.execute(query);
+      setUsers(result.data);
+    });
+  };
+
+  return (
+    <DataViewRenderer
+      spec={MyDataView}
+      items={users}
+      pagination={{ page, pageSize: 20, total: users.length }}
+      onPageChange={setPage}
+    />
+  );
+}
+\`\`\`
+
+### Complete Multi-Tenant Setup
+
+\`\`\`typescript
+// 1. RLS Middleware
+import { createRlsMiddleware } from '@lssm/lib.multi-tenancy/rls';
+db.$use(createRlsMiddleware(() => req.tenantId));
+
+// 2. Tenant Provisioning
+import { TenantProvisioningService } from '@lssm/lib.multi-tenancy/provisioning';
+const service = new TenantProvisioningService({ db });
+
+// 3. Create new tenant
+await service.provision({
+  id: 'acme',
+  name: 'Acme Corp',
+  slug: 'acme',
+  ownerEmail: 'admin@acme.com',
+});
+
+// 4. Validate isolation in tests
+import { IsolationValidator } from '@lssm/lib.multi-tenancy/isolation';
+
+test('queries are isolated', () => {
+  const isValid = IsolationValidator.validateQuery(
+    'User',
+    'findMany',
+    { where: { tenantId: 'acme' } },
+    'acme'
+  );
+  expect(isValid).toBe(true);
+});
+\`\`\`
+
+---
+
+## Testing
+
+### Test Circuit Breakers
+
+\`\`\`typescript
+import { CircuitBreaker } from '@lssm/lib.resilience/circuit-breaker';
+
+test('circuit opens after threshold', async () => {
+  const breaker = new CircuitBreaker({
+    failureThreshold: 3,
+    resetTimeoutMs: 5000,
+  });
+
+  // Trigger failures
+  for (let i = 0; i < 3; i++) {
+    await expect(
+      breaker.execute(() => Promise.reject('error'))
+    ).rejects.toThrow();
+  }
+
+  // Circuit should be open
+  await expect(
+    breaker.execute(() => Promise.resolve('ok'))
+  ).rejects.toThrow('CircuitBreaker is OPEN');
+});
+\`\`\`
+
+### Test Workflow Retry
+
+\`\`\`typescript
+test('workflow retries on failure', async () => {
+  let attempts = 0;
+  const opExecutor = async () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const runner = new WorkflowRunner({ /* ... */ opExecutor });
+  await runner.executeStep(workflowId);
+  
+  expect(attempts).toBe(3);
+});
+\`\`\`
+
+---
+
+## Common Patterns
+
+### Pattern: Resilient External Call
+
+\`\`\`typescript
+import { CircuitBreaker } from '@lssm/lib.resilience/circuit-breaker';
+import { retry } from '@lssm/lib.resilience/retry';
+import { timeout } from '@lssm/lib.resilience/timeout';
+import { traceAsync } from '@lssm/lib.observability/tracing';
+
+const breaker = new CircuitBreaker({ failureThreshold: 5, resetTimeoutMs: 30000 });
+
+export async function callExternalAPI(input: any) {
+  return traceAsync('external_api_call', async (span) => {
+    span.setAttribute('service', 'stripe');
+    
+    return breaker.execute(() =>
+      retry(
+        () => timeout(() => stripe.api.call(input), 5000),
+        3,
+        1000,
+        true
+      )
+    );
+  });
+}
+\`\`\`
+
+**Benefits**: Circuit breaker + retry + timeout + tracing in one place.
+
+---
+
+### Pattern: Tenant-Aware Operation
+
+\`\`\`typescript
+import { traceAsync } from '@lssm/lib.observability/tracing';
+
+export async function listUsers(tenantId: string) {
+  return traceAsync('list_users', async (span) => {
+    span.setAttribute('tenant_id', tenantId);
+    
+    // RLS middleware will inject WHERE tenantId = ?
+    return db.user.findMany();
+  });
+}
+\`\`\`
+
+---
+
+### Pattern: Monitored Workflow
+
+\`\`\`typescript
+import { WorkflowRunner } from '@lssm/lib.contracts/workflow/runner';
+import { SLAMonitor } from '@lssm/lib.contracts/workflow/sla-monitor';
+import { logger } from '@lssm/lib.observability/logging';
+
+const monitor = new SLAMonitor((event, payload) => {
+  logger.warn('workflow.sla_breach', payload);
+});
+
+// In workflow poller
+const state = await runner.getState(workflowId);
+const spec = registry.get(state.workflowName, state.workflowVersion);
+if (spec) {
+  monitor.check(state, spec);
+}
+\`\`\`
+
+---
+
+## Next Steps
+
+1. **Implement one quick win** (30 minutes)
+2. **Add tests for new functionality** (1 hour)
+3. **Deploy to staging and verify observability** (1 hour)
+4. **Roll out to production** (monitor closely)
+5. **Read full documentation** at https://contractspec.lssm.tech/docs
+
+---
+
+**Questions?** See \`/docs/guides/phase-1-migration\` or reach out via https://contractspec.lssm.tech/contact
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`
+}];
+a(t);
+
+//#endregion

package/dist/libs/contracts/dist/docs/tech/PHASE_2_AI_NATIVE_OPERATIONS.docblock.js

@@ -0,0 +1,83 @@
+import { a } from "../registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech/PHASE_2_AI_NATIVE_OPERATIONS.docblock.js
+const t = [{
+	id: `docs.tech.PHASE_2_AI_NATIVE_OPERATIONS`,
+	title: `Phase 2: AI-Native Operations`,
+	summary: `_Last updated: 2025-11-20_`,
+	kind: `reference`,
+	visibility: `public`,
+	route: `/docs/tech/PHASE_2_AI_NATIVE_OPERATIONS`,
+	tags: [`tech`, `PHASE_2_AI_NATIVE_OPERATIONS`],
+	body: `# Phase 2: AI-Native Operations
+
+_Last updated: 2025-11-20_
+
+Phase 2 turns ContractSpec into an AI-first operations stack. The new libraries below are the building blocks used by support bots, growth agents, and human-in-the-loop flows.
+
+## Libraries
+
+### @lssm/lib.ai-agent
+
+- **Spec + Registry**: \`defineAgent\`, \`AgentRegistry\` keep agent definitions type-safe.
+- **Runner**: \`AgentRunner\` drives LLM conversations, tool calls, retries, escalation, and telemetry hooks.
+- **Tools**: \`ToolExecutor\` standardizes schema validation + timeouts.
+- **Memory**: \`InMemoryAgentMemory\` + interfaces for plugging persistent stores.
+- **Approvals**: new \`ApprovalWorkflow\` + \`InMemoryApprovalStore\` capture low-confidence decisions and surface them to reviewers.
+
+### @lssm/lib.support-bot
+
+Composable support automation primitives:
+
+- \`TicketClassifier\` → heuristics + optional LLM validation for category, priority, sentiment.
+- \`TicketResolver\` → RAG pipeline backed by knowledge spaces.
+- \`AutoResponder\` → tone-aware drafts with citations.
+- \`SupportFeedbackLoop\` → tracks resolution rates.
+- \`createSupportTools\` → ready-made tool definitions for AgentRunner.
+
+### @lssm/lib.content-gen
+
+Content generators that consume a \`ContentBrief\` and output production-ready assets:
+
+- \`BlogGenerator\`, \`LandingPageGenerator\`, \`EmailCampaignGenerator\`, \`SocialPostGenerator\`.
+- \`SeoOptimizer\` builds metadata + schema markup.
+
+### @lssm/lib.analytics
+
+Queryless analytics helpers:
+
+- \`FunnelAnalyzer\` – conversion/drop-off per step.
+- \`CohortTracker\` – retention + LTV per cohort.
+- \`ChurnPredictor\` – recency/frequency/error scoring.
+- \`GrowthHypothesisGenerator\` – surfaces experiment ideas from metric trends.
+
+### @lssm/lib.growth
+
+A/B testing toolkit:
+
+- \`ExperimentRegistry\` + \`ExperimentRunner\` – deterministic bucketing.
+- \`ExperimentTracker\` – persist exposures + metrics.
+- \`StatsEngine\` – Welch’s t-test + improvement calculations.
+
+### Human-in-the-loop UI
+
+\`@lssm/lib.design-system\` now exposes:
+
+- \`ApprovalQueue\` – list + act on pending approvals.
+- \`AgentMonitor\` – live view of agent sessions with confidence + status.
+
+## Examples
+
+- \`examples/ai-support-bot/setup.ts\` shows ticket classification → resolution → response draft.
+- \`examples/content-generation/generate.ts\` produces blog, landing, email, social, SEO output from one brief.
+
+## Next Steps
+
+1. Wire these libraries into vertical apps (H-Circle, ArtisanOS, etc.).
+2. Add background workers that consume the new analytics/growth trackers.
+3. Expand web-landing to highlight these Phase 2 capabilities (see separate TODO).
+`
+}];
+a(t);
+
+//#endregion

package/dist/libs/contracts/dist/docs/tech/PHASE_3_AUTO_EVOLUTION.docblock.js

@@ -0,0 +1,155 @@
+import { a } from "../registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech/PHASE_3_AUTO_EVOLUTION.docblock.js
+const t = [{
+	id: `docs.tech.PHASE_3_AUTO_EVOLUTION`,
+	title: `Phase 3: Auto-Evolution Technical Notes`,
+	summary: `**Status**: In progress`,
+	kind: `reference`,
+	visibility: `public`,
+	route: `/docs/tech/PHASE_3_AUTO_EVOLUTION`,
+	tags: [`tech`, `PHASE_3_AUTO_EVOLUTION`],
+	body: `# Phase 3: Auto-Evolution Technical Notes
+
+**Status**: In progress  
+**Last updated**: 2025-11-21  
+
+Phase 3 introduces self-learning capabilities that analyze production telemetry, suggest new specs, safely roll out variants, and generate golden tests from real traffic. This document captures the main building blocks delivered in this iteration.
+
+---
+
+## 1. Libraries
+
+### @lssm/lib.evolution
+
+- \`SpecAnalyzer\` converts raw telemetry samples into usage stats + anomalies.
+- \`SpecGenerator\` produces \`SpecSuggestion\` objects and validates confidence thresholds.
+- \`SpecSuggestionOrchestrator\` routes proposals through the AI approval workflow and writes approved specs to \`packages/libs/contracts/src/generated\`.
+- Storage adapters:
+  - \`InMemorySpecSuggestionRepository\` for tests.
+  - \`PrismaSpecSuggestionRepository\` persists to the new Prisma model (see §4).
+  - \`FileSystemSuggestionWriter\` emits JSON envelopes for git review.
+
+### @lssm/lib.observability
+
+- Added intent detection modules:
+  - \`IntentAggregator\` batches telemetry into rolling windows.
+  - \`IntentDetector\` surfaces latency/error/throughput regressions and sequential intents.
+- \`EvolutionPipeline\` orchestrates aggregation → detection → intent events and exposes hooks for downstream orchestrators.
+- \`createTracingMiddleware\` now accepts \`resolveOperation\`/\`onSample\` hooks to feed telemetry samples into the pipeline.
+
+### @lssm/lib.growth
+
+- New \`spec-experiments\` module:
+  - \`SpecExperimentRegistry\`, \`SpecExperimentRunner\`, \`SpecExperimentAdapter\`.
+  - \`SpecExperimentAnalyzer\` + \`SpecExperimentController\` handle guardrails and staged rollouts.
+  - Helper \`createSpecVariantResolver\` plugs directly into \`HandlerCtx.specVariantResolver\`.
+- \`SpecVariantResolver\` is now a first-class concept in \`@lssm/lib.contracts\`. The runtime will attempt to execute variant specs before falling back to the registered handler.
+
+### @lssm/lib.testing
+
+- \`TrafficRecorder\` + \`TrafficStore\` capture production requests with sampling and sanitization hooks.
+- \`GoldenTestGenerator\` converts \`TrafficSnapshot\`s into Vitest/Jest suites.
+- \`generateVitestSuite\` / \`generateJestSuite\` output self-contained test files, and \`runGoldenTests\` offers a programmatic harness for CI pipelines.
+
+---
+
+## 2. Telemetry → Intent → Spec Pipeline
+
+1. \`createTracingMiddleware({ onSample })\` emits \`TelemetrySample\`s for every HTTP request.
+2. \`IntentAggregator\` groups samples into statistical windows (default 15 minutes).
+3. \`IntentDetector\` raises signals for:
+   - Error spikes
+   - Latency regressions
+   - Throughput drops
+   - Sequential workflows that hint at missing specs
+4. \`EvolutionPipeline\` emits \`intent.detected\` events and hands them to \`SpecGenerator\`.
+5. \`SpecSuggestionOrchestrator\` persists suggestions, triggers approval workflows, and—upon approval—writes JSON envelopes to \`packages/.../contracts/src/generated\`.
+
+---
+
+## 3. Spec Experiments & Rollouts
+
+1. Register spec experiments in \`SpecExperimentRegistry\` with control + variant bindings.
+2. Expose bucketed specs by attaching \`createSpecVariantResolver\` to \`HandlerCtx.specVariantResolver\` inside adapters.
+3. Record outcomes via \`SpecExperimentAdapter.trackOutcome()\` (latency + error metrics).
+4. \`SpecExperimentController\` uses guardrails from config and \`SpecExperimentAnalyzer\` to:
+   - Auto-rollback on error/latency breaches.
+   - Advance rollout stages (1% → 10% → 50% → 100%) when metrics stay green.
+
+---
+
+## 4. Data Models (Prisma)
+
+File: \`packages/libs/database/prisma/schema.prisma\`
+
+- \`SpecSuggestion\` – stores serialized suggestion payloads + statuses.
+- \`IntentSnapshot\` – captured detector output for auditing/training.
+- \`TrafficSnapshot\` – persisted production traffic (input/output/error blobs).
+- \`SpecExperiment\` / \`SpecExperimentMetric\` – rollout state + metrics for each variant.
+
+> Run \`bun database generate\` after pulling to refresh the Prisma client.
+
+---
+
+## 5. Golden Test Workflow
+
+1. Capture traffic via middleware or direct \`TrafficRecorder.record\`.
+2. Use the new CLI command to materialize suites:
+
+\`\`\`bash
+contractspec test generate \\
+  --operation billing.createInvoice \\
+  --output tests/billing.createInvoice.golden.test.ts \\
+  --runner-import ./tests/run-operation \\
+  --runner-fn runBillingCommand \\
+  --from-production \\
+  --days 7 \\
+  --sample-rate 0.05
+\`\`\`
+
+3. Generated files import your runner and assert against recorded outputs (or expected errors for negative paths).
+
+---
+
+## 6. Operational Notes
+
+- **Approvals**: By default, every suggestion still requires human approval. \`EvolutionConfig.autoApproveThreshold\` can be tuned per environment but should remain conservative (<0.3) until OverlaySpec tooling lands.
+- **Sampling**: Keep \`TrafficRecorder.sampleRate\` ≤ 0.05 in production to avoid sensitive payload storage; scrub PII through the \`sanitize\` callback before persistence.
+- **Rollouts**: Guardrails default to 5% error-rate and 750ms P99 latency. Override per experiment to match SLOs.
+
+---
+
+## 7. Next Steps
+
+1. Wire \`SpecExperimentAdapter.trackOutcome\` into adapters (REST, GraphQL, Workers) so every execution logs metrics automatically.
+2. Add a UI for reviewing \`SpecSuggestion\` objects alongside approval status.
+3. Expand \`TrafficRecorder\` to ship directly to the Prisma-backed store (currently in-memory by default).
+4. Integrate \`EvolutionPipeline\` events with the Regenerator to close the loop (auto-open proposals + attach evidence).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`
+}];
+a(t);
+
+//#endregion