@contractspec/lib.contracts 1.44.0 → 1.45.0

package/dist/app-config/spec.js

@@ -1,31 +1,10 @@
+import { SpecContractRegistry } from "../registry.js";
+
 //#region src/app-config/spec.ts
 const blueprintKey = (meta) => `${meta.key}.v${meta.version}`;
-var AppBlueprintRegistry = class {
-	items = /* @__PURE__ */ new Map();
-	register(spec) {
-		const key = blueprintKey(spec.meta);
-		if (this.items.has(key)) throw new Error(`Duplicate AppBlueprint ${key}`);
-		this.items.set(key, spec);
-		return this;
-	}
-	list() {
-		return [...this.items.values()];
-	}
-	get(key, version) {
-		if (version != null) return this.items.get(blueprintKey({
-			key,
-			version
-		}));
-		let latest;
-		let maxVersion = -Infinity;
-		for (const spec of this.items.values()) {
-			if (spec.meta.key !== key) continue;
-			if (spec.meta.version > maxVersion) {
-				maxVersion = spec.meta.version;
-				latest = spec;
-			}
-		}
-		return latest;
+var AppBlueprintRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("app-config", items);
 	}
 };
 function makeAppBlueprintKey(meta) {

package/dist/capabilities/capabilities.d.ts

@@ -1,4 +1,3 @@
-import { DocId } from "../docs/registry.js";
 import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/capabilities/capabilities.d.ts
@@ -7,28 +6,22 @@ type CapabilitySurface = 'operation' | 'event' | 'workflow' | 'presentation' | '
 interface CapabilitySurfaceRef {
   surface: CapabilitySurface;
   key: string;
-  version: number;
+  version: string;
   description?: string;
 }
 interface CapabilityMeta extends OwnerShipMeta {
-  /** Stable capability slug (e.g., "payments.stripe"). */
-  key: string;
-  /** Increment when the capability shape changes. */
-  version: number;
   kind: CapabilityKind;
-  /** Optional doc block id for governance and navigation. */
-  docId?: DocId[];
 }
 interface CapabilityRequirement {
   key: string;
-  version?: number;
+  version?: string;
   kind?: CapabilityKind;
   optional?: boolean;
   reason?: string;
 }
 interface CapabilityRef {
   key: string;
-  version: number;
+  version: string;
 }
 interface CapabilitySpec {
   meta: CapabilityMeta;
@@ -39,7 +32,7 @@ declare class CapabilityRegistry {
   private readonly items;
   register(spec: CapabilitySpec): this;
   list(): CapabilitySpec[];
-  get(key: string, version?: number): CapabilitySpec | undefined;
+  get(key: string, version?: string): CapabilitySpec | undefined;
   satisfies(requirement: CapabilityRequirement, additional?: CapabilityRef[] | undefined): boolean;
 }
 declare function capabilityKey(spec: CapabilitySpec): string;

package/dist/capabilities/capabilities.js

@@ -1,3 +1,5 @@
+import { compareVersions } from "compare-versions";
+
 //#region src/capabilities/capabilities.ts
 const capKey = (key, version) => `${key}.v${version}`;
 var CapabilityRegistry = class {
@@ -14,13 +16,9 @@ var CapabilityRegistry = class {
 	get(key, version) {
 		if (version != null) return this.items.get(capKey(key, version));
 		let candidate;
-		let max = -Infinity;
 		for (const spec of this.items.values()) {
 			if (spec.meta.key !== key) continue;
-			if (spec.meta.version > max) {
-				max = spec.meta.version;
-				candidate = spec;
-			}
+			if (!candidate || compareVersions(spec.meta.version, candidate.meta.version) > 0) candidate = spec;
 		}
 		return candidate;
 	}

package/dist/capabilities/openbanking.js

@@ -6,7 +6,7 @@ const TAGS = ["open-banking", "finance"];
 const openBankingAccountsReadCapability = {
 	meta: {
 		key: "openbanking.accounts.read",
-		version: 1,
+		version: "1.0.0",
 		kind: "integration",
 		title: "Open Banking Accounts (Read)",
 		description: "Provides read-only access to linked bank accounts, including account summaries and metadata.",
@@ -19,19 +19,19 @@ const openBankingAccountsReadCapability = {
 		{
 			surface: "operation",
 			key: "openbanking.accounts.list",
-			version: 1,
+			version: "1.0.0",
 			description: "List bank accounts linked to a Powens open banking connection."
 		},
 		{
 			surface: "operation",
 			key: "openbanking.accounts.get",
-			version: 1,
+			version: "1.0.0",
 			description: "Retrieve the canonical bank account record for a specific account."
 		},
 		{
 			surface: "operation",
 			key: "openbanking.accounts.sync",
-			version: 1,
+			version: "1.0.0",
 			description: "Trigger a refresh of bank account metadata from the open banking provider."
 		}
 	]
@@ -39,7 +39,7 @@ const openBankingAccountsReadCapability = {
 const openBankingTransactionsReadCapability = {
 	meta: {
 		key: "openbanking.transactions.read",
-		version: 1,
+		version: "1.0.0",
 		kind: "integration",
 		title: "Open Banking Transactions (Read)",
 		description: "Enables retrieval of transaction history for linked bank accounts via open banking providers.",
@@ -51,19 +51,19 @@ const openBankingTransactionsReadCapability = {
 	provides: [{
 		surface: "operation",
 		key: "openbanking.transactions.list",
-		version: 1,
+		version: "1.0.0",
 		description: "List transactions for a given bank account with optional date filtering."
 	}, {
 		surface: "operation",
 		key: "openbanking.transactions.sync",
-		version: 1,
+		version: "1.0.0",
 		description: "Synchronise transactions from the open banking provider into the canonical ledger."
 	}]
 };
 const openBankingBalancesReadCapability = {
 	meta: {
 		key: "openbanking.balances.read",
-		version: 1,
+		version: "1.0.0",
 		kind: "integration",
 		title: "Open Banking Balances (Read)",
 		description: "Allows querying of current and available balances for linked bank accounts via open banking providers.",
@@ -75,12 +75,12 @@ const openBankingBalancesReadCapability = {
 	provides: [{
 		surface: "operation",
 		key: "openbanking.balances.get",
-		version: 1,
+		version: "1.0.0",
 		description: "Retrieve the latest known balances for a specified bank account."
 	}, {
 		surface: "operation",
 		key: "openbanking.balances.refresh",
-		version: 1,
+		version: "1.0.0",
 		description: "Force a balance refresh from the open banking provider."
 	}]
 };

package/dist/client/react/form-render.js

@@ -1,4 +1,5 @@
 import { buildZodWithRelations, evalPredicate } from "../../forms/forms.js";
+import "../../forms/index.js";
 import React, { useEffect, useMemo, useState } from "react";
 import { Controller, useFieldArray, useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";

package/dist/contract-registry/schemas.d.ts

@@ -41,17 +41,17 @@ declare const ContractRegistryItemSchema: z.ZodObject<{
     "contractspec:app-config": "contractspec:app-config";
     "contractspec:knowledge": "contractspec:knowledge";
   }>;
-  version: z.ZodNumber;
+  version: z.ZodString;
   title: z.ZodString;
   description: z.ZodString;
   meta: z.ZodObject<{
     stability: z.ZodEnum<{
-      experimental: "experimental";
-      beta: "beta";
-      stable: "stable";
       deprecated: "deprecated";
       idea: "idea";
       in_creation: "in_creation";
+      experimental: "experimental";
+      beta: "beta";
+      stable: "stable";
     }>;
     owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -90,17 +90,17 @@ declare const ContractRegistryManifestSchema: z.ZodObject<{
       "contractspec:app-config": "contractspec:app-config";
       "contractspec:knowledge": "contractspec:knowledge";
     }>;
-    version: z.ZodNumber;
+    version: z.ZodString;
     title: z.ZodString;
     description: z.ZodString;
     meta: z.ZodObject<{
       stability: z.ZodEnum<{
-        experimental: "experimental";
-        beta: "beta";
-        stable: "stable";
         deprecated: "deprecated";
         idea: "idea";
         in_creation: "in_creation";
+        experimental: "experimental";
+        beta: "beta";
+        stable: "stable";
       }>;
       owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
       tags: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/contract-registry/schemas.js

@@ -27,7 +27,7 @@ const ContractRegistryFileSchema = z.object({
 const ContractRegistryItemSchema = z.object({
 	key: z.string().min(1),
 	type: ContractRegistryItemTypeSchema,
-	version: z.number().int().nonnegative(),
+	version: z.string(),
 	title: z.string().min(1),
 	description: z.string().min(1),
 	meta: z.object({

package/dist/contract-registry/types.d.ts

@@ -19,7 +19,7 @@ interface ContractRegistryFile {
 interface ContractRegistryItem {
   key: string;
   type: ContractRegistryItemType;
-  version: number;
+  version: string;
   title: string;
   description: string;
   meta: {

package/dist/data-views/data-views.js

@@ -1,4 +1,5 @@
 import { defineDataView } from "./spec.js";
 import { DataViewRegistry, dataViewKey } from "./registry.js";
+import "./index.js";
 
 export { DataViewRegistry, dataViewKey, defineDataView };

package/dist/data-views/registry.d.ts

@@ -1,5 +1,5 @@
-import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
 import { DataViewSpec } from "./spec.js";
+import { SpecContractRegistry } from "../registry.js";
 
 //#region src/data-views/registry.d.ts
 
@@ -10,42 +10,8 @@ declare function dataViewKey(spec: DataViewSpec): string;
 /**
  * Registry for managing data view specifications.
  */
-declare class DataViewRegistry {
-  private readonly items;
-  /**
-   * Register a data view spec.
-   * @throws Error if a spec with the same key already exists.
-   */
-  register(spec: DataViewSpec): this;
-  /**
-   * List all registered data view specs.
-   */
-  list(): DataViewSpec[];
-  /**
-   * Get a data view by key and optional version.
-   * If version is not specified, returns the latest version.
-   */
-  get(name: string, version?: number): DataViewSpec | undefined;
-  /**
-   * Filter data views by criteria.
-   */
-  filter(criteria: RegistryFilter): DataViewSpec[];
-  /**
-   * List data views with specific tag.
-   */
-  listByTag(tag: string): DataViewSpec[];
-  /**
-   * List data views by owner.
-   */
-  listByOwner(owner: string): DataViewSpec[];
-  /**
-   * Group data views by key function.
-   */
-  groupBy(keyFn: GroupKeyFn<DataViewSpec>): Map<string, DataViewSpec[]>;
-  /**
-   * Get unique tags from all data views.
-   */
-  getUniqueTags(): string[];
+declare class DataViewRegistry extends SpecContractRegistry<'data-view', DataViewSpec> {
+  constructor(items?: DataViewSpec[]);
 }
 //#endregion
 export { DataViewRegistry, dataViewKey };

package/dist/data-views/registry.js

@@ -1,7 +1,6 @@
-import { filterBy, getUniqueTags, groupBy, init_registry_utils } from "../registry-utils.js";
+import { SpecContractRegistry } from "../registry.js";
 
 //#region src/data-views/registry.ts
-init_registry_utils();
 /**
 * Generate a unique key for a data view spec.
 */
@@ -11,70 +10,9 @@ function dataViewKey(spec) {
 /**
 * Registry for managing data view specifications.
 */
-var DataViewRegistry = class {
-	items = /* @__PURE__ */ new Map();
-	/**
-	* Register a data view spec.
-	* @throws Error if a spec with the same key already exists.
-	*/
-	register(spec) {
-		const key = dataViewKey(spec);
-		if (this.items.has(key)) throw new Error(`Duplicate data view ${key}`);
-		this.items.set(key, spec);
-		return this;
-	}
-	/**
-	* List all registered data view specs.
-	*/
-	list() {
-		return [...this.items.values()];
-	}
-	/**
-	* Get a data view by key and optional version.
-	* If version is not specified, returns the latest version.
-	*/
-	get(name, version) {
-		if (version != null) return this.items.get(`${name}.v${version}`);
-		let candidate;
-		let max = -Infinity;
-		for (const spec of this.items.values()) {
-			if (spec.meta.key !== name) continue;
-			if (spec.meta.version > max) {
-				max = spec.meta.version;
-				candidate = spec;
-			}
-		}
-		return candidate;
-	}
-	/**
-	* Filter data views by criteria.
-	*/
-	filter(criteria) {
-		return filterBy(this.list(), criteria);
-	}
-	/**
-	* List data views with specific tag.
-	*/
-	listByTag(tag) {
-		return this.list().filter((d) => d.meta.tags?.includes(tag));
-	}
-	/**
-	* List data views by owner.
-	*/
-	listByOwner(owner) {
-		return this.list().filter((d) => d.meta.owners?.includes(owner));
-	}
-	/**
-	* Group data views by key function.
-	*/
-	groupBy(keyFn) {
-		return groupBy(this.list(), keyFn);
-	}
-	/**
-	* Get unique tags from all data views.
-	*/
-	getUniqueTags() {
-		return getUniqueTags(this.list());
+var DataViewRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("data-view", items);
 	}
 };
 

package/dist/data-views/runtime.d.ts

@@ -18,7 +18,7 @@ declare class DataViewRuntime {
   private subscriptions;
   constructor(config: DataViewRuntimeConfig);
   register(spec: DataViewSpec): void;
-  getSpec(name: string, version?: number): DataViewSpec | undefined;
+  getSpec(name: string, version?: string): DataViewSpec | undefined;
   executeQuery(specName: string, _params: unknown): Promise<DataViewResult>;
   invalidate(specName: string): void;
   subscribe(specName: string, callback: () => void): () => void;

package/dist/data-views/runtime.js

@@ -1,3 +1,5 @@
+import "./index.js";
+
 //#region src/data-views/runtime.ts
 var DataViewRuntime = class {
 	cache = /* @__PURE__ */ new Map();

package/dist/data-views/spec.d.ts

@@ -1,5 +1,5 @@
-import { ExperimentRef } from "../experiments/spec.js";
 import { DataViewConfig, DataViewMeta, DataViewSource, DataViewStates } from "./types.js";
+import { ExperimentRef } from "../experiments/spec.js";
 
 //#region src/data-views/spec.d.ts
 
@@ -22,7 +22,7 @@ interface DataViewSpec {
  */
 interface DataViewRef {
   key: string;
-  version: number;
+  version: string;
 }
 /**
  * Helper to define a data view spec with type safety.

package/dist/docs/index.d.ts

@@ -1,6 +1,6 @@
 import { DocBlock, DocBlockLink, DocKind, DocVisibility } from "./types.js";
-import { DocPresentationOptions, DocPresentationRoute, docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes } from "./presentations.js";
+import { DocPresentationOptions, DocPresentationRoute, docBlockToPresentationSpec, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes } from "./presentations.js";
 import { DocId, DocRegistry, defaultDocRegistry, docId, listRegisteredDocBlocks, registerDocBlocks } from "./registry.js";
 import { techContractsDocs } from "./tech-contracts.docs.js";
 import { metaDocs } from "./meta.docs.js";
-export { DocBlock, DocBlockLink, DocId, DocKind, DocPresentationOptions, DocPresentationRoute, DocRegistry, DocVisibility, defaultDocRegistry, docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, docId, listRegisteredDocBlocks, mapDocRoutes, metaDocs, registerDocBlocks, techContractsDocs };
+export { DocBlock, DocBlockLink, DocId, DocKind, DocPresentationOptions, DocPresentationRoute, DocRegistry, DocVisibility, defaultDocRegistry, docBlockToPresentationSpec, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, docId, listRegisteredDocBlocks, mapDocRoutes, metaDocs, registerDocBlocks, techContractsDocs };

package/dist/docs/index.js

@@ -1,4 +1,4 @@
-import { docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes } from "./presentations.js";
+import { docBlockToPresentationSpec, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes } from "./presentations.js";
 import { DocRegistry, defaultDocRegistry, docId, listRegisteredDocBlocks, registerDocBlocks } from "./registry.js";
 import { techContractsDocs } from "./tech-contracts.docs.js";
 import { metaDocs } from "./meta.docs.js";
@@ -26,4 +26,4 @@ import "./tech/studio/project-access-teams.docblock.js";
 import "./tech/studio/team-invitations.docblock.js";
 import "./tech/llm/llm-integration.docblock.js";
 
-export { DocRegistry, defaultDocRegistry, docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, docId, listRegisteredDocBlocks, mapDocRoutes, metaDocs, registerDocBlocks, techContractsDocs };
+export { DocRegistry, defaultDocRegistry, docBlockToPresentationSpec, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, docId, listRegisteredDocBlocks, mapDocRoutes, metaDocs, registerDocBlocks, techContractsDocs };

package/dist/docs/presentations.d.ts

@@ -14,7 +14,7 @@ interface DocPresentationOptions {
   /** Default presentation targets. */
   defaultTargets?: PresentationTarget[];
   /** Default version when block.version is not set. */
-  defaultVersion?: number;
+  defaultVersion?: string;
   /** Default stability if not provided on the DocBlock. */
   defaultStability?: Stability;
 }
@@ -24,10 +24,8 @@ interface DocPresentationRoute {
   block: DocBlock;
 }
 declare function docBlockToPresentationSpec(block: DocBlock, options?: DocPresentationOptions): PresentationSpec;
-/** @deprecated Use docBlockToPresentationSpec instead */
-declare const docBlockToPresentationV2: typeof docBlockToPresentationSpec;
 declare function docBlocksToPresentationRoutes(blocks: DocBlock[], options?: DocPresentationOptions): DocPresentationRoute[];
 declare function docBlocksToPresentationSpecs(blocks: DocBlock[], options?: DocPresentationOptions): PresentationSpec[];
 declare function mapDocRoutes(routes: DocPresentationRoute[]): [string, PresentationSpec][];
 //#endregion
-export { DocPresentationOptions, DocPresentationRoute, docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes };
+export { DocPresentationOptions, DocPresentationRoute, docBlockToPresentationSpec, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes };

package/dist/docs/presentations.js

@@ -21,7 +21,7 @@ function buildName(block, namespace) {
 }
 function docBlockToPresentationSpec(block, options) {
 	const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-	const version = block.version ?? options?.defaultVersion ?? 1;
+	const version = block.version ?? options?.defaultVersion ?? "1.0.0";
 	const stability = block.stability ?? options?.defaultStability ?? "stable";
 	return {
 		meta: {
@@ -44,8 +44,6 @@ function docBlockToPresentationSpec(block, options) {
 		targets
 	};
 }
-/** @deprecated Use docBlockToPresentationSpec instead */
-const docBlockToPresentationV2 = docBlockToPresentationSpec;
 function docBlocksToPresentationRoutes(blocks, options) {
 	return blocks.map((block) => ({
 		block,
@@ -61,4 +59,4 @@ function mapDocRoutes(routes) {
 }
 
 //#endregion
-export { docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes };
+export { docBlockToPresentationSpec, docBlocksToPresentationRoutes, docBlocksToPresentationSpecs, mapDocRoutes };

package/dist/docs/tech/contracts/ops-to-presentation-linking.docblock.js

@@ -13,7 +13,7 @@ const tech_contracts_ops_to_presentation_linking_DocBlocks = [{
 		"contracts",
 		"ops-to-presentation-linking"
 	],
-	body: "### Ops ↔ Presentation linking (V2)\n\nThis document explains how operations (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.\n\n- Location: `@contractspec/lib.contracts/src/features.ts`\n- Field: `FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]`\n- Validation: `installFeature()` validates that linked ops exist in `OperationSpecRegistry` and linked presentations exist in the registry, and that declared targets are present.\n\nExample:\n\n```ts\nimport type { OperationSpecRegistry } from '@contractspec/lib.contracts/src/registry';\nimport { FeatureRegistry, createFeatureModule } from '@contractspec/lib.contracts';\n\nexport function buildFeaturesWithOps(ops: OperationSpecRegistry) {\n  const features = new FeatureRegistry();\n  features.register(\n    createFeatureModule(\n      {\n        key: 'myapp.widgets.linkage',\n        title: 'Widgets (linked)',\n        description: 'Links create/update ops to UI presentations',\n        domain: 'widgets',\n        tags: ['widgets', 'linkage'],\n        stability: 'beta',\n      },\n      {\n        operations: [\n          { name: 'widgets.create', version: 1 },\n          { name: 'widgets.update', version: 1 },\n        ],\n        presentations: [{ name: 'myapp.widgets.editor.page', version: 1 }],\n        opToPresentation: [\n          {\n            op: { name: 'widgets.create', version: 1 },\n            pres: { name: 'myapp.widgets.editor.page', version: 1 },\n          },\n          {\n            op: { name: 'widgets.update', version: 1 },\n            pres: { name: 'myapp.widgets.editor.page', version: 1 },\n          },\n        ],\n        presentationsTargets: [\n          {\n            name: 'myapp.widgets.editor.page',\n            version: 1,\n            targets: ['react', 'markdown'],\n          },\n        ],\n      }\n    )\n  );\n  return { features };\n}\n```\n\nNotes\n\n- This enables traceability: the UI flow that realizes an op is discoverable via the feature catalog.\n- Presentations can target multiple outputs (`react`, `markdown`, `application/json`, `application/xml`).\n- Use `renderFeaturePresentation()` to render a descriptor to a given target with a component map.\n"
+	body: "### Ops ↔ Presentation linking (V2)\n\nThis document explains how operations (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.\n\n- Location: `@contractspec/lib.contracts/src/features.ts`\n- Field: `FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]`\n- Validation: `installFeature()` validates that linked ops exist in `OperationSpecRegistry` and linked presentations exist in the registry, and that declared targets are present.\n\nExample:\n\n```ts\nimport type { OperationSpecRegistry } from '@contractspec/lib.contracts/src/registry';\nimport { FeatureRegistry, createFeatureModule } from '@contractspec/lib.contracts';\n\nexport function buildFeaturesWithOps(ops: OperationSpecRegistry) {\n  const features = new FeatureRegistry();\n  features.register(\n    createFeatureModule(\n      {\n        key: 'myapp.widgets.linkage',\n        title: 'Widgets (linked)',\n        description: 'Links create/update ops to UI presentations',\n        domain: 'widgets',\n        tags: ['widgets', 'linkage'],\n        stability: 'beta',\n      },\n      {\n        operations: [\n          { name: 'widgets.create', version: '1.0.0' },\n          { name: 'widgets.update', version: '1.0.0' },\n        ],\n        presentations: [{ name: 'myapp.widgets.editor.page', version: '1.0.0' }],\n        opToPresentation: [\n          {\n            op: { name: 'widgets.create', version: '1.0.0' },\n            pres: { name: 'myapp.widgets.editor.page', version: '1.0.0' },\n          },\n          {\n            op: { name: 'widgets.update', version: '1.0.0' },\n            pres: { name: 'myapp.widgets.editor.page', version: '1.0.0' },\n          },\n        ],\n        presentationsTargets: [\n          {\n            name: 'myapp.widgets.editor.page',\n            version: '1.0.0',\n            targets: ['react', 'markdown'],\n          },\n        ],\n      }\n    )\n  );\n  return { features };\n}\n```\n\nNotes\n\n- This enables traceability: the UI flow that realizes an op is discoverable via the feature catalog.\n- Presentations can target multiple outputs (`react`, `markdown`, `application/json`, `application/xml`).\n- Use `renderFeaturePresentation()` to render a descriptor to a given target with a component map.\n"
 }];
 registerDocBlocks(tech_contracts_ops_to_presentation_linking_DocBlocks);
 

package/dist/docs/tech/contracts/tests.docblock.js

@@ -13,7 +13,7 @@ const tech_contracts_tests_DocBlocks = [{
 		"contracts",
 		"tests"
 	],
-	body: "## TestSpec & TestRunner\n\nUse `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same OperationSpecRegistry handlers the app uses.\n\n- Types & registry: `packages/libs/contracts/src/tests/spec.ts`\n- Runtime runner: `packages/libs/contracts/src/tests/runner.ts`\n- CLI: `contractspec test`\n\n### Structure\n\n```ts\nexport interface TestSpec {\n  meta: TestSpecMeta;\n  target: TestTarget;  // contract or workflow\n  fixtures?: Fixture[]; // optional shared setup before each scenario\n  scenarios: TestScenario[];\n  coverage?: CoverageRequirement;\n}\n```\n\n- `Fixture`: run an operation before the scenario (`operation`, optional `input`)\n- `Action`: operation input that the scenario exercises\n- `Assertion`:\n  - `expectOutput` `{ match }` deep-equals the handler output\n  - `expectError` `{ messageIncludes? }` ensures an error was thrown\n  - `expectEvents` `{ events: [{ name, version, min?, max? }] }` checks emitted events\n\n### Example\n\n```ts\nimport { defineCommand, type TestSpec } from '@contractspec/lib.contracts';\n\nexport const AddNumbersSpec = defineCommand({\n  meta: { name: 'math.add', version: 1, /* … */ },\n  io: {\n    input: AddNumbersInput,\n    output: AddNumbersOutput,\n  },\n  policy: { auth: 'user' },\n});\n\nexport const MathAddTests: TestSpec = {\n  meta: {\n    name: 'math.add.tests',\n    version: 1,\n    title: 'Math add scenarios',\n    owners: ['@team.math'],\n    tags: ['math'],\n    stability: StabilityEnum.Experimental,\n  },\n  target: { type: 'contract', operation: { name: 'math.add' } },\n  scenarios: [\n    {\n      name: 'adds positive numbers',\n      when: {\n        operation: { name: 'math.add' },\n        input: { a: 2, b: 3 },\n      },\n      then: [\n        { type: 'expectOutput', match: { sum: 5 } },\n        {\n          type: 'expectEvents',\n          events: [{ name: 'math.sum_calculated', version: 1, min: 1 }],\n        },\n      ],\n    },\n  ],\n};\n```\n\n### Running tests\n\n1. Register the contract handlers in a `OperationSpecRegistry`:\n\n```ts\nexport function createRegistry() {\n  const registry = new OperationSpecRegistry();\n  registry.register(AddNumbersSpec);\n  registry.bind(AddNumbersSpec, addNumbersHandler);\n  return registry;\n}\n```\n\n2. Run the CLI:\n\n```\ncontractspec test apps/math/tests/math.add.tests.ts \\\n  --registry apps/math/tests/registry.ts\n```\n\n- The CLI loads the TestSpec, instantiates the registry (via the provided module), and executes each scenario via `TestRunner`.\n- `--json` outputs machine-readable results.\n\n### Programmatic usage\n\n```ts\nconst runner = new TestRunner({\n  registry,\n  createContext: () => ({ actor: 'user', organizationId: 'tenant-1' }),\n});\n\nconst result = await runner.run(MathAddTests);\nconsole.log(result.passed, result.failed);\n```\n\n- `createContext` can supply default `HandlerCtx` values.\n- `beforeEach` / `afterEach` hooks let you seed databases or reset state.\n\n### Best practices\n\n- Keep fixtures idempotent so scenarios can run in parallel in the future.\n- Use `expectEvents` to guard analytics/telemetry expectations.\n- Add specs to `TestRegistry` for discovery and documentation.\n- `coverage` captures desired coverage metrics (enforced by future tooling).\n- Pair TestSpec files with CI using `contractspec test --json` and fail builds when `failed > 0`.\n\n### Mocking with Bun's `vi`\n\n- Pass a single function type to `vi.fn<TFunction>()` so calls retain typed arguments:\n\n```ts\nconst handler = vi.fn<typeof fetch>();\nconst fetchImpl: typeof fetch = ((...args) => handler(...args)) as typeof fetch;\nObject.defineProperty(fetchImpl, 'preconnect', {\n  value: vi.fn<typeof fetch.preconnect>(),\n});\n```\n\n- When you need to inspect calls, use the typed mock (`handler.mock.calls`) rather than casting to `any`.\n- Narrow optional request data defensively (e.g., check for headers before reading them) so tests remain type-safe under strict `tsconfig` settings.\n\n"
+	body: "## TestSpec & TestRunner\n\nUse `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same OperationSpecRegistry handlers the app uses.\n\n- Types & registry: `packages/libs/contracts/src/tests/spec.ts`\n- Runtime runner: `packages/libs/contracts/src/tests/runner.ts`\n- CLI: `contractspec test`\n\n### Structure\n\n```ts\nexport interface TestSpec {\n  meta: TestSpecMeta;\n  target: TestTarget;  // contract or workflow\n  fixtures?: Fixture[]; // optional shared setup before each scenario\n  scenarios: TestScenario[];\n  coverage?: CoverageRequirement;\n}\n```\n\n- `Fixture`: run an operation before the scenario (`operation`, optional `input`)\n- `Action`: operation input that the scenario exercises\n- `Assertion`:\n  - `expectOutput` `{ match }` deep-equals the handler output\n  - `expectError` `{ messageIncludes? }` ensures an error was thrown\n  - `expectEvents` `{ events: [{ name, version, min?, max? }] }` checks emitted events\n\n### Example\n\n```ts\nimport { defineCommand, type TestSpec } from '@contractspec/lib.contracts';\n\nexport const AddNumbersSpec = defineCommand({\n  meta: { name: 'math.add', version: '1.0.0', /* … */ },\n  io: {\n    input: AddNumbersInput,\n    output: AddNumbersOutput,\n  },\n  policy: { auth: 'user' },\n});\n\nexport const MathAddTests: TestSpec = {\n  meta: {\n    name: 'math.add.tests',\n    version: '1.0.0',\n    title: 'Math add scenarios',\n    owners: ['@team.math'],\n    tags: ['math'],\n    stability: StabilityEnum.Experimental,\n  },\n  target: { type: 'contract', operation: { name: 'math.add' } },\n  scenarios: [\n    {\n      name: 'adds positive numbers',\n      when: {\n        operation: { name: 'math.add' },\n        input: { a: 2, b: 3 },\n      },\n      then: [\n        { type: 'expectOutput', match: { sum: 5 } },\n        {\n          type: 'expectEvents',\n          events: [{ name: 'math.sum_calculated', version: '1.0.0', min: 1 }],\n        },\n      ],\n    },\n  ],\n};\n```\n\n### Running tests\n\n1. Register the contract handlers in a `OperationSpecRegistry`:\n\n```ts\nexport function createRegistry() {\n  const registry = new OperationSpecRegistry();\n  registry.register(AddNumbersSpec);\n  registry.bind(AddNumbersSpec, addNumbersHandler);\n  return registry;\n}\n```\n\n2. Run the CLI:\n\n```\ncontractspec test apps/math/tests/math.add.tests.ts \\\n  --registry apps/math/tests/registry.ts\n```\n\n- The CLI loads the TestSpec, instantiates the registry (via the provided module), and executes each scenario via `TestRunner`.\n- `--json` outputs machine-readable results.\n\n### Programmatic usage\n\n```ts\nconst runner = new TestRunner({\n  registry,\n  createContext: () => ({ actor: 'user', organizationId: 'tenant-1' }),\n});\n\nconst result = await runner.run(MathAddTests);\nconsole.log(result.passed, result.failed);\n```\n\n- `createContext` can supply default `HandlerCtx` values.\n- `beforeEach` / `afterEach` hooks let you seed databases or reset state.\n\n### Best practices\n\n- Keep fixtures idempotent so scenarios can run in parallel in the future.\n- Use `expectEvents` to guard analytics/telemetry expectations.\n- Add specs to `TestRegistry` for discovery and documentation.\n- `coverage` captures desired coverage metrics (enforced by future tooling).\n- Pair TestSpec files with CI using `contractspec test --json` and fail builds when `failed > 0`.\n\n### Mocking with Bun's `vi`\n\n- Pass a single function type to `vi.fn<TFunction>()` so calls retain typed arguments:\n\n```ts\nconst handler = vi.fn<typeof fetch>();\nconst fetchImpl: typeof fetch = ((...args) => handler(...args)) as typeof fetch;\nObject.defineProperty(fetchImpl, 'preconnect', {\n  value: vi.fn<typeof fetch.preconnect>(),\n});\n```\n\n- When you need to inspect calls, use the typed mock (`handler.mock.calls`) rather than casting to `any`.\n- Narrow optional request data defensively (e.g., check for headers before reading them) so tests remain type-safe under strict `tsconfig` settings.\n\n"
 }];
 registerDocBlocks(tech_contracts_tests_DocBlocks);
 

package/dist/docs/tech/lifecycle-stage-system.docblock.js

@@ -9,7 +9,7 @@ const tech_lifecycle_stage_system_DocBlocks = [{
 	visibility: "public",
 	route: "/docs/tech/lifecycle-stage-system",
 	tags: ["tech", "lifecycle-stage-system"],
-	body: "## ContractSpec Lifecycle Stage System – Technical Design\n\nThis document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.\n\n---\n\n### 1. Architecture Overview\n\n```\n┌──────────────────────┐\n│ @contractspec/lib.lifecycle  │  Types, enums, helpers (pure data)\n└───────────┬──────────┘\n            │\n┌───────────▼──────────┐    ┌───────────────────────────┐\n│ modules/lifecycle-   │    │ modules/lifecycle-advisor  │\n│ core (detection)     │    │ (guidance & ceremonies)    │\n└───────────┬──────────┘    └───────────┬───────────────┘\n            │                           │\n            ├────────────┬──────────────┤\n            ▼            ▼              ▼\n  Adapters: analytics, intent, questionnaires\n            │\n┌───────────▼──────────┐\n│ bundles/lifecycle-   │  Managed service for Studio\n│ managed              │  (REST handlers, AI agent)     │\n└───────────┬──────────┘\n            │\n  ContractSpec Studio surfaces\n  (web/mobile APIs, CLI, docs)\n```\n\n- **Libraries** provide shared vocabulary.\n- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.\n- **Bundles** compose modules, register agents/events, and expose APIs for Studio.\n- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve `@contractspec/bundle.studio` and `@contractspec/lib.database-contractspec-studio` directly from their `packages/.../src` folders via `tsconfig` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled `dist` artifacts into client chunks.\n\n---\n\n### 2. Core Library (`@contractspec/lib.lifecycle`)\n\n- Stage enum (0–6) with metadata (`question`, `signals`, `traps`).\n- Axes types (`ProductPhase`, `CompanyPhase`, `CapitalPhase`).\n- `LifecycleSignal` (source, metric, value, timestamp).\n- `LifecycleMetricSnapshot` (aggregated numbers).\n- `LifecycleMilestone`, `LifecycleAction`, `LifecycleAssessment` interfaces.\n- Utility helpers:\n  - `formatStageSummary(stage, assessment)`\n  - `rankStageCandidates(scores)`\n\nThe library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.\n\n---\n\n### 3. Lifecycle Core Module\n\n**Location:** `packages/modules/lifecycle-core/`\n\n#### Components\n1. **StageSignalCollector**\n   - Accepts adapter interfaces:\n     - `AnalyticsAdapter` (pulls metrics from `@contractspec/lib.analytics` or fixture streams).\n     - `IntentAdapter` (hooks into `@contractspec/lib.observability` intent detectors or logs).\n     - `QuestionnaireAdapter` (loads JSON questionnaires and responses).\n   - Produces normalized `LifecycleSignal[]`.\n\n2. **StageScorer**\n   - Weighted scoring model:\n     - Base weight per stage (reflecting expected maturity).\n     - Feature weights (retention, revenue, team size, qualitative feedback).\n     - Confidence computed via variance of contributing signals.\n   - Supports pluggable scoring matrices via JSON config.\n   - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.\n\n3. **LifecycleOrchestrator**\n   - Coordinates collectors + scorer.\n   - Returns `LifecycleAssessment` with:\n     - `stage`, `confidence`, `axisSnapshot`, `signalsUsed`.\n     - Recommended focus areas (high-level categories only).\n   - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).\n\n4. **LifecycleMilestonePlanner**\n   - Loads `milestones-catalog.json` (no DB).\n   - Filters upcoming milestones per stage + axis.\n   - Tracks completion using provided IDs (caller persists).\n\n#### Data Files\n- `configs/stage-weights.json`\n- `configs/milestones-catalog.json`\n- `questionnaires/stage-readiness.json`\n\n#### Extension Hooks\n- All adapters exported as TypeScript interfaces.\n- Implementations for analytics/intent can live in bundles or apps without modifying module code.\n\n---\n\n### 4. Lifecycle Advisor Module\n\n**Location:** `packages/modules/lifecycle-advisor/`\n\n#### Components\n1. **LifecycleRecommendationEngine**\n   - Consumes `LifecycleAssessment`.\n   - Maps gaps to `LifecycleAction[]` using rule tables (`stage-playbooks.ts`).\n   - Supports override hooks for customer-specific rules.\n\n2. **ContractSpecLibraryRecommender**\n   - Maintains mapping from stage → recommended libraries/modules/bundles.\n   - Returns prioritized list with rationale and adoption prerequisites.\n\n3. **LifecycleCeremonyDesigner**\n   - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).\n   - Ensures low-tech friendly instructions (clear copy, undo guidance).\n\n4. **AI Hooks**\n   - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).\n   - Keeps actual LLM integration outside module.\n\n---\n\n### 5. Managed Bundle (`lifecycle-managed`)\n\n**Responsibilities**\n- Wire modules together.\n- Provide HTTP/GraphQL handlers (exact transport optional).\n- Register LifecycleAdvisorAgent via `@contractspec/lib.ai-agent`.\n- LifecycleAdvisorAgent meta: domain `operations`, owners `team-lifecycle`, stability `experimental`, tags `guide/lifecycle/ops` so ops tooling can route incidents quickly.\n- Emit lifecycle events through `@contractspec/lib.bus` + `@contractspec/lib.analytics`.\n- Integrate with `contractspec-studio` packages:\n  - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).\n  - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).\n\n**APIs**\n- `POST /lifecycle/assessments`: Accepts metrics + optional questionnaire answers. Returns `LifecycleAssessment`.\n- `GET /lifecycle/playbooks/:stage`: Returns stage playbook + ceremonies.\n- `POST /lifecycle/advise`: Invokes LifecycleAdvisorAgent with context.\n\n**Events**\n- `LifecycleAssessmentCreated`\n- `LifecycleStageChanged`\n- `LifecycleGuidanceConsumed`\n\n---\n\n### 6. Library Enhancements\n\n| Library | Enhancement |\n| --- | --- |\n| `@contractspec/lib.analytics` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by `StageSignalCollector`. |\n| `@contractspec/lib.evolution` | Accepts `LifecycleContext` when ranking spec anomalies/suggestions. |\n| `@contractspec/lib.growth` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |\n| `@contractspec/lib.observability` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |\n\nEach enhancement must import stage types from `@contractspec/lib.lifecycle`.\n\n---\n\n### 7. Feature Flags & Progressive Delivery\n\n- Add new flags in progressive-delivery library:\n  - `LIFECYCLE_DETECTION_ALPHA`\n  - `LIFECYCLE_ADVISOR_ALPHA`\n  - `LIFECYCLE_MANAGED_SERVICE`\n- Bundles/modules should check flags before enabling workflows.\n- Flags referenced in docs + Studio UI to avoid accidental exposure.\n\n---\n\n### 8. Analytics & Telemetry\n\n- Events defined in analytics library; consumed by bundle/app:\n  - `lifecycle_assessment_run`\n  - `lifecycle_stage_changed`\n  - `lifecycle_guidance_consumed`\n- Observability pipeline includes:\n  - Composite lifecycle health metric (weighted sum of KPIs).\n  - Drift detection comparing stage predictions over time.\n  - Alert manager recipes for regression (e.g., PMF drop).\n\n---\n\n### 9. Testing Strategy\n\n1. **Unit**\n   - StageScorer weight matrix.\n   - RecommendationEngine mapping.\n   - Library recommender stage coverage.\n\n2. **Contract**\n   - Adapters: ensure mock adapters satisfy interfaces.\n   - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.\n\n3. **Integration**\n   - CLI example runs detection + guidance end-to-end on fixture data.\n   - Dashboard example renders assessments, verifying JSON structures remain stable.\n\n---\n\n### 10. Implementation Checklist\n\n- [ ] Documentation (product, tech, ops, user).\n- [ ] Library creation (`@contractspec/lib.lifecycle`).\n- [ ] Modules (`lifecycle-core`, `lifecycle-advisor`).\n- [ ] Bundle (`lifecycle-managed`) + Studio wiring.\n- [ ] Library enhancements (analytics/evolution/growth/observability).\n- [ ] Examples (CLI + dashboard).\n- [ ] Feature flags + telemetry.\n- [ ] Automated tests + fixtures.\n\nKeep this document in sync as modules evolve. When adding new stages or axes, update `@contractspec/lib.lifecycle` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch\n\n\n"
+	body: "## ContractSpec Lifecycle Stage System – Technical Design\n\nThis document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.\n\n---\n\n### 1. Architecture Overview\n\n```\n┌──────────────────────┐\n│ @contractspec/lib.lifecycle  │  Types, enums, helpers (pure data)\n└───────────┬──────────┘\n            │\n┌───────────▼──────────┐    ┌───────────────────────────┐\n│ modules/lifecycle-   │    │ modules/lifecycle-advisor  │\n│ core (detection)     │    │ (guidance & ceremonies)    │\n└───────────┬──────────┘    └───────────┬───────────────┘\n            │                           │\n            ├────────────┬──────────────┤\n            ▼            ▼              ▼\n  Adapters: analytics, intent, questionnaires\n            │\n┌───────────▼──────────┐\n│ bundles/lifecycle-   │  Managed service for Studio\n│ managed              │  (REST handlers, AI agent)     │\n└───────────┬──────────┘\n            │\n  ContractSpec Studio surfaces\n  (web/mobile APIs, CLI, docs)\n```\n\n- **Libraries** provide shared vocabulary.\n- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.\n- **Bundles** compose modules, register agents/events, and expose APIs for Studio.\n- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve `@contractspec/bundle.studio` and `@contractspec/lib.database-studio` directly from their `packages/.../src` folders via `tsconfig` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled `dist` artifacts into client chunks.\n\n---\n\n### 2. Core Library (`@contractspec/lib.lifecycle`)\n\n- Stage enum (0–6) with metadata (`question`, `signals`, `traps`).\n- Axes types (`ProductPhase`, `CompanyPhase`, `CapitalPhase`).\n- `LifecycleSignal` (source, metric, value, timestamp).\n- `LifecycleMetricSnapshot` (aggregated numbers).\n- `LifecycleMilestone`, `LifecycleAction`, `LifecycleAssessment` interfaces.\n- Utility helpers:\n  - `formatStageSummary(stage, assessment)`\n  - `rankStageCandidates(scores)`\n\nThe library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.\n\n---\n\n### 3. Lifecycle Core Module\n\n**Location:** `packages/modules/lifecycle-core/`\n\n#### Components\n1. **StageSignalCollector**\n   - Accepts adapter interfaces:\n     - `AnalyticsAdapter` (pulls metrics from `@contractspec/lib.analytics` or fixture streams).\n     - `IntentAdapter` (hooks into `@contractspec/lib.observability` intent detectors or logs).\n     - `QuestionnaireAdapter` (loads JSON questionnaires and responses).\n   - Produces normalized `LifecycleSignal[]`.\n\n2. **StageScorer**\n   - Weighted scoring model:\n     - Base weight per stage (reflecting expected maturity).\n     - Feature weights (retention, revenue, team size, qualitative feedback).\n     - Confidence computed via variance of contributing signals.\n   - Supports pluggable scoring matrices via JSON config.\n   - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.\n\n3. **LifecycleOrchestrator**\n   - Coordinates collectors + scorer.\n   - Returns `LifecycleAssessment` with:\n     - `stage`, `confidence`, `axisSnapshot`, `signalsUsed`.\n     - Recommended focus areas (high-level categories only).\n   - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).\n\n4. **LifecycleMilestonePlanner**\n   - Loads `milestones-catalog.json` (no DB).\n   - Filters upcoming milestones per stage + axis.\n   - Tracks completion using provided IDs (caller persists).\n\n#### Data Files\n- `configs/stage-weights.json`\n- `configs/milestones-catalog.json`\n- `questionnaires/stage-readiness.json`\n\n#### Extension Hooks\n- All adapters exported as TypeScript interfaces.\n- Implementations for analytics/intent can live in bundles or apps without modifying module code.\n\n---\n\n### 4. Lifecycle Advisor Module\n\n**Location:** `packages/modules/lifecycle-advisor/`\n\n#### Components\n1. **LifecycleRecommendationEngine**\n   - Consumes `LifecycleAssessment`.\n   - Maps gaps to `LifecycleAction[]` using rule tables (`stage-playbooks.ts`).\n   - Supports override hooks for customer-specific rules.\n\n2. **ContractSpecLibraryRecommender**\n   - Maintains mapping from stage → recommended libraries/modules/bundles.\n   - Returns prioritized list with rationale and adoption prerequisites.\n\n3. **LifecycleCeremonyDesigner**\n   - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).\n   - Ensures low-tech friendly instructions (clear copy, undo guidance).\n\n4. **AI Hooks**\n   - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).\n   - Keeps actual LLM integration outside module.\n\n---\n\n### 5. Managed Bundle (`lifecycle-managed`)\n\n**Responsibilities**\n- Wire modules together.\n- Provide HTTP/GraphQL handlers (exact transport optional).\n- Register LifecycleAdvisorAgent via `@contractspec/lib.ai-agent`.\n- LifecycleAdvisorAgent meta: domain `operations`, owners `team-lifecycle`, stability `experimental`, tags `guide/lifecycle/ops` so ops tooling can route incidents quickly.\n- Emit lifecycle events through `@contractspec/lib.bus` + `@contractspec/lib.analytics`.\n- Integrate with `contractspec-studio` packages:\n  - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).\n  - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).\n\n**APIs**\n- `POST /lifecycle/assessments`: Accepts metrics + optional questionnaire answers. Returns `LifecycleAssessment`.\n- `GET /lifecycle/playbooks/:stage`: Returns stage playbook + ceremonies.\n- `POST /lifecycle/advise`: Invokes LifecycleAdvisorAgent with context.\n\n**Events**\n- `LifecycleAssessmentCreated`\n- `LifecycleStageChanged`\n- `LifecycleGuidanceConsumed`\n\n---\n\n### 6. Library Enhancements\n\n| Library | Enhancement |\n| --- | --- |\n| `@contractspec/lib.analytics` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by `StageSignalCollector`. |\n| `@contractspec/lib.evolution` | Accepts `LifecycleContext` when ranking spec anomalies/suggestions. |\n| `@contractspec/lib.growth` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |\n| `@contractspec/lib.observability` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |\n\nEach enhancement must import stage types from `@contractspec/lib.lifecycle`.\n\n---\n\n### 7. Feature Flags & Progressive Delivery\n\n- Add new flags in progressive-delivery library:\n  - `LIFECYCLE_DETECTION_ALPHA`\n  - `LIFECYCLE_ADVISOR_ALPHA`\n  - `LIFECYCLE_MANAGED_SERVICE`\n- Bundles/modules should check flags before enabling workflows.\n- Flags referenced in docs + Studio UI to avoid accidental exposure.\n\n---\n\n### 8. Analytics & Telemetry\n\n- Events defined in analytics library; consumed by bundle/app:\n  - `lifecycle_assessment_run`\n  - `lifecycle_stage_changed`\n  - `lifecycle_guidance_consumed`\n- Observability pipeline includes:\n  - Composite lifecycle health metric (weighted sum of KPIs).\n  - Drift detection comparing stage predictions over time.\n  - Alert manager recipes for regression (e.g., PMF drop).\n\n---\n\n### 9. Testing Strategy\n\n1. **Unit**\n   - StageScorer weight matrix.\n   - RecommendationEngine mapping.\n   - Library recommender stage coverage.\n\n2. **Contract**\n   - Adapters: ensure mock adapters satisfy interfaces.\n   - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.\n\n3. **Integration**\n   - CLI example runs detection + guidance end-to-end on fixture data.\n   - Dashboard example renders assessments, verifying JSON structures remain stable.\n\n---\n\n### 10. Implementation Checklist\n\n- [ ] Documentation (product, tech, ops, user).\n- [ ] Library creation (`@contractspec/lib.lifecycle`).\n- [ ] Modules (`lifecycle-core`, `lifecycle-advisor`).\n- [ ] Bundle (`lifecycle-managed`) + Studio wiring.\n- [ ] Library enhancements (analytics/evolution/growth/observability).\n- [ ] Examples (CLI + dashboard).\n- [ ] Feature flags + telemetry.\n- [ ] Automated tests + fixtures.\n\nKeep this document in sync as modules evolve. When adding new stages or axes, update `@contractspec/lib.lifecycle` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch\n\n\n"
 }];
 registerDocBlocks(tech_lifecycle_stage_system_DocBlocks);
 

package/dist/docs/tech-contracts.docs.js

@@ -61,7 +61,7 @@ type Tag = string; // curated list available in code (e.g., 'auth', 'spots')
 // For presentations, meta is a Partial<OwnerShipMeta> plus description, name, version
 interface PresentationMeta extends Partial<OwnerShipMeta> {
   name: string;
-  version: number;
+  version: string;
   description?: string;
 }
 \`\`\`

package/dist/docs/types.d.ts

@@ -23,7 +23,7 @@ interface DocBlock {
   /** Visibility gate. Defaults to public. */
   visibility?: DocVisibility;
   /** Optional version to allow evolutions without breaking links. Defaults to 1. */
-  version?: number;
+  version?: string;
   /** Tags to aid discovery and filtering. */
   tags?: string[];
   /** Owning teams or individuals. */

package/dist/events.d.ts

@@ -32,13 +32,13 @@ interface EventEnvelope<T> {
   /** Event name as published (should match spec.name). */
   key: string;
   /** Event version as published (should match spec.version). */
-  version: number;
+  version: string;
   /** Validated payload. */
   payload: T;
 }
-type EventKey = `${string}.v${number}`;
+type EventKey = `${string}.v${string}`;
 /** Build a stable string key for an event name/version pair. */
-declare const eventKey: (key: string, version: number) => EventKey;
+declare const eventKey: (key: string, version: string) => EventKey;
 /** In-memory registry for EventSpec. */
 declare class EventRegistry extends SpecContractRegistry<'event', AnyEventSpec> {
   constructor(items?: AnyEventSpec[]);

package/dist/examples/docs/examples.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/examples/docs/examples.docblock.d.ts
+declare const tech_contracts_examples_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_examples_DocBlocks };