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

package/README.md

@@ -19,14 +19,14 @@ bun add @lssm/lib.contracts @lssm/lib.schema
 ## Key Concepts
 
 - **Spec-First, TypeScript-First**: Define operations in pure TypeScript (no YAML).
-- **Runtime Adapters**: The `SpecRegistry` is passed to adapters (e.g., `makeNextAppHandler`) to serve APIs dynamically. There is no intermediate "compile" step to generate code; the spec _is_ the code.
+- **Runtime Adapters**: The `OperationSpecRegistry` is passed to adapters (e.g., `makeNextAppHandler`) to serve APIs dynamically. There is no intermediate "compile" step to generate code; the spec _is_ the code.
 - **Capabilities**: `defineCommand` (writes) and `defineQuery` (reads) with Zod-backed I/O.
 - **Events**: `defineEvent` for type-safe side effects.
 - **Presentations**: (V2) Describe how data is rendered (Web Components, Markdown, Data) for automated UI generation.
 
 ## Exports
 
-- **Core**: `SpecRegistry`, `defineCommand`, `defineQuery`, `defineEvent`.
+- **Core**: `OperationSpecRegistry`, `defineCommand`, `defineQuery`, `defineEvent`.
 - **Adapters**:
   - `server/rest-next-app`: Next.js App Router adapter.
   - `server/provider-mcp`: Model Context Protocol (MCP) adapter for AI agents.
@@ -78,9 +78,9 @@ export const CreateUser = defineCommand({
 ### 2. Register and Implement
 
 ```ts
-import { SpecRegistry, installOp } from '@lssm/lib.contracts';
+import { OperationSpecRegistry, installOp } from '@lssm/lib.contracts';
 
-const reg = new SpecRegistry();
+const reg = new OperationSpecRegistry();
 
 installOp(reg, CreateUser, async (ctx, input) => {
   // Implementation logic here

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

@@ -1,38 +1,38 @@
-import { ContractSpec } from "../spec.js";
-import { SpecRegistry } from "../registry.js";
-import * as _lssm_lib_schema206 from "@lssm/lib.schema";
+import { OperationSpec } from "../operation.js";
+import { OperationSpecRegistry } from "../registry.js";
+import * as _lssm_lib_schema242 from "@lssm/lib.schema";
 import { SchemaModel } from "@lssm/lib.schema";
 
 //#region src/app-config/contracts.d.ts
-declare const UpdateTenantBrandingCommand: ContractSpec<SchemaModel<{
+declare const UpdateTenantBrandingCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   environment: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
   };
   appName: {
-    type: _lssm_lib_schema206.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    type: _lssm_lib_schema242.FieldType<Record<string, unknown>, Record<string, unknown>>;
     isOptional: true;
   };
   assets: {
     type: SchemaModel<{
       type: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: false;
       };
       url: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: false;
       };
       mimeType: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -40,92 +40,92 @@ declare const UpdateTenantBrandingCommand: ContractSpec<SchemaModel<{
     isArray: true;
   };
   colors: {
-    type: _lssm_lib_schema206.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    type: _lssm_lib_schema242.FieldType<Record<string, unknown>, Record<string, unknown>>;
     isOptional: true;
   };
   customDomain: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
   };
   subdomain: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
   };
 }>, SchemaModel<{
   success: {
-    type: _lssm_lib_schema206.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema242.FieldType<boolean, boolean>;
     isOptional: false;
   };
   updatedAt: {
-    type: _lssm_lib_schema206.FieldType<Date, string>;
+    type: _lssm_lib_schema242.FieldType<Date, string>;
     isOptional: false;
   };
 }>, undefined>;
-declare const VerifyCustomDomainCommand: ContractSpec<SchemaModel<{
+declare const VerifyCustomDomainCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   domain: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   status: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   message: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
   };
 }>, undefined>;
-declare const UpdateBlueprintTranslationCatalogCommand: ContractSpec<SchemaModel<{
+declare const UpdateBlueprintTranslationCatalogCommand: OperationSpec<SchemaModel<{
   blueprintName: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   blueprintVersion: {
-    type: _lssm_lib_schema206.FieldType<number, number>;
+    type: _lssm_lib_schema242.FieldType<number, number>;
     isOptional: false;
   };
   catalogName: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   catalogVersion: {
-    type: _lssm_lib_schema206.FieldType<number, number>;
+    type: _lssm_lib_schema242.FieldType<number, number>;
     isOptional: false;
   };
   defaultLocale: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   supportedLocales: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
     isArray: true;
   };
   entries: {
     type: SchemaModel<{
       key: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: false;
       };
       locale: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: false;
       };
       value: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: false;
       };
       context: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -134,39 +134,39 @@ declare const UpdateBlueprintTranslationCatalogCommand: ContractSpec<SchemaModel
   };
 }>, SchemaModel<{
   success: {
-    type: _lssm_lib_schema206.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema242.FieldType<boolean, boolean>;
     isOptional: false;
   };
   updatedAt: {
-    type: _lssm_lib_schema206.FieldType<Date, string>;
+    type: _lssm_lib_schema242.FieldType<Date, string>;
     isOptional: false;
   };
 }>, undefined>;
-declare const UpdateTenantTranslationOverridesCommand: ContractSpec<SchemaModel<{
+declare const UpdateTenantTranslationOverridesCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   entries: {
     type: SchemaModel<{
       key: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: false;
       };
       locale: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: false;
       };
       value: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: false;
       };
       context: {
-        type: _lssm_lib_schema206.FieldType<string, string>;
+        type: _lssm_lib_schema242.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -174,71 +174,71 @@ declare const UpdateTenantTranslationOverridesCommand: ContractSpec<SchemaModel<
     isArray: true;
   };
   defaultLocale: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
   };
   enabledLocales: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
 }>, SchemaModel<{
   success: {
-    type: _lssm_lib_schema206.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema242.FieldType<boolean, boolean>;
     isOptional: false;
   };
   updatedAt: {
-    type: _lssm_lib_schema206.FieldType<Date, string>;
+    type: _lssm_lib_schema242.FieldType<Date, string>;
     isOptional: false;
   };
 }>, undefined>;
-declare const GetResolvedBrandingQuery: ContractSpec<SchemaModel<{
+declare const GetResolvedBrandingQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   environment: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
   };
 }>, SchemaModel<{
   branding: {
-    type: _lssm_lib_schema206.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    type: _lssm_lib_schema242.FieldType<Record<string, unknown>, Record<string, unknown>>;
     isOptional: false;
   };
 }>, undefined>;
-declare const ResolveMessageQuery: ContractSpec<SchemaModel<{
+declare const ResolveMessageQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   locale: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
   key: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   value: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
   };
   source: {
-    type: _lssm_lib_schema206.FieldType<string, string>;
+    type: _lssm_lib_schema242.FieldType<string, string>;
     isOptional: true;
   };
 }>, undefined>;
-declare const appConfigContracts: Record<string, ContractSpec<any, any>>;
-declare function registerAppConfigContracts(registry: SpecRegistry): SpecRegistry;
+declare const appConfigContracts: Record<string, OperationSpec<any, any>>;
+declare function registerAppConfigContracts(registry: OperationSpecRegistry): OperationSpecRegistry;
 //#endregion
 export { GetResolvedBrandingQuery, ResolveMessageQuery, UpdateBlueprintTranslationCatalogCommand, UpdateTenantBrandingCommand, UpdateTenantTranslationOverridesCommand, VerifyCustomDomainCommand, appConfigContracts, registerAppConfigContracts };

package/dist/app-config/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";
 
 //#region src/app-config/contracts.ts

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

@@ -1,120 +1,120 @@
 import { EventSpec } from "../events.js";
 import "../index.js";
-import * as _lssm_lib_schema263 from "@lssm/lib.schema";
+import * as _lssm_lib_schema291 from "@lssm/lib.schema";
 import { SchemaModel } from "@lssm/lib.schema";
 
 //#region src/app-config/events.d.ts
 declare const ConfigDraftCreatedEvent: EventSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: false;
   };
   blueprintName: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   blueprintVersion: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: false;
   };
   createdBy: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   clonedFrom: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: true;
   };
 }>>;
 declare const ConfigPromotedToPreviewEvent: EventSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: false;
   };
   promotedBy: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   warnings: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
 }>>;
 declare const ConfigPublishedEvent: EventSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: false;
   };
   previousVersion: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: true;
   };
   publishedBy: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   changeSummary: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: true;
   };
   changedSections: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
 }>>;
 declare const ConfigRolledBackEvent: EventSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   newVersion: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: false;
   };
   rolledBackFrom: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: false;
   };
   rolledBackTo: {
-    type: _lssm_lib_schema263.FieldType<number, number>;
+    type: _lssm_lib_schema291.FieldType<number, number>;
     isOptional: false;
   };
   rolledBackBy: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
   reason: {
-    type: _lssm_lib_schema263.FieldType<string, string>;
+    type: _lssm_lib_schema291.FieldType<string, string>;
     isOptional: false;
   };
 }>>;

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

@@ -1,12 +1,12 @@
 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_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_schema317.FieldType<string, string>;
     isOptional: false;
@@ -81,7 +81,7 @@ declare const CreateTenantConfigDraftCommand: ContractSpec<SchemaModel<{
   }>>;
   when: string;
 }[]>;
-declare const PromoteTenantConfigToPreviewCommand: ContractSpec<SchemaModel<{
+declare const PromoteTenantConfigToPreviewCommand: OperationSpec<SchemaModel<{
   tenantId: {
     type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
@@ -138,7 +138,7 @@ declare const PromoteTenantConfigToPreviewCommand: ContractSpec<SchemaModel<{
   }>>;
   when: string;
 }[]>;
-declare const PublishTenantConfigCommand: ContractSpec<SchemaModel<{
+declare const PublishTenantConfigCommand: OperationSpec<SchemaModel<{
   tenantId: {
     type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
@@ -214,7 +214,7 @@ declare const PublishTenantConfigCommand: ContractSpec<SchemaModel<{
   }>>;
   when: string;
 }[]>;
-declare const RollbackTenantConfigCommand: ContractSpec<SchemaModel<{
+declare const RollbackTenantConfigCommand: OperationSpec<SchemaModel<{
   tenantId: {
     type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
@@ -285,7 +285,7 @@ declare const RollbackTenantConfigCommand: ContractSpec<SchemaModel<{
   }>>;
   when: string;
 }[]>;
-declare const ListTenantConfigVersionsQuery: ContractSpec<SchemaModel<{
+declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
   tenantId: {
     type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
@@ -348,7 +348,7 @@ declare const ListTenantConfigVersionsQuery: ContractSpec<SchemaModel<{
     isArray: true;
   };
 }>, undefined>;
-declare const GetTenantConfigVersionQuery: ContractSpec<SchemaModel<{
+declare const GetTenantConfigVersionQuery: OperationSpec<SchemaModel<{
   tenantId: {
     type: _lssm_lib_schema317.FieldType<string, string>;
     isOptional: false;
@@ -376,7 +376,7 @@ declare const GetTenantConfigVersionQuery: ContractSpec<SchemaModel<{
     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);