@lssm/lib.contracts 0.0.0-canary-20251220041653 → 0.0.0-canary-20251221114240

package/dist/app-config/lifecycle-contracts.d.ts

@@ -1,308 +1,308 @@
 import { EventSpec } from "../events.js";
-import { ContractSpec } from "../spec.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpec } from "../operation.js";
+import { OperationSpecRegistry } from "../registry.js";
 import "../index.js";
-import * as _lssm_lib_schema172 from "@lssm/lib.schema";
+import * as _lssm_lib_schema317 from "@lssm/lib.schema";
 import { SchemaModel } from "@lssm/lib.schema";
 
 //#region src/app-config/lifecycle-contracts.d.ts
-declare const CreateTenantConfigDraftCommand: ContractSpec<SchemaModel<{
+declare const CreateTenantConfigDraftCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   blueprintName: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   blueprintVersion: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
   environment: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: true;
   };
   fromVersion: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: true;
   };
   createdBy: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
   status: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   createdAt: {
-    type: _lssm_lib_schema172.FieldType<Date, string>;
+    type: _lssm_lib_schema317.FieldType<Date, string>;
     isOptional: false;
   };
 }>, {
   ref: EventSpec<SchemaModel<{
     tenantId: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     appId: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     version: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: false;
     };
     blueprintName: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     blueprintVersion: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: false;
     };
     createdBy: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     clonedFrom: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: true;
     };
   }>>;
   when: string;
 }[]>;
-declare const PromoteTenantConfigToPreviewCommand: ContractSpec<SchemaModel<{
+declare const PromoteTenantConfigToPreviewCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
   promotedBy: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
   status: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   warnings: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
 }>, {
   ref: EventSpec<SchemaModel<{
     tenantId: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     appId: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     version: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: false;
     };
     promotedBy: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     warnings: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: true;
       isArray: true;
     };
   }>>;
   when: string;
 }[]>;
-declare const PublishTenantConfigCommand: ContractSpec<SchemaModel<{
+declare const PublishTenantConfigCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
   environment: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: true;
   };
   publishedBy: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   changeSummary: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: true;
   };
 }>, SchemaModel<{
   version: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
   status: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   previousVersion: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: true;
   };
   publishedAt: {
-    type: _lssm_lib_schema172.FieldType<Date, string>;
+    type: _lssm_lib_schema317.FieldType<Date, string>;
     isOptional: false;
   };
 }>, {
   ref: EventSpec<SchemaModel<{
     tenantId: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     appId: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     version: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: false;
     };
     previousVersion: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: true;
     };
     publishedBy: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     changeSummary: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: true;
     };
     changedSections: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: true;
       isArray: true;
     };
   }>>;
   when: string;
 }[]>;
-declare const RollbackTenantConfigCommand: ContractSpec<SchemaModel<{
+declare const RollbackTenantConfigCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   toVersion: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
   environment: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: true;
   };
   rolledBackBy: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   reason: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   newVersion: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
   status: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   rolledBackFrom: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
 }>, {
   ref: EventSpec<SchemaModel<{
     tenantId: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     appId: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     newVersion: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: false;
     };
     rolledBackFrom: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: false;
     };
     rolledBackTo: {
-      type: _lssm_lib_schema172.FieldType<number, number>;
+      type: _lssm_lib_schema317.FieldType<number, number>;
       isOptional: false;
     };
     rolledBackBy: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
     reason: {
-      type: _lssm_lib_schema172.FieldType<string, string>;
+      type: _lssm_lib_schema317.FieldType<string, string>;
       isOptional: false;
     };
   }>>;
   when: string;
 }[]>;
-declare const ListTenantConfigVersionsQuery: ContractSpec<SchemaModel<{
+declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   versions: {
     type: SchemaModel<{
       meta: {
-        type: _lssm_lib_schema172.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _lssm_lib_schema317.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
       config: {
-        type: _lssm_lib_schema172.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _lssm_lib_schema317.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
     }>;
@@ -312,35 +312,35 @@ declare const ListTenantConfigVersionsQuery: ContractSpec<SchemaModel<{
   transitions: {
     type: SchemaModel<{
       tenantId: {
-        type: _lssm_lib_schema172.FieldType<string, string>;
+        type: _lssm_lib_schema317.FieldType<string, string>;
         isOptional: false;
       };
       appId: {
-        type: _lssm_lib_schema172.FieldType<string, string>;
+        type: _lssm_lib_schema317.FieldType<string, string>;
         isOptional: false;
       };
       fromStatus: {
-        type: _lssm_lib_schema172.FieldType<string, string>;
+        type: _lssm_lib_schema317.FieldType<string, string>;
         isOptional: false;
       };
       toStatus: {
-        type: _lssm_lib_schema172.FieldType<string, string>;
+        type: _lssm_lib_schema317.FieldType<string, string>;
         isOptional: false;
       };
       version: {
-        type: _lssm_lib_schema172.FieldType<number, number>;
+        type: _lssm_lib_schema317.FieldType<number, number>;
         isOptional: false;
       };
       timestamp: {
-        type: _lssm_lib_schema172.FieldType<Date, string>;
+        type: _lssm_lib_schema317.FieldType<Date, string>;
         isOptional: false;
       };
       actor: {
-        type: _lssm_lib_schema172.FieldType<string, string>;
+        type: _lssm_lib_schema317.FieldType<string, string>;
         isOptional: false;
       };
       reason: {
-        type: _lssm_lib_schema172.FieldType<string, string>;
+        type: _lssm_lib_schema317.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -348,35 +348,35 @@ declare const ListTenantConfigVersionsQuery: ContractSpec<SchemaModel<{
     isArray: true;
   };
 }>, undefined>;
-declare const GetTenantConfigVersionQuery: ContractSpec<SchemaModel<{
+declare const GetTenantConfigVersionQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema172.FieldType<string, string>;
+    type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema172.FieldType<number, number>;
+    type: _lssm_lib_schema317.FieldType<number, number>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
     type: SchemaModel<{
       meta: {
-        type: _lssm_lib_schema172.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _lssm_lib_schema317.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
       config: {
-        type: _lssm_lib_schema172.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _lssm_lib_schema317.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
     }>;
     isOptional: false;
   };
 }>, undefined>;
-declare const lifecycleContracts: Record<string, ContractSpec<any, any>>;
-declare function registerAppConfigLifecycleContracts(registry: SpecRegistry): SpecRegistry;
+declare const lifecycleContracts: Record<string, OperationSpec<any, any>>;
+declare function registerAppConfigLifecycleContracts(registry: OperationSpecRegistry): OperationSpecRegistry;
 //#endregion
 export { CreateTenantConfigDraftCommand, GetTenantConfigVersionQuery, ListTenantConfigVersionsQuery, PromoteTenantConfigToPreviewCommand, PublishTenantConfigCommand, RollbackTenantConfigCommand, lifecycleContracts, registerAppConfigLifecycleContracts };

package/dist/app-config/lifecycle-contracts.js

@@ -1,5 +1,5 @@
 import { E5, x8 } from "../schema/dist/index.js";
-import { defineCommand, defineQuery } from "../spec.js";
+import { defineCommand, defineQuery } from "../operation.js";
 import { OwnersEnum, StabilityEnum, TagsEnum } from "../ownership.js";
 import { ConfigDraftCreatedEvent, ConfigPromotedToPreviewEvent, ConfigPublishedEvent, ConfigRolledBackEvent } from "./events.js";
 

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

@@ -4,7 +4,7 @@ import { registerDocBlocks } from "../../registry.js";
 const tech_contracts_README_DocBlocks = [{
 	id: "docs.tech.contracts.README",
 	title: "Contracts: Specs, Registry, Handlers, Adapters",
-	summary: "- `packages/lssm/libs/contracts` defines the contracts core (SpecRegistry, ContractSpec, install helpers, REST/MCP adapters).",
+	summary: "- `packages/lssm/libs/contracts` defines the contracts core (OperationSpecRegistry, OperationSpec, PresentationSpec, install helpers, REST/MCP adapters, ...).",
 	kind: "reference",
 	visibility: "public",
 	route: "/docs/tech/contracts/README",
@@ -13,7 +13,7 @@ const tech_contracts_README_DocBlocks = [{
 		"contracts",
 		"README"
 	],
-	body: "## Contracts: Specs, Registry, Handlers, Adapters\n\n### What lives where\n\n- `packages/lssm/libs/contracts` defines the contracts core (SpecRegistry, ContractSpec, install helpers, REST/MCP adapters).\n- `packages/lssm/libs/schema` defines the schema dictionary (`SchemaModel`, `FieldType`) used to describe I/O once and map to multiple targets (zod, GraphQL, JSON Schema).\n- App adapters (e.g. GraphQL) live close to the app. Example: `packages/hcircle/apps/api-coliving/src/graphql/contracts-adapter.ts`.\n\n### npm distribution\n\n- `@lssm/lib.contracts` (root) keeps the legacy \\\"everything\\\" surface for backward compatibility.\n- `@lssm/lib.contracts/client` exposes only browser-safe helpers (React renderers, client SDK, drivers). Import from this entry when bundling for the web or React Native to avoid dragging server adapters.\n- `@lssm/lib.contracts/server` covers HTTP/MCP adapters, registries, integrations, and other Node-only helpers.\n- `@lssm/lib.contracts/types` exports the runtime handler context utilities, while `@lssm/lib.contracts/types/all` re-exports every type alias/interface across the package via `export type` so consumers can import a single module for typings without shipping runtime code.\n- `@lssm/lib.schema`, `@lssm/lib.design-system`, `@lssm/lib.ui-kit`, `@lssm/lib.ui-kit-web`, `@lssm/lib.accessibility`, and the presentation runtime packages are published to npm alongside contracts; prefer the scoped packages to keep tree-shaking intact.\n- Bundlers with conditional exports should resolve subpaths first; keep root imports for server-only code paths.\n\n### Core concepts\n\n- **ContractSpec**: immutable description of an operation.\n  - `meta`: `{ name, version, kind: 'query' | 'command' }`\n  - `io`: `{ input: SchemaModel | zod schema, output: SchemaModel | zod schema }`\n  - `policy`: `{ auth?: {...}, rateLimit?: {...}, flags?: string[] }`\n  - `transport.gql.field?`: explicit GraphQL field name (otherwise derived via `defaultGqlField`).\n- **SpecRegistry**: registry of specs + handlers. Use `installOp(reg, spec, handler)` to attach a handler.\n- **Handler**: `(ctx, input) => Promise<output>` implementing the operation.\n- **CapabilitySpec**: canonical capability declaration stored in `src/capabilities.ts`. Tracks `meta` (`{ key, version, kind, title, description, domain, owners, tags, stability }`), `provides` surfaces (`operation`, `event`, `workflow`, `presentation`, `resource`), and `requires` which other capabilities must be present. Enforced during `installFeature`.\n- **PolicySpec**: declarative policy rules (`src/policy/spec.ts`) covering ABAC/ReBAC, consent + rate limit requirements, field-level controls, and PII guidance. `PolicyEngine` evaluates refs, while `OPAPolicyAdapter` lets OPA override/augment runtime decisions.\n- **TelemetrySpec**: analytics definitions (`src/telemetry/spec.ts`) describing event semantics, privacy level, retention, sampling, and anomaly detection. `TelemetryTracker` handles redaction/sampling, `TelemetryAnomalyMonitor` raises alerts, and specs integrate with contracts/workflows via `ctx.telemetry`.\n- **TestSpec**: declarative scenario definitions in `src/tests/spec.ts`. `TestRunner` executes fixtures/actions/assertions against a `SpecRegistry`, and the CLI (`contractspec test`) wraps the runner for automation.\n- **ExperimentSpec**: experiment definitions (`src/experiments/spec.ts`) describing variants, allocation strategies, and success metrics. `ExperimentEvaluator` assigns variants (random/sticky/targeted) and integrates with Policy/Telemetry for safe experimentation.\n- **AppBlueprintSpec / TenantAppConfig**: global blueprints and per-tenant overrides (`src/app-config/spec.ts`). `resolveAppConfig()` merges the two into a `ResolvedAppConfig`, while `composeAppConfig()` hydrates the merged view against registries and reports missing references for safe rollout.\n- **RegeneratorService**: background daemon (`src/regenerator/service.ts`) that consumes telemetry/error/behavior signals, evaluates regeneration rules, and produces `SpecChangeProposal`s for Studio review.\n- **DataViewSpec**: declarative data presentation layer in `src/data-views.ts`. Describes entity projections (`fields`, `filters`, `actions`) with `view.kind` (`list`, `table`, `detail`, `grid`), ties to query operations via `source.primary`, and exposes optional presentation-based empty/error states.\n- **ThemeSpec**: design token + component variant definitions in `src/themes.ts`. Supports inheritance (`extends`), tenant/user overrides, and component-specific variant metadata for the design system.\n- **MigrationSpec**: schema/data migration descriptors (`src/migrations.ts`) with ordered step plans, dependency tracking, and pre/post checks to support automated database/content migrations.\n- **WorkflowSpec**: typed definition of multi-step workflows living in `src/workflow/spec.ts`. `WorkflowRegistry` stores versioned specs, and `validateWorkflowSpec()` (in `src/workflow/validation.ts`) checks graph integrity, step references, and reachability.\n\n### Lifecycle\n\n1. Define the spec (I/O via `SchemaModel` or zod) in a vertical lib (e.g. `contracts-coliving`).\n2. Register it: `installOp(registry, spec, handler)` within the app/service.\n3. Expose it via an adapter (REST, GraphQL, MCP). Each adapter maps the I/O to its transport and enforces policy.\n4. Validate at runtime: parse `input` before executing, parse `output` before returning.\n\n### Adapters\n\n- **REST**: see `packages/lssm/libs/contracts/src/server/rest-*`. Binds routes, validates request/response, maps errors/policies.\n- **MCP**: see `packages/lssm/libs/contracts/src/server/provider-mcp.ts` (standalone MCP server) and `packages/lssm/libs/contracts/src/server/rest-next-mcp.ts` (MCP over Next.js route). Provides tools/resources/prompts.\n  - Tools + resources are registered from Zod schemas.\n  - Resource templates are keyed by full `ResourceMeta.uriTemplate` (e.g. `docs://list`, `docs://doc/{id}`), so multiple templates can share a scheme (`docs://*`) without collisions.\n- **GraphQL (Pothos)**: see `packages/lssm/libs/contracts/src/server/graphql-pothos.ts`. Adds Query/Mutation fields by transforming contract I/O to GraphQL types.\n\n### GraphQL adapter behaviour (summary)\n\n- Field naming: `spec.transport.gql.field` or `<name_with_dots>_v<version>`.\n- Input/Output types from `SchemaModel` (preferred) or fallback zod introspection.\n- Scalars: String/Int/Float/Boolean/Date/JSON; Objects/Arrays/Enums; unions for outputs; input unions => JSON.\n- Policy: auth gate checks GraphQL context; optional feature flag gating.\n- Complexity & tracing: attaches hints and records timings; log includes `{ specName, version }`.\n\n#### Returns mapping and hydration\n\n- `spec.transport.gql.returns` can declare the GraphQL return wrapper: e.g. `\"Spot\"` or `[Spot]`. If omitted, the adapter infers from `io.output` (SchemaModel) or `resourceRef.graphQLType`.\n- Resource outputs: when `io.output` is a `resourceRef(...)` or `transport.gql.resource` is set, the adapter will optionally hydrate via a `ResourceRegistry` using `contracts-adapter-hydration.ts`:\n  - Grammar is parsed with `parseReturns()`.\n  - Entities are resolved via `hydrateResourceIfNeeded(resources, result, { template, varName, returns })` after handler execution.\n\n### Resource outputs\n\n- Declare resource outputs using `resourceRef(uriTemplate, opts)`.\n- `opts.varName` (default `id`) selects the identifier field returned by the handler for URI substitution.\n- `opts.graphQLType` is the GraphQL return type name (e.g., `Spot`) or list form (e.g., `[Spot]`).\n- `opts.many: true` indicates the handler returns an array of resources. The handler type becomes an array of items that include the identifier field.\n\nExample:\n\n```ts\nio: {\n  input: ListThingsInput,\n  output: resourceRef('myapp://thing/{id}', { graphQLType: '[Thing]', many: true }),\n}\n```\n\nHandler return (simplified): `{ id: string | number }[]`.\n\n### Errors\n\n- Validation errors → transport 400/GraphQL UserInputError.\n- Policy/auth errors → 401/403 or GraphQL ForbiddenError.\n- Handler errors → mapped to transport error with safe message.\n\n### Versioning & naming\n\n- Keep `meta.version` monotonic. Clients should pin to a versioned field/key.\n- Avoid renaming existing fields; add new fields with new versions.\n\n### Ownership metadata (OwnerShipMeta)\n\nAll contracts, events, features, and presentations reference a shared ownership schema (source of truth in `packages/lssm/libs/contracts/src/ownership.ts`).\n\n- Required fields: `title`, `description`, `domain`, `owners[]`, `tags[]`, `stability`.\n- Curated enums: the library exports suggested constants for owners and tags; free-form strings are still allowed for forward-compatibility.\n- Operations (`spec.ts`): `meta` requires `stability`, `owners`, and `tags` alongside `name`, `version`, `kind`, `description`, `goal`, and `context`.\n- Presentations V2: `meta` is a partial of ownership plus `description`.\n- Events: may specify `ownership` (recommended) for discoverability and docs.\n\n### Quick start\n\n```ts\n// app bootstrap\nconst reg = new SpecRegistry();\ninstallOp(reg, BeginSignupSpec, beginSignupHandler);\nregisterContractsOnBuilder(gqlSchemaBuilder, reg); // GraphQL\n// or: createRestRouter(reg) // REST\n```\n"
+	body: "## Contracts: Specs, Registry, Handlers, Adapters\n\n### What lives where\n\n- `packages/lssm/libs/contracts` defines the contracts core (OperationSpecRegistry, OperationSpec, PresentationSpec, install helpers, REST/MCP adapters).\n- `packages/lssm/libs/schema` defines the schema dictionary (`SchemaModel`, `FieldType`) used to describe I/O once and map to multiple targets (zod, GraphQL, JSON Schema).\n- App adapters (e.g. GraphQL) live close to the app. Example: `packages/hcircle/apps/api-coliving/src/graphql/contracts-adapter.ts`.\n\n### npm distribution\n\n- `@lssm/lib.contracts` (root) keeps the legacy \\\"everything\\\" surface for backward compatibility.\n- `@lssm/lib.contracts/client` exposes only browser-safe helpers (React renderers, client SDK, drivers). Import from this entry when bundling for the web or React Native to avoid dragging server adapters.\n- `@lssm/lib.contracts/server` covers HTTP/MCP adapters, registries, integrations, and other Node-only helpers.\n- `@lssm/lib.contracts/types` exports the runtime handler context utilities, while `@lssm/lib.contracts/types/all` re-exports every type alias/interface across the package via `export type` so consumers can import a single module for typings without shipping runtime code.\n- `@lssm/lib.schema`, `@lssm/lib.design-system`, `@lssm/lib.ui-kit`, `@lssm/lib.ui-kit-web`, `@lssm/lib.accessibility`, and the presentation runtime packages are published to npm alongside contracts; prefer the scoped packages to keep tree-shaking intact.\n- Bundlers with conditional exports should resolve subpaths first; keep root imports for server-only code paths.\n\n### Core concepts\n\n- **OperationSpec**: immutable description of an operation.\n  - `meta`: `{ name, version, kind: 'query' | 'command' }`\n  - `io`: `{ input: SchemaModel | zod schema, output: SchemaModel | zod schema }`\n  - `policy`: `{ auth?: {...}, rateLimit?: {...}, flags?: string[] }`\n  - `transport.gql.field?`: explicit GraphQL field name (otherwise derived via `defaultGqlField`).\n- **OperationSpecRegistry**: registry of specs + handlers. Use `installOp(reg, spec, handler)` to attach a handler.\n- **Handler**: `(ctx, input) => Promise<output>` implementing the operation.\n- **CapabilitySpec**: canonical capability declaration stored in `src/capabilities.ts`. Tracks `meta` (`{ key, version, kind, title, description, domain, owners, tags, stability }`), `provides` surfaces (`operation`, `event`, `workflow`, `presentation`, `resource`), and `requires` which other capabilities must be present. Enforced during `installFeature`.\n- **PolicySpec**: declarative policy rules (`src/policy/spec.ts`) covering ABAC/ReBAC, consent + rate limit requirements, field-level controls, and PII guidance. `PolicyEngine` evaluates refs, while `OPAPolicyAdapter` lets OPA override/augment runtime decisions.\n- **TelemetrySpec**: analytics definitions (`src/telemetry/spec.ts`) describing event semantics, privacy level, retention, sampling, and anomaly detection. `TelemetryTracker` handles redaction/sampling, `TelemetryAnomalyMonitor` raises alerts, and specs integrate with contracts/workflows via `ctx.telemetry`.\n- **TestSpec**: declarative scenario definitions in `src/tests/spec.ts`. `TestRunner` executes fixtures/actions/assertions against a `OperationSpecRegistry`, and the CLI (`contractspec test`) wraps the runner for automation.\n- **ExperimentSpec**: experiment definitions (`src/experiments/spec.ts`) describing variants, allocation strategies, and success metrics. `ExperimentEvaluator` assigns variants (random/sticky/targeted) and integrates with Policy/Telemetry for safe experimentation.\n- **AppBlueprintSpec / TenantAppConfig**: global blueprints and per-tenant overrides (`src/app-config/spec.ts`). `resolveAppConfig()` merges the two into a `ResolvedAppConfig`, while `composeAppConfig()` hydrates the merged view against registries and reports missing references for safe rollout.\n- **RegeneratorService**: background daemon (`src/regenerator/service.ts`) that consumes telemetry/error/behavior signals, evaluates regeneration rules, and produces `SpecChangeProposal`s for Studio review.\n- **DataViewSpec**: declarative data presentation layer in `src/data-views.ts`. Describes entity projections (`fields`, `filters`, `actions`) with `view.kind` (`list`, `table`, `detail`, `grid`), ties to query operations via `source.primary`, and exposes optional presentation-based empty/error states.\n- **ThemeSpec**: design token + component variant definitions in `src/themes.ts`. Supports inheritance (`extends`), tenant/user overrides, and component-specific variant metadata for the design system.\n- **MigrationSpec**: schema/data migration descriptors (`src/migrations.ts`) with ordered step plans, dependency tracking, and pre/post checks to support automated database/content migrations.\n- **WorkflowSpec**: typed definition of multi-step workflows living in `src/workflow/spec.ts`. `WorkflowRegistry` stores versioned specs, and `validateWorkflowSpec()` (in `src/workflow/validation.ts`) checks graph integrity, step references, and reachability.\n\n### Lifecycle\n\n1. Define the spec (I/O via `SchemaModel` or zod) in a vertical lib (e.g. `contracts-coliving`).\n2. Register it: `installOp(registry, spec, handler)` within the app/service.\n3. Expose it via an adapter (REST, GraphQL, MCP). Each adapter maps the I/O to its transport and enforces policy.\n4. Validate at runtime: parse `input` before executing, parse `output` before returning.\n\n### Adapters\n\n- **REST**: see `packages/lssm/libs/contracts/src/server/rest-*`. Binds routes, validates request/response, maps errors/policies.\n- **MCP**: see `packages/lssm/libs/contracts/src/server/provider-mcp.ts` (standalone MCP server) and `packages/lssm/libs/contracts/src/server/rest-next-mcp.ts` (MCP over Next.js route). Provides tools/resources/prompts.\n  - Tools + resources are registered from Zod schemas.\n  - Resource templates are keyed by full `ResourceMeta.uriTemplate` (e.g. `docs://list`, `docs://doc/{id}`), so multiple templates can share a scheme (`docs://*`) without collisions.\n- **GraphQL (Pothos)**: see `packages/lssm/libs/contracts/src/server/graphql-pothos.ts`. Adds Query/Mutation fields by transforming contract I/O to GraphQL types.\n\n### GraphQL adapter behaviour (summary)\n\n- Field naming: `spec.transport.gql.field` or `<name_with_dots>_v<version>`.\n- Input/Output types from `SchemaModel` (preferred) or fallback zod introspection.\n- Scalars: String/Int/Float/Boolean/Date/JSON; Objects/Arrays/Enums; unions for outputs; input unions => JSON.\n- Policy: auth gate checks GraphQL context; optional feature flag gating.\n- Complexity & tracing: attaches hints and records timings; log includes `{ specName, version }`.\n\n#### Returns mapping and hydration\n\n- `spec.transport.gql.returns` can declare the GraphQL return wrapper: e.g. `\"Spot\"` or `[Spot]`. If omitted, the adapter infers from `io.output` (SchemaModel) or `resourceRef.graphQLType`.\n- Resource outputs: when `io.output` is a `resourceRef(...)` or `transport.gql.resource` is set, the adapter will optionally hydrate via a `ResourceRegistry` using `contracts-adapter-hydration.ts`:\n  - Grammar is parsed with `parseReturns()`.\n  - Entities are resolved via `hydrateResourceIfNeeded(resources, result, { template, varName, returns })` after handler execution.\n\n### Resource outputs\n\n- Declare resource outputs using `resourceRef(uriTemplate, opts)`.\n- `opts.varName` (default `id`) selects the identifier field returned by the handler for URI substitution.\n- `opts.graphQLType` is the GraphQL return type name (e.g., `Spot`) or list form (e.g., `[Spot]`).\n- `opts.many: true` indicates the handler returns an array of resources. The handler type becomes an array of items that include the identifier field.\n\nExample:\n\n```ts\nio: {\n  input: ListThingsInput,\n  output: resourceRef('myapp://thing/{id}', { graphQLType: '[Thing]', many: true }),\n}\n```\n\nHandler return (simplified): `{ id: string | number }[]`.\n\n### Errors\n\n- Validation errors → transport 400/GraphQL UserInputError.\n- Policy/auth errors → 401/403 or GraphQL ForbiddenError.\n- Handler errors → mapped to transport error with safe message.\n\n### Versioning & naming\n\n- Keep `meta.version` monotonic. Clients should pin to a versioned field/key.\n- Avoid renaming existing fields; add new fields with new versions.\n\n### Ownership metadata (OwnerShipMeta)\n\nAll contracts, events, features, and presentations reference a shared ownership schema (source of truth in `packages/lssm/libs/contracts/src/ownership.ts`).\n\n- Required fields: `title`, `description`, `domain`, `owners[]`, `tags[]`, `stability`.\n- Curated enums: the library exports suggested constants for owners and tags; free-form strings are still allowed for forward-compatibility.\n- Operations (`spec.ts`): `meta` requires `stability`, `owners`, and `tags` alongside `name`, `version`, `kind`, `description`, `goal`, and `context`.\n- Presentations V2: `meta` is a partial of ownership plus `description`.\n- Events: may specify `ownership` (recommended) for discoverability and docs.\n\n### Quick start\n\n```ts\n// app bootstrap\nconst reg = new OperationSpecRegistry();\ninstallOp(reg, BeginSignupSpec, beginSignupHandler);\nregisterContractsOnBuilder(gqlSchemaBuilder, reg); // GraphQL\n// or: createRestRouter(reg) // REST\n```\n"
 }];
 registerDocBlocks(tech_contracts_README_DocBlocks);
 

package/dist/docs/tech/contracts/openapi-export.docblock.js

@@ -3,8 +3,8 @@ import { registerDocBlocks } from "../../registry.js";
 //#region src/docs/tech/contracts/openapi-export.docblock.ts
 const tech_contracts_openapi_export_DocBlocks = [{
 	id: "docs.tech.contracts.openapi-export",
-	title: "OpenAPI export (OpenAPI 3.1) from SpecRegistry",
-	summary: "Generate a deterministic OpenAPI document from a SpecRegistry using jsonSchemaForSpec + REST transport metadata.",
+	title: "OpenAPI export (OpenAPI 3.1) from OperationSpecRegistry",
+	summary: "Generate a deterministic OpenAPI document from a OperationSpecRegistry using jsonSchemaForSpec + REST transport metadata.",
 	kind: "reference",
 	visibility: "public",
 	route: "/docs/tech/contracts/openapi-export",
@@ -13,7 +13,7 @@ const tech_contracts_openapi_export_DocBlocks = [{
 		"openapi",
 		"rest"
 	],
-	body: `## OpenAPI export (OpenAPI 3.1) from SpecRegistry
+	body: `## OpenAPI export (OpenAPI 3.1) from OperationSpecRegistry
 
 ### Purpose
 
@@ -42,9 +42,9 @@ contractspec openapi --registry ./src/registry.ts --out ./openapi.json
 
 The registry module must export one of:
 
-- \`registry: SpecRegistry\`
-- \`default(): SpecRegistry | Promise<SpecRegistry>\`
-- \`createRegistry(): SpecRegistry | Promise<SpecRegistry>\`
+- \`registry: OperationSpecRegistry\`
+- \`default(): OperationSpecRegistry | Promise<OperationSpecRegistry>\`
+- \`createRegistry(): OperationSpecRegistry | Promise<OperationSpecRegistry>\`
 
 ### Notes / limitations (current)
 

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

@@ -4,7 +4,7 @@ import { registerDocBlocks } from "../../registry.js";
 const tech_contracts_ops_to_presentation_linking_DocBlocks = [{
 	id: "docs.tech.contracts.ops-to-presentation-linking",
 	title: "Ops ↔ Presentation linking (V2)",
-	summary: "This document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.",
+	summary: "This document explains how operations (OperationSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.",
 	kind: "reference",
 	visibility: "public",
 	route: "/docs/tech/contracts/ops-to-presentation-linking",
@@ -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 (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.\n\n- Location: `@lssm/lib.contracts/src/features.ts`\n- Field: `FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]`\n- Validation: `installFeature()` validates that linked ops exist in `SpecRegistry` and linked presentations exist in the registry, and that declared targets are present.\n\nExample:\n\n```ts\nimport type { SpecRegistry } from '@lssm/lib.contracts/src/registry';\nimport { FeatureRegistry, createFeatureModule } from '@lssm/lib.contracts';\n\nexport function buildFeaturesWithOps(ops: SpecRegistry) {\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 (PresentationDescriptorV2) via Feature modules.\n\n- Location: `@lssm/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 '@lssm/lib.contracts/src/registry';\nimport { FeatureRegistry, createFeatureModule } from '@lssm/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"
 }];
 registerDocBlocks(tech_contracts_ops_to_presentation_linking_DocBlocks);
 

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

@@ -4,7 +4,7 @@ import { registerDocBlocks } from "../../registry.js";
 const tech_contracts_tests_DocBlocks = [{
 	id: "docs.tech.contracts.tests",
 	title: "TestSpec & TestRunner",
-	summary: "Use `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same SpecRegistry handlers the app uses.",
+	summary: "Use `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.",
 	kind: "reference",
 	visibility: "public",
 	route: "/docs/tech/contracts/tests",
@@ -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 SpecRegistry 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 '@lssm/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 `SpecRegistry`:\n\n```ts\nexport function createRegistry() {\n  const registry = new SpecRegistry();\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 '@lssm/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"
 }];
 registerDocBlocks(tech_contracts_tests_DocBlocks);
 

package/dist/experiments/spec-resolver.d.ts

@@ -1,10 +1,10 @@
 import { ResourceRefDescriptor } from "../resources.js";
-import { ContractSpec, OpKind } from "../spec.js";
+import { OpKind, OperationSpec } from "../operation.js";
 import { HandlerCtx } from "../types.js";
 import { AnySchemaModel } from "@lssm/lib.schema";
 
 //#region src/experiments/spec-resolver.d.ts
-type RuntimeContract = ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+type RuntimeContract = OperationSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
 interface SpecVariantResolver {
   resolve(operation: {
     name: string;