@contractspec/lib.contracts 1.44.1 → 1.45.0

package/dist/app-config/spec.d.ts

@@ -2,7 +2,6 @@ import { OwnerShipMeta } from "../ownership.js";
 import { CapabilityRef } from "../capabilities/capabilities.js";
 import "../capabilities/index.js";
 import { PolicyRef } from "../policy/spec.js";
-import { ExperimentRef } from "../experiments/spec.js";
 import { ThemeRef } from "../themes.js";
 import { IntegrationCategory, IntegrationOwnershipMode } from "../integrations/spec.js";
 import { AppIntegrationBinding } from "../integrations/binding.js";
@@ -10,13 +9,15 @@ import { AppKnowledgeBinding } from "../knowledge/binding.js";
 import { BrandingDefaults, TenantBrandingConfig } from "./branding.js";
 import { Locale, TranslationEntry } from "../translations/catalog.js";
 import { ConfigStatus } from "./lifecycle.js";
+import { SpecContractRegistry } from "../registry.js";
+import { ExperimentRef } from "../experiments/spec.js";
 import { FeatureRef } from "../features/types.js";
 import "../features/index.js";
 
 //#region src/app-config/spec.d.ts
 interface SpecPointer {
   key: string;
-  version?: number;
+  version?: string;
 }
 interface AppRouteConfig {
   path: string;
@@ -29,7 +30,7 @@ interface AppRouteConfig {
 }
 interface TranslationCatalogPointer {
   key: string;
-  version: number;
+  version: string;
 }
 interface AppIntegrationSlot {
   /** Slot identifier unique within the blueprint (e.g., "primaryPayments"). */
@@ -90,11 +91,8 @@ interface AppBlueprintSpec {
   routes?: AppRouteConfig[];
   notes?: string;
 }
-declare class AppBlueprintRegistry {
-  private readonly items;
-  register(spec: AppBlueprintSpec): this;
-  list(): AppBlueprintSpec[];
-  get(key: string, version?: number): AppBlueprintSpec | undefined;
+declare class AppBlueprintRegistry extends SpecContractRegistry<'app-config', AppBlueprintSpec> {
+  constructor(items?: AppBlueprintSpec[]);
 }
 declare function makeAppBlueprintKey(meta: AppBlueprintMeta): string;
 interface TenantAppConfigMeta {
@@ -102,16 +100,16 @@ interface TenantAppConfigMeta {
   tenantId: string;
   appId: string;
   blueprintName: string;
-  blueprintVersion: number;
+  blueprintVersion: string;
   environment?: string;
   /** Monotonic version for auditing changes to the tenant config. */
-  version: number;
+  version: string;
   status: ConfigStatus;
   createdBy?: string;
   publishedBy?: string;
   publishedAt?: string | Date;
-  rolledBackFrom?: number;
-  rolledBackTo?: number;
+  rolledBackFrom?: string;
+  rolledBackTo?: string;
   changeSummary?: string;
   createdAt?: string | Date;
   updatedAt?: string | Date;

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-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[]);