@lssm/lib.contracts-spec 17.3.2

package/dist/knowledge/spec.js

@@ -0,0 +1,172 @@
+export{KnowledgeSpaceRegistry}from"./registry.js";export function makeKnowledgeSpaceKey(e){return`${e.key}.v${e.version}`}export const tech_contracts_knowledge_DocBlocks=[{id:"docs.tech.contracts.knowledge",title:"Knowledge Layer",summary:"The knowledge layer turns unstructured inputs (uploads, email threads,",kind:"reference",visibility:"public",route:"/docs/tech/contracts/knowledge",tags:["tech","contracts","knowledge"],body:`# Knowledge Layer
+
+The knowledge layer turns unstructured inputs (uploads, email threads,
+notes) into searchable context for agents and workflows. The Pocket
+Family Office vertical ships a minimal but production-ready stack that
+covers ingestion, indexing, querying, and guardrails.
+
+## Knowledge Spaces
+
+Knowledge is organised via \`KnowledgeSpaceSpec\` definitions under
+\`packages/libs/contracts-spec/src/knowledge/spaces\`:
+
+- \`knowledge.financial-docs\` \u2013 canonical invoices, bills, and contracts.
+- \`knowledge.email-threads\` \u2013 operational Gmail threads.
+- \`knowledge.support-faq\` / \`knowledge.product-canon\` \u2013 reusable shared
+  spaces available to any vertical.
+
+Each space defines:
+
+- Ownership metadata (domain, owners, stability tags).
+- Retention policy (TTL/archival).
+- Access policy (trust level, automation write permissions).
+- Indexing configuration (embedding model, chunk size, vector DB slot).
+
+## Sources & Bindings
+
+- \`KnowledgeSourceConfig\` records tenant-specific connections (bucket,
+  Gmail labels, sync cadence). Pocket Family Office provides sample
+  configs in \`knowledge/sources.sample.ts\`.
+- \`AppKnowledgeBinding\` associates spaces with workflows/agents and adds
+  per-tenant constraints (rate limits, scopes).
+
+Validation ensures that:
+
+- All referenced spaces exist in the registry.
+- At least one source is configured per binding.
+- External/ephemeral spaces trigger warnings for policy-sensitive flows.
+
+## Ingestion Pipeline
+
+Implemented in \`@lssm/lib.knowledge/ingestion\`:
+
+1. **DocumentProcessor** \u2013 pluggable MIME extractors producing
+   \`DocumentFragment\`s.
+2. **EmbeddingService** \u2013 batches fragments through an \`EmbeddingProvider\`
+   (Mistral in the reference implementation).
+3. **VectorIndexer** \u2013 upserts fragments into a \`VectorStoreProvider\`
+   (Qdrant in production, with in-memory implementations for tests) and
+   persists canonical \`payload.text\` content alongside fragment metadata
+   so retrieval and query flows can reuse indexed text directly.
+4. **Adapters**
+   - \`GmailIngestionAdapter\`: list threads \u2192 convert to raw documents \u2192
+     index.
+   - \`StorageIngestionAdapter\`: fetch object from storage provider \u2192
+     index.
+
+Background jobs (see \`@lssm/lib.jobs\`) orchestrate ingestion via
+Cloud Tasks / Pub/Sub or in-memory workers. Handlers:
+
+- \`storage-document-handler\` \u2013 resolves storage object + indexes.
+- \`gmail-sync-handler\` \u2013 syncs threads based on label/date filters.
+
+## Query Service
+
+\`KnowledgeQueryService\` performs retrieval-augmented generation:
+
+1. Embed the user query using the configured provider.
+2. Search the vector store for top-k matches.
+3. Compose prompts combining system instructions + indexed contextual
+   snippets from \`payload.text\` (falling back to legacy \`payload.content\`
+   when needed).
+4. Invoke the LLM provider (Mistral) and return the answer plus
+   references and token usage.
+
+The service is designed for tooling: workflows can execute it directly
+or through custom operations (see \`pfo.summary.generate\` contract).
+
+## Guardrails
+
+- Automation can only write to spaces where \`automationWritable\` is true.
+- Canonical spaces default to high trust; external/ephemeral spaces are
+  flagged during validation.
+- Provider-free knowledge flows must block stale runbook or low-confidence
+  evidence before action, and non-dry-run knowledge mutations require approval
+  or audit references before execution.
+- Telemetry captures query volumes per tenant + space.
+
+## Extending
+
+1. Define a new \`KnowledgeSpaceSpec\` with indexing/retention policies.
+2. Add sources pointing to storage providers or APIs.
+3. Register adapters if ingestion requires bespoke logic.
+4. Reference the space in blueprints (\`AppKnowledgeBinding\`) and update
+   workflows/agents accordingly.
+
+The Pocket Family Office tests (\`tests/pocket-family-office.test.ts\`)
+show how to wire the ingestion pipeline, index a document, and run an
+end-to-end knowledge query using in-memory providers.
+## Knowledge Spaces & Guardrails
+
+Knowledge surfaces (\`KnowledgeSpaceSpec\`) describe curated corpora that agents and workflows can consult. Tenant bindings (\`AppKnowledgeBinding\`) declare which spaces are active, who can use them, and optional usage constraints.
+
+### Binding recap
+
+- \`spaceKey\` / \`spaceVersion\`: pointer to the \`KnowledgeSpaceSpec\`
+- \`scope.workflows\` / \`scope.agents\`: explicit allow-lists for consumers
+- \`constraints.maxTokensPerQuery\` & \`constraints.maxQueriesPerMinute\`: throttling knobs for LLM-backed search
+- \`required\`: mark the binding as blocking (defaults to \`true\`)
+
+At runtime, \`ResolvedAppConfig.knowledge\` contains \`ResolvedKnowledge\` entries with the bound space, active sources, and the binding metadata above.
+
+### KnowledgeAccessGuard
+
+\`KnowledgeAccessGuard\` (\`@lssm/lib.knowledge/access/guard\`) centralises the access checks that must run before any workflow/agent reads or mutates a knowledge space.
+
+\`\`\`ts
+import { KnowledgeAccessGuard } from '@lssm/lib.knowledge/access/guard';
+
+const guard = new KnowledgeAccessGuard({
+  disallowWriteCategories: ['external', 'ephemeral'], // default
+  requireWorkflowBinding: true,
+  requireAgentBinding: false,
+});
+
+const result = guard.checkAccess(resolvedKnowledge, {
+  tenantId,
+  appId,
+  workflowName: 'order-processing',
+  operation: 'read', // or 'write' / 'search'
+}, resolvedAppConfig);
+
+if (!result.allowed) {
+  throw new Error(result.reason);
+}
+\`\`\`
+
+Key behaviours:
+
+- **Binding**: rejects access when the space is not present in the resolved tenant config.
+- **Category guardrails**: blocks writes to \`external\` and \`ephemeral\` spaces by default; allows reads but emits warnings for \`ephemeral\`.
+- **Workflow/agent scoping**: when \`requireWorkflowBinding\` or \`requireAgentBinding\` is enabled, only explicitly authorised consumers may access the space.
+
+Use the guard inside workflow operations or agent resolvers to guarantee multi-tenant isolation and honour data governance rules.
+
+## Agent memory tools and ephemeral spaces
+
+Ephemeral spaces (\`category: 'ephemeral'\`) are the canonical home for agent memory storage (scratchpads, session context, drafts). Agent memory tools (Anthropic \`memory_20250818\`, custom operation-backed) can use ephemeral spaces as storage when configured with \`memoryTools.spaceKey\`.
+
+### Enabling agent memory writes
+
+By default, \`KnowledgeAccessGuard\` blocks writes to ephemeral spaces (\`disallowWriteCategories: ['external', 'ephemeral']\`). To allow agent memory tools to write:
+
+1. Configure \`disallowWriteCategories: ['external']\` (allow ephemeral writes).
+2. Ensure \`AppKnowledgeBinding.scope.agents\` includes the agent key when using knowledge-backed storage.
+3. Set \`requireAgentBinding: true\` so only explicitly bound agents can write.
+
+See \`@lssm/lib.ai-agent\` memory tools and \`AgentMemoryStore\` for implementation details.
+`},{id:"docs.tech.contracts.knowledge-provider-backed",title:"Provider-backed knowledge",summary:"Provider-backed knowledge syncs Gmail and Google Drive through explicit provider delta and mutation governance evidence.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/knowledge-provider-backed",tags:["tech","contracts","knowledge","integrations"],body:`# Provider-backed knowledge
+
+Provider-backed knowledge starts from the same \`KnowledgeSpaceSpec\` and
+\`KnowledgeSourceConfig\` surfaces, then adds explicit provider delta and
+mutation governance evidence before runtime sync begins.
+
+Gmail and Google Drive ingestion should persist \`ProviderDeltaSyncState\` per
+source so leases, cursors, webhook channel expiry, provider event IDs,
+dedupe/idempotency keys, replay checkpoints, and tombstones survive retries.
+
+External mutations should route through
+\`knowledge.mutation.evaluateGovernance\` or
+\`@lssm/lib.knowledge/governance\` so dry-runs, approval refs,
+idempotency keys, audit evidence, and outbound-send gates are recorded before
+provider writes happen.`}];

package/dist/llm/exporters.d.ts

@@ -0,0 +1,75 @@
+/**
+ * LLM Export Functions
+ *
+ * Provides multi-format markdown export for specs, features, presentations,
+ * and other ContractSpec artifacts for LLM consumption.
+ */
+import type { AnySchemaModel } from '@lssm/lib.schema';
+import type { DocBlock } from '../docs/types.js';
+import type { EventSpec } from '../events.js';
+import type { FeatureModuleSpec } from '../features/index.js';
+import type { AnyOperationSpec } from '../operations/index.js';
+import type { OperationSpecRegistry } from '../operations/registry.js';
+import type { PresentationRegistry } from '../presentations/index.js';
+import type { PresentationSpec } from '../presentations/index.js';
+import type { VisualScenarioRegistry } from '../visual-scenarios/registry.js';
+import type { VisualizationRegistry, VisualizationSpec } from '../visualizations/index.js';
+import type { FeatureExportOptions, FeatureExportResult, SpecExportOptions, SpecExportResult } from './types.js';
+/**
+ * Export a single spec to context-focused markdown.
+ * Includes: goal, context, description, acceptance scenarios.
+ * Best for: Understanding what the spec does, providing context to LLMs.
+ */
+export declare function operationSpecToContextMarkdown(spec: AnyOperationSpec): string;
+/**
+ * Export a single spec to full markdown with all details.
+ * Includes: all fields, I/O schemas, policy, events, examples.
+ * Best for: Complete documentation, implementation reference.
+ */
+export declare function operationSpecToFullMarkdown(spec: AnyOperationSpec, options?: Partial<SpecExportOptions>): string;
+/**
+ * Export a single spec as an actionable agent prompt.
+ * Includes: instructions, full spec, expected output format.
+ * Best for: Directly feeding to coding agents for implementation.
+ */
+export declare function operationSpecToAgentPrompt(spec: AnyOperationSpec, options?: {
+    taskType?: 'implement' | 'test' | 'refactor' | 'review';
+    existingCode?: string;
+}): string;
+/**
+ * Export a feature module to markdown.
+ * Includes all related specs, events, and presentations.
+ */
+export declare function featureToMarkdown(feature: FeatureModuleSpec, deps?: {
+    specs?: OperationSpecRegistry;
+    presentations?: PresentationRegistry;
+    visualizations?: VisualizationRegistry;
+    visualScenarios?: VisualScenarioRegistry;
+}, options?: Partial<FeatureExportOptions>): string;
+/**
+ * Export a presentation descriptor to markdown.
+ */
+export declare function presentationToMarkdown(presentation: PresentationSpec): string;
+export declare function visualizationToMarkdown(visualization: VisualizationSpec): string;
+/**
+ * Export an event spec to markdown.
+ */
+export declare function eventToMarkdown(event: EventSpec<AnySchemaModel>): string;
+/**
+ * Export a DocBlock to markdown (already markdown, but formatted consistently).
+ */
+export declare function docBlockToMarkdown(doc: DocBlock): string;
+/**
+ * Export a spec with a specific format.
+ * Convenience function that wraps the format-specific functions.
+ */
+export declare function exportSpec(spec: AnyOperationSpec, options?: Partial<SpecExportOptions>): SpecExportResult;
+/**
+ * Export a feature with a specific format.
+ */
+export declare function exportFeature(feature: FeatureModuleSpec, deps?: {
+    specs?: OperationSpecRegistry;
+    presentations?: PresentationRegistry;
+    visualizations?: VisualizationRegistry;
+    visualScenarios?: VisualScenarioRegistry;
+}, options?: Partial<FeatureExportOptions>): FeatureExportResult;

package/dist/llm/exporters.js

@@ -0,0 +1,9 @@
+import{jsonSchemaForSpec as a}from"../jsonschema.js";import{isEmitDeclRef as l}from"../operations/index.js";const r={format:"full",includeSchemas:!0,includeScenarios:!0,includeExamples:!0,includePolicy:!0,includeSideEffects:!0};const c={...r,includeRelatedSpecs:!0,includeRelatedEvents:!0,includeRelatedPresentations:!0,includeRelatedVisualizations:!0,includeRelatedVisualScenarios:!0};export function operationSpecToContextMarkdown(e){const n=e.meta,t=[];t.push(`# ${n.key} (v${n.version})`);t.push("");t.push(`> ${n.description}`);t.push("");t.push(`**Type:** ${n.kind} | **Stability:** ${n.stability}`);t.push("");t.push("## Goal");t.push("");t.push(n.goal);t.push("");t.push("## Context");t.push("");t.push(n.context);t.push("");if(e.acceptance?.scenarios?.length){t.push("## Acceptance Criteria");t.push("");for(const p of e.acceptance.scenarios){t.push(`### ${p.key}`);t.push("");t.push("**Given:**");for(const s of p.given)t.push(`- ${s}`);t.push("");t.push("**When:**");for(const s of p.when)t.push(`- ${s}`);t.push("");t.push("**Then:**");for(const s of p.then)t.push(`- ${s}`);t.push("")}}return t.join(`
+`)}export function operationSpecToFullMarkdown(e,n={}){const t={...r,...n},p=e.meta,s=[];s.push(`# ${p.key}.v${p.version}`);s.push("");s.push(`> ${p.description}`);s.push("");s.push("## Metadata");s.push("");s.push("| Field | Value |");s.push("|-------|-------|");s.push(`| Kind | ${p.kind} |`);s.push(`| Stability | ${p.stability} |`);s.push(`| Owners | ${p.owners.join(", ")} |`);s.push(`| Tags | ${p.tags.join(", ")} |`);s.push("");s.push("## Goal");s.push("");s.push(p.goal);s.push("");s.push("## Context");s.push("");s.push(p.context);s.push("");if(t.includeSchemas){s.push("## Input/Output");s.push("");if(e.io.input){s.push("### Input Schema");s.push("");s.push("```json");try{const i=a(e);s.push(JSON.stringify(i.input??{},null,2))}catch{s.push("// Schema generation not available")}s.push("```");s.push("")}s.push("### Output Schema");s.push("");s.push("```json");try{const i=a(e);s.push(JSON.stringify(i.output??{},null,2))}catch{s.push("// Schema generation not available")}s.push("```");s.push("");if(e.io.errors&&Object.keys(e.io.errors).length){s.push("### Error Codes");s.push("");s.push("| Code | HTTP | Description | When |");s.push("|------|------|-------------|------|");for(const[i,o]of Object.entries(e.io.errors))s.push(`| \`${i}\` | ${o.http??400} | ${o.description} | ${o.when} |`);s.push("")}}if(t.includePolicy){s.push("## Policy");s.push("");s.push(`- **Auth Required:** ${e.policy.auth}`);s.push(`- **Idempotent:** ${e.policy.idempotent??p.kind==="query"}`);if(e.policy.rateLimit)s.push(`- **Rate Limit:** ${e.policy.rateLimit.rpm} rpm per ${e.policy.rateLimit.key}`);if(e.policy.flags?.length)s.push(`- **Feature Flags:** ${e.policy.flags.join(", ")}`);if(e.policy.pii?.length)s.push(`- **PII Fields:** ${e.policy.pii.join(", ")}`);if(e.policy.escalate)s.push(`- **Escalation:** ${e.policy.escalate}`);s.push("")}if(t.includeSideEffects&&e.sideEffects){if(e.sideEffects.emits?.length){s.push("## Events Emitted");s.push("");for(const i of e.sideEffects.emits)if(l(i))s.push(`- \`${i.ref.key}.v${i.ref.version}\` \u2014 ${i.when}`);else s.push(`- \`${i.key}.v${i.version}\` \u2014 ${i.when}`);s.push("")}if(e.sideEffects.analytics?.length){s.push("## Analytics Events");s.push("");for(const i of e.sideEffects.analytics)s.push(`- ${i}`);s.push("")}}if(t.includeScenarios&&e.acceptance?.scenarios?.length){s.push("## Acceptance Scenarios");s.push("");for(const i of e.acceptance.scenarios){s.push(`### ${i.key}`);s.push("");s.push("**Given:**");for(const o of i.given)s.push(`- ${o}`);s.push("");s.push("**When:**");for(const o of i.when)s.push(`- ${o}`);s.push("");s.push("**Then:**");for(const o of i.then)s.push(`- ${o}`);s.push("")}}if(t.includeExamples&&e.acceptance?.examples?.length){s.push("## Examples");s.push("");for(const i of e.acceptance.examples){s.push(`### ${i.key}`);s.push("");s.push("**Input:**");s.push("```json");s.push(JSON.stringify(i.input,null,2));s.push("```");s.push("");s.push("**Output:**");s.push("```json");s.push(JSON.stringify(i.output,null,2));s.push("```");s.push("")}}if(e.transport){s.push("## Transport Configuration");s.push("");if(e.transport.rest)s.push(`- **REST:** ${e.transport.rest.method??"POST"} ${e.transport.rest.path??"auto"}`);if(e.transport.gql)s.push(`- **GraphQL:** ${e.transport.gql.field??"auto"}`);if(e.transport.mcp)s.push(`- **MCP Tool:** ${e.transport.mcp.toolName??"auto"}`);s.push("")}return s.join(`
+`)}export function operationSpecToAgentPrompt(e,n){const t=n?.taskType??"implement",p=e.meta,s=[],i={implement:"Implement",test:"Write tests for",refactor:"Refactor",review:"Review"}[t];s.push(`# Task: ${i} ${p.key}.v${p.version}`);s.push("");s.push("## Context");s.push("");s.push(`You are working on a ContractSpec-driven codebase. This spec defines a ${p.kind} operation.`);s.push("");s.push(`**Goal:** ${p.goal}`);s.push("");s.push(`**Background:** ${p.context}`);s.push("");s.push("## Specification");s.push("");s.push(operationSpecToFullMarkdown(e));s.push("");s.push("## Instructions");s.push("");if(t==="implement"){s.push("Implement this specification following these requirements:");s.push("");s.push("1. **Type Safety**: Use TypeScript with strict typing. No `any` types.");s.push("2. **Input Validation**: Validate input against the schema before processing.");s.push("3. **Error Handling**: Implement all error cases defined in the spec.");s.push("4. **Events**: Emit events as specified in sideEffects.emits.");s.push("5. **Policy**: Respect auth, rate limits, and feature flags.");s.push("6. **Idempotency**: "+(e.policy.idempotent?"This operation MUST be idempotent.":"This operation may have side effects."));s.push("");if(e.policy.pii?.length){s.push("**PII Handling**: The following fields contain PII and must be handled carefully:");for(const o of e.policy.pii)s.push(`- ${o}`);s.push("")}}else if(t==="test"){s.push("Write comprehensive tests for this specification:");s.push("");s.push("1. Test all acceptance scenarios defined in the spec.");s.push("2. Test all error cases with appropriate assertions.");s.push("3. Test edge cases and boundary conditions.");s.push("4. Verify events are emitted correctly.");s.push('5. Use descriptive test names following the pattern: "should [behavior] when [condition]"');s.push("")}else if(t==="refactor"){s.push("Refactor this implementation while preserving all behavior:");s.push("");s.push("1. Maintain compliance with the specification.");s.push("2. Improve code clarity and maintainability.");s.push("3. Reduce complexity where possible.");s.push("4. Ensure all existing tests still pass.");s.push("")}else if(t==="review"){s.push("Review this implementation against the specification:");s.push("");s.push("1. Verify input/output types match the schema.");s.push("2. Check all error cases are handled.");s.push("3. Verify events are emitted as specified.");s.push("4. Check policy compliance (auth, rate limits).");s.push("5. Report any deviations from the spec.");s.push("")}if(n?.existingCode){s.push("## Existing Code");s.push("");s.push("```typescript");s.push(n.existingCode);s.push("```");s.push("")}s.push("## Expected Output");s.push("");if(t==="implement"||t==="refactor"){s.push("Provide a complete TypeScript implementation. Include:");s.push("- Type definitions for input/output");s.push("- Handler function with proper error handling");s.push("- JSDoc comments explaining the implementation")}else if(t==="test")s.push("Provide a complete test file using the testing framework available (prefer Vitest).");else if(t==="review"){s.push("Provide a structured review with:");s.push("- Compliance status (pass/fail for each requirement)");s.push("- Issues found with severity (error/warning/info)");s.push("- Suggestions for improvement")}s.push("");return s.join(`
+`)}export function featureToMarkdown(e,n,t={}){const p={...c,...t},s=e.meta,i=[];i.push(`# Feature: ${s.title??s.key}`);i.push("");if(s.description){i.push(`> ${s.description}`);i.push("")}i.push("## Overview");i.push("");i.push(`- **Key:** \`${s.key}\``);i.push(`- **Stability:** ${s.stability}`);i.push(`- **Owners:** ${s.owners.join(", ")}`);if(s.tags?.length)i.push(`- **Tags:** ${s.tags.join(", ")}`);i.push("");if(e.operations?.length){i.push("## Operations");i.push("");i.push("| Name | Version | Type |");i.push("|------|---------|------|");for(const o of e.operations){const h=n?.specs?.get(o.key,o.version)?.meta.kind??"unknown";i.push(`| ${o.key} | v${o.version} | ${h} |`)}i.push("");if(p.includeRelatedSpecs&&n?.specs){i.push("### Operation Details");i.push("");for(const o of e.operations){const u=n.specs.get(o.key,o.version);if(u){i.push("---");i.push("");i.push(operationSpecToFullMarkdown(u,p))}}}}if(e.events?.length){i.push("## Events");i.push("");i.push("| Name | Version |");i.push("|------|---------|");for(const o of e.events)i.push(`| ${o.key} | v${o.version} |`);i.push("")}if(e.presentations?.length){i.push("## Presentations");i.push("");i.push("| Name | Version |");i.push("|------|---------|");for(const o of e.presentations)i.push(`| ${o.key} | v${o.version} |`);i.push("");if(p.includeRelatedPresentations&&n?.presentations){i.push("### Presentation Details");i.push("");for(const o of e.presentations){const u=n.presentations.get(o.key,o.version);if(u){i.push(`#### ${o.key}.v${o.version}`);i.push("");i.push(`- **Type:** ${u.source.type}`);if(u.source.type==="component")i.push(`- **Component:** ${u.source.componentKey}`);i.push("")}}}}if(e.visualizations?.length){i.push("## Visualizations");i.push("");i.push("| Name | Version | Kind |");i.push("|------|---------|------|");for(const o of e.visualizations){const u=n?.visualizations?.get(o.key,o.version);i.push(`| ${o.key} | v${o.version} | ${u?.visualization.kind??"unknown"} |`)}i.push("");if(p.includeRelatedVisualizations&&n?.visualizations){i.push("### Visualization Details");i.push("");for(const o of e.visualizations){const u=n.visualizations.get(o.key,o.version);if(u){i.push(visualizationToMarkdown(u));i.push("")}}}}if(e.visualScenarios?.length){i.push("## Visual Scenarios");i.push("");i.push("| Name | Version | Surface | Cases |");i.push("|------|---------|---------|-------|");for(const o of e.visualScenarios){const u=n?.visualScenarios?.get(o.key,o.version);i.push(`| ${o.key} | v${o.version} | ${u?.surface??"unknown"} | ${u?.cases.length??"unknown"} |`)}i.push("")}if(e.capabilities){if(e.capabilities.provides?.length){i.push("## Capabilities Provided");i.push("");for(const o of e.capabilities.provides)i.push(`- \`${o.key}.v${o.version}\``);i.push("")}if(e.capabilities.requires?.length){i.push("## Capabilities Required");i.push("");for(const o of e.capabilities.requires)i.push(`- \`${o.key}\`${o.version?`.v${o.version}`:""} (${o.optional?"optional":"required"})`);i.push("")}}return i.join(`
+`)}export function presentationToMarkdown(e){const n=e.meta,t=[];t.push(`# Presentation: ${n.key}.v${n.version}`);t.push("");if(n.description){t.push(`> ${n.description}`);t.push("")}t.push("## Metadata");t.push("");t.push(`- **Name:** ${n.key}`);t.push(`- **Version:** ${n.version}`);if(n.stability)t.push(`- **Stability:** ${n.stability}`);if(n.owners?.length)t.push(`- **Owners:** ${n.owners.join(", ")}`);if(n.tags?.length)t.push(`- **Tags:** ${n.tags.join(", ")}`);t.push("");t.push("## Source");t.push("");t.push(`- **Type:** ${e.source.type}`);if(e.source.type==="component"){t.push(`- **Framework:** ${e.source.framework}`);t.push(`- **Component Key:** ${e.source.componentKey}`)}t.push("");t.push("## Supported Targets");t.push("");for(const p of e.targets)t.push(`- ${p}`);t.push("");if(e.policy){t.push("## Policy");t.push("");if(e.policy.flags?.length)t.push(`- **Feature Flags:** ${e.policy.flags.join(", ")}`);if(e.policy.pii?.length)t.push(`- **PII Fields:** ${e.policy.pii.join(", ")}`);t.push("")}return t.join(`
+`)}export function visualizationToMarkdown(e){const{meta:n,visualization:t}=e,p=[];p.push(`# Visualization: ${n.key}.v${n.version}`);p.push("");p.push(`> ${n.description}`);p.push("");p.push(`- **Kind:** ${t.kind}`);if("variant"in t&&t.variant)p.push(`- **Variant:** ${t.variant}`);p.push(`- **Goal:** ${n.goal}`);p.push(`- **Context:** ${n.context}`);p.push("");if(t.dimensions?.length){p.push("## Dimensions");p.push("");for(const s of t.dimensions)p.push(`- \`${s.key}\` (${s.type??"category"}) -> ${s.dataPath}`);p.push("")}if(t.measures?.length){p.push("## Measures");p.push("");for(const s of t.measures)p.push(`- \`${s.key}\` -> ${s.dataPath}`);p.push("")}return p.join(`
+`)}export function eventToMarkdown(e){const n=[];n.push(`# Event: ${e.meta.key}.v${e.meta.version}`);n.push("");n.push("## Metadata");n.push("");n.push(`- **Name:** ${e.meta.key}`);n.push(`- **Version:** ${e.meta.version}`);if(e.meta.description)n.push(`- **Description:** ${e.meta.description}`);n.push("");n.push("## Payload Schema");n.push("");n.push("```json");try{const t=e.payload.getZod();if("shape"in t&&t.shape){const p=t.shape,s=Object.keys(p);n.push(JSON.stringify({fields:s},null,2))}else n.push("// Payload schema available at runtime")}catch{n.push("// Schema details available at runtime")}n.push("```");n.push("");return n.join(`
+`)}export function docBlockToMarkdown(e){const n=[];n.push(`# ${e.title}`);n.push("");if(e.summary){n.push(`> ${e.summary}`);n.push("")}n.push("## Metadata");n.push("");n.push(`- **ID:** ${e.id}`);n.push(`- **Kind:** ${e.kind??"reference"}`);n.push(`- **Visibility:** ${e.visibility??"public"}`);if(e.tags?.length)n.push(`- **Tags:** ${e.tags.join(", ")}`);if(e.owners?.length)n.push(`- **Owners:** ${e.owners.join(", ")}`);if(e.domain)n.push(`- **Domain:** ${e.domain}`);n.push("");n.push("## Content");n.push("");n.push(e.body);n.push("");if(e.links?.length){n.push("## Related Links");n.push("");for(const t of e.links)n.push(`- [${t.label}](${t.href})`);n.push("")}return n.join(`
+`)}export function exportSpec(e,n={}){const t=n.format??"full";let p;switch(t){case"context":p=operationSpecToContextMarkdown(e);break;case"prompt":p=operationSpecToAgentPrompt(e);break;case"full":default:p=operationSpecToFullMarkdown(e,n);break}return{spec:e,markdown:p,format:t,meta:{specName:e.meta.key,specVersion:e.meta.version,exportedAt:new Date().toISOString(),wordCount:p.split(/\s+/).length}}}export function exportFeature(e,n,t={}){const p=t.format??"full",s=featureToMarkdown(e,n,t);return{feature:e,markdown:s,format:p,includedSpecs:e.operations?.map((i)=>`${i.key}.v${i.version}`)??[],includedEvents:e.events?.map((i)=>`${i.key}.v${i.version}`)??[],includedPresentations:e.presentations?.map((i)=>`${i.key}.v${i.version}`)??[],includedVisualizations:e.visualizations?.map((i)=>`${i.key}.v${i.version}`)??[],includedVisualScenarios:e.visualScenarios?.map((i)=>`${i.key}.v${i.version}`)??[]}}

package/dist/llm/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * LLM Integration Module
+ *
+ * Provides tools for exporting ContractSpec artifacts to LLM-friendly formats,
+ * generating implementation prompts for AI coding agents, and verifying
+ * implementations against specifications.
+ *
+ * @module @lssm/lib.contracts-spec/llm
+ */
+export { docBlockToMarkdown, eventToMarkdown, exportFeature, exportSpec, featureToMarkdown, operationSpecToAgentPrompt, operationSpecToContextMarkdown, operationSpecToFullMarkdown, presentationToMarkdown, } from './exporters.js';
+export { AGENT_SYSTEM_PROMPTS, formatPlanForAgent, generateFixViolationsPrompt, generateImplementationPlan, generateImplementationPrompt, generateReviewPrompt, generateTestPrompt, generateVerificationPrompt, } from './prompts.js';
+export type { AgentPrompt, AgentType, BatchExportOptions, ExportableItem, FeatureExportOptions, FeatureExportResult, FeatureLookup, ImplementationPlan, LLMExportFormat, SpecExportOptions, SpecExportResult, SpecLookup, VerificationIssue, VerificationReport, VerificationTier, } from './types.js';

package/dist/llm/index.js

@@ -0,0 +1 @@
+export{docBlockToMarkdown,eventToMarkdown,exportFeature,exportSpec,featureToMarkdown,operationSpecToAgentPrompt,operationSpecToContextMarkdown,operationSpecToFullMarkdown,presentationToMarkdown}from"./exporters.js";export{AGENT_SYSTEM_PROMPTS,formatPlanForAgent,generateFixViolationsPrompt,generateImplementationPlan,generateImplementationPrompt,generateReviewPrompt,generateTestPrompt,generateVerificationPrompt}from"./prompts.js";

package/dist/llm/prompts.d.ts

@@ -0,0 +1,53 @@
+/**
+ * LLM Prompt Templates
+ *
+ * Pre-built prompt templates for different agent types and tasks.
+ * These prompts are designed to guide AI coding agents in implementing,
+ * testing, and verifying ContractSpec-based code.
+ */
+import type { AnyOperationSpec } from '../operations/index.js';
+import type { AgentPrompt, AgentType, ImplementationPlan } from './types.js';
+/**
+ * System prompts for different agent types.
+ */
+export declare const AGENT_SYSTEM_PROMPTS: Record<AgentType, string>;
+/**
+ * Generate an implementation prompt for a specific agent type.
+ */
+export declare function generateImplementationPrompt(spec: AnyOperationSpec, agent: AgentType, options?: {
+    existingCode?: string;
+    targetPath?: string;
+}): AgentPrompt;
+/**
+ * Generate a test generation prompt.
+ */
+export declare function generateTestPrompt(spec: AnyOperationSpec, agent: AgentType, options?: {
+    implementationCode?: string;
+    testFramework?: 'vitest' | 'jest' | 'bun';
+}): AgentPrompt;
+/**
+ * Generate a code review prompt.
+ */
+export declare function generateReviewPrompt(spec: AnyOperationSpec, agent: AgentType, implementationCode: string): AgentPrompt;
+/**
+ * Generate a verification prompt for AI-powered semantic review.
+ */
+export declare function generateVerificationPrompt(spec: AnyOperationSpec, implementationCode: string): AgentPrompt;
+/**
+ * Generate a feature implementation plan.
+ */
+export declare function generateImplementationPlan(spec: AnyOperationSpec, options?: {
+    projectRoot?: string;
+    existingFiles?: string[];
+}): ImplementationPlan;
+/**
+ * Format an implementation plan for a specific agent.
+ */
+export declare function formatPlanForAgent(plan: ImplementationPlan, agent: AgentType): AgentPrompt;
+/**
+ * Generate a fix violations prompt after verification.
+ */
+export declare function generateFixViolationsPrompt(spec: AnyOperationSpec, implementationCode: string, violations: {
+    message: string;
+    suggestion?: string;
+}[]): AgentPrompt;

package/dist/llm/prompts.js

@@ -0,0 +1,237 @@
+import{operationSpecToAgentPrompt as u,operationSpecToFullMarkdown as l}from"./exporters.js";export const AGENT_SYSTEM_PROMPTS={"claude-code":`You are an expert TypeScript developer working with ContractSpec, a spec-first development framework.
+
+Your code follows these principles:
+- Type-safe with comprehensive TypeScript types (no \`any\`)
+- Well-documented with JSDoc comments
+- Production-ready with proper error handling
+- Following SOLID principles and clean code practices
+- Modular and testable
+
+When implementing specs:
+1. Validate input against the schema before processing
+2. Handle all error cases defined in the spec
+3. Emit events as specified in sideEffects
+4. Respect policy constraints (auth, rate limits, PII handling)
+5. Follow the acceptance scenarios as your implementation guide
+
+Generate clean, idiomatic TypeScript that exactly matches the specification.`,"cursor-cli":`You are implementing features for a ContractSpec-driven codebase.
+
+ContractSpec is a spec-first framework where specifications define:
+- Operations (commands and queries) with typed I/O
+- Events that operations emit
+- Presentations for UI components
+- Features that group related specs
+
+When working with specs:
+- Read the spec carefully before implementing
+- Match the input/output types exactly
+- Implement all error cases
+- Follow the acceptance scenarios
+- Respect policy constraints
+
+Use the project's existing patterns and conventions.`,"generic-mcp":`You are a code generation assistant working with ContractSpec specifications.
+
+ContractSpec specs define:
+- meta: name, version, kind (command/query), description, goal, context
+- io: input schema, output schema, error definitions
+- policy: auth level, rate limits, feature flags, PII handling
+- sideEffects: events to emit, analytics, audit
+- acceptance: scenarios and examples
+
+Your task is to generate or modify code that complies with the given specification.
+Follow the spec exactly and handle all defined cases.`};export function generateImplementationPrompt(e,n,i){const t=AGENT_SYSTEM_PROMPTS[n],r=l(e);let o;if(n==="claude-code")o=`## Implementation Task
+
+Implement the following ContractSpec operation:
+
+${r}
+
+${i?.targetPath?`**Target file:** \`${i.targetPath}\`
+`:""}
+${i?.existingCode?`**Existing code to modify:**
+\`\`\`typescript
+${i.existingCode}
+\`\`\`
+`:""}
+
+Generate a complete, production-ready TypeScript implementation that:
+1. Exports a handler function matching the spec signature
+2. Validates input using the schema
+3. Handles all defined error cases
+4. Emits events as specified
+5. Includes JSDoc documentation
+
+Provide ONLY the TypeScript code.`;else if(n==="cursor-cli")o=`Implement this ContractSpec operation.
+
+${r}
+
+${i?.targetPath?`Target: ${i.targetPath}
+`:""}
+
+Requirements:
+- TypeScript with strict types
+- Handle all error cases
+- Emit specified events
+- Follow acceptance scenarios`;else o=u(e,{taskType:"implement",existingCode:i?.existingCode});return{agent:n,systemPrompt:t,taskPrompt:o}}export function generateTestPrompt(e,n,i){const t=i?.testFramework??"vitest",o=`## Test Generation Task
+
+Generate comprehensive tests for this specification:
+
+${l(e)}
+
+${i?.implementationCode?`**Implementation:**
+\`\`\`typescript
+${i.implementationCode}
+\`\`\`
+`:""}
+
+**Test Framework:** ${t}
+
+Generate tests that:
+1. Cover all acceptance scenarios from the spec
+2. Test all defined error cases
+3. Verify input validation
+4. Check event emissions
+5. Test edge cases
+
+Use descriptive test names: "should [behavior] when [condition]"
+
+Provide a complete test file.`;return{agent:n,systemPrompt:AGENT_SYSTEM_PROMPTS[n],taskPrompt:o}}export function generateReviewPrompt(e,n,i){const r=`## Code Review Task
+
+Review this implementation against its specification:
+
+**Specification:**
+${l(e)}
+
+**Implementation:**
+\`\`\`typescript
+${i}
+\`\`\`
+
+Provide a structured review:
+
+### Compliance Check
+- [ ] Input types match spec
+- [ ] Output types match spec
+- [ ] All error cases handled
+- [ ] Events emitted correctly
+- [ ] Policy constraints respected
+
+### Issues Found
+List any issues with severity (error/warning/info)
+
+### Suggestions
+List improvements and recommendations
+
+Be thorough and precise. Focus on spec compliance first, then code quality.`;return{agent:n,systemPrompt:AGENT_SYSTEM_PROMPTS[n],taskPrompt:r}}export function generateVerificationPrompt(e,n){return{agent:"generic-mcp",taskPrompt:`## Semantic Verification Task
+
+Verify that this implementation fulfills the specification's intent.
+
+**Specification:**
+${l(e)}
+
+**Implementation:**
+\`\`\`typescript
+${n}
+\`\`\`
+
+Analyze and respond with JSON:
+
+\`\`\`json
+{
+  "passed": true/false,
+  "score": 0-100,
+  "compliance": {
+    "inputTypes": { "match": true/false, "issues": [] },
+    "outputTypes": { "match": true/false, "issues": [] },
+    "errorHandling": { "coverage": "full/partial/none", "missing": [] },
+    "eventEmission": { "correct": true/false, "issues": [] },
+    "policyCompliance": { "auth": true/false, "rateLimit": true/false, "pii": true/false }
+  },
+  "scenarios": [
+    { "name": "scenario name", "covered": true/false, "notes": "" }
+  ],
+  "issues": [
+    { "severity": "error/warning/info", "category": "type/export/import/scenario/error_handling/semantic", "message": "", "suggestion": "" }
+  ],
+  "summary": "Brief summary of verification results"
+}
+\`\`\``}}export function generateImplementationPlan(e,n){const i=e.meta,t=[],r=n?.projectRoot??"src",o=i.key.replace(/\./g,"/");if(i.kind==="command"||i.kind==="query")t.push({path:`${r}/${o}/handler.ts`,purpose:"Main handler implementation",type:"create"},{path:`${r}/${o}/types.ts`,purpose:"Type definitions",type:"create"},{path:`${r}/${o}/handler.test.ts`,purpose:"Handler tests",type:"create"});const s=[];let c=1;s.push({order:c++,title:"Define Types",description:"Create TypeScript types for input, output, and internal data structures",acceptanceCriteria:["Input type matches spec schema exactly","Output type matches spec schema exactly","Error types defined for all error cases"]});s.push({order:c++,title:"Implement Input Validation",description:"Add validation logic for the input payload",acceptanceCriteria:["All required fields are validated","Type constraints are enforced","Validation errors return appropriate error codes"]});s.push({order:c++,title:"Implement Core Logic",description:"Implement the main business logic of the operation",acceptanceCriteria:e.acceptance?.scenarios?.map((a)=>a.key)??["Operation completes successfully for valid input"]});if(e.io.errors&&Object.keys(e.io.errors).length>0)s.push({order:c++,title:"Implement Error Handling",description:"Handle all defined error cases",acceptanceCriteria:Object.entries(e.io.errors).map(([a,d])=>`Handle ${a}: ${d.when}`)});if(e.sideEffects?.emits?.length)s.push({order:c++,title:"Implement Event Emission",description:"Emit events as specified",acceptanceCriteria:e.sideEffects.emits.map((a)=>{if("ref"in a)return`Emit ${a.ref.key}.v${a.ref.version} when ${a.when}`;return`Emit ${a.key}.v${a.version} when ${a.when}`})});s.push({order:c++,title:"Write Tests",description:"Create comprehensive test suite",acceptanceCriteria:["All acceptance scenarios covered","All error cases tested","Edge cases handled","Events verified"]});const p={policy:[],security:[],pii:[]};p.policy.push(`Auth level: ${e.policy.auth}`);if(e.policy.idempotent!==void 0)p.policy.push(`Idempotent: ${e.policy.idempotent}`);if(e.policy.rateLimit)p.policy.push(`Rate limit: ${e.policy.rateLimit.rpm} rpm per ${e.policy.rateLimit.key}`);if(e.policy.flags?.length)p.policy.push(`Feature flags required: ${e.policy.flags.join(", ")}`);if(e.policy.escalate)p.security.push(`Escalation required: ${e.policy.escalate}`);if(e.policy.pii?.length)p.pii=e.policy.pii;const m=["Input validation works for all cases","Output matches expected schema","All error cases return correct codes","Events are emitted with correct payloads","Auth requirements are enforced","Rate limiting is applied (if applicable)","PII fields are handled correctly","All acceptance scenarios pass","Tests provide adequate coverage"];return{target:{type:"spec",key:i.key,version:i.version},context:{goal:i.goal,description:i.description,background:i.context},specMarkdown:l(e),fileStructure:t,steps:s,constraints:p,verificationChecklist:m}}export function formatPlanForAgent(e,n){let i;if(n==="claude-code")i=`## Implementation Plan: ${e.target.key}.v${e.target.version}
+
+### Context
+**Goal:** ${e.context.goal}
+
+**Background:** ${e.context.background}
+
+### Specification
+${e.specMarkdown}
+
+### File Structure
+${e.fileStructure.map((t)=>`- \`${t.path}\` (${t.type}): ${t.purpose}`).join(`
+`)}
+
+### Implementation Steps
+${e.steps.map((t)=>`
+#### Step ${t.order}: ${t.title}
+${t.description}
+
+**Acceptance Criteria:**
+${t.acceptanceCriteria.map((r)=>`- [ ] ${r}`).join(`
+`)}
+`).join(`
+`)}
+
+### Constraints
+${e.constraints.policy.length?`**Policy:**
+${e.constraints.policy.map((t)=>`- ${t}`).join(`
+`)}
+`:""}
+${e.constraints.security.length?`**Security:**
+${e.constraints.security.map((t)=>`- ${t}`).join(`
+`)}
+`:""}
+${e.constraints.pii.length?`**PII Handling:**
+${e.constraints.pii.map((t)=>`- ${t}`).join(`
+`)}
+`:""}
+
+### Verification Checklist
+${e.verificationChecklist.map((t)=>`- [ ] ${t}`).join(`
+`)}
+
+Implement this plan step by step.`;else if(n==="cursor-cli")i=`# ${e.target.key}.v${e.target.version}
+
+${e.context.goal}
+
+## Spec
+${e.specMarkdown}
+
+## Files to create
+${e.fileStructure.map((t)=>`${t.type}: ${t.path}`).join(`
+`)}
+
+## Steps
+${e.steps.map((t)=>`${t.order}. ${t.title}`).join(`
+`)}`;else i=`Implementation plan for ${e.target.key}.v${e.target.version}
+
+${e.specMarkdown}
+
+Steps:
+${e.steps.map((t)=>`${t.order}. ${t.title}: ${t.description}`).join(`
+`)}`;return{agent:n,systemPrompt:AGENT_SYSTEM_PROMPTS[n],taskPrompt:i}}export function generateFixViolationsPrompt(e,n,i){const t=l(e),r=i.map((s,c)=>`${c+1}. ${s.message}${s.suggestion?`
+   Suggestion: ${s.suggestion}`:""}`).join(`
+`);return{agent:"generic-mcp",taskPrompt:`## Fix Specification Violations
+
+The following implementation has violations against its specification:
+
+**Specification:**
+${t}
+
+**Current Implementation:**
+\`\`\`typescript
+${n}
+\`\`\`
+
+**Violations Found:**
+${r}
+
+Fix ALL violations while maintaining existing functionality.
+Provide the corrected implementation.`}}