@lssm/lib.contracts 1.42.10 → 1.43.2

package/README.md

@@ -30,6 +30,7 @@ bun add @lssm/lib.contracts @lssm/lib.schema
 ## Exports
 
 - **Core**: `OperationSpecRegistry`, `defineCommand`, `defineQuery`, `defineEvent`.
+- **Config**: `SchemaFormat` ('contractspec' | 'zod' | 'json-schema' | 'graphql').
 - **Adapters**:
   - `server/rest-next-app`: Next.js App Router adapter.
   - `server/provider-mcp`: Model Context Protocol (MCP) adapter for AI agents.

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

@@ -1,4 +1,5 @@
-import { FeatureModuleSpec } from "../features.js";
+import { FeatureModuleSpec } from "../features/types.js";
+import "../features/index.js";
 
 //#region src/app-config/app-config.feature.d.ts
 

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

@@ -1,39 +1,39 @@
-import "../operations/index.js";
 import { OperationSpec } from "../operations/operation.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
-import * as _lssm_lib_schema35 from "@lssm/lib.schema";
+import "../operations/index.js";
+import * as _lssm_lib_schema128 from "@lssm/lib.schema";
 import { SchemaModel } from "@lssm/lib.schema";
 
 //#region src/app-config/contracts.d.ts
 declare const UpdateTenantBrandingCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   environment: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
   };
   appName: {
-    type: _lssm_lib_schema35.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    type: _lssm_lib_schema128.FieldType<Record<string, unknown>, Record<string, unknown>>;
     isOptional: true;
   };
   assets: {
     type: SchemaModel<{
       type: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: false;
       };
       url: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: false;
       };
       mimeType: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -41,92 +41,92 @@ declare const UpdateTenantBrandingCommand: OperationSpec<SchemaModel<{
     isArray: true;
   };
   colors: {
-    type: _lssm_lib_schema35.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    type: _lssm_lib_schema128.FieldType<Record<string, unknown>, Record<string, unknown>>;
     isOptional: true;
   };
   customDomain: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
   };
   subdomain: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
   };
 }>, SchemaModel<{
   success: {
-    type: _lssm_lib_schema35.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema128.FieldType<boolean, boolean>;
     isOptional: false;
   };
   updatedAt: {
-    type: _lssm_lib_schema35.FieldType<Date, string>;
+    type: _lssm_lib_schema128.FieldType<Date, string>;
     isOptional: false;
   };
 }>, undefined>;
 declare const VerifyCustomDomainCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   domain: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   status: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   message: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
   };
 }>, undefined>;
 declare const UpdateBlueprintTranslationCatalogCommand: OperationSpec<SchemaModel<{
   blueprintName: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   blueprintVersion: {
-    type: _lssm_lib_schema35.FieldType<number, number>;
+    type: _lssm_lib_schema128.FieldType<number, number>;
     isOptional: false;
   };
   catalogName: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   catalogVersion: {
-    type: _lssm_lib_schema35.FieldType<number, number>;
+    type: _lssm_lib_schema128.FieldType<number, number>;
     isOptional: false;
   };
   defaultLocale: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   supportedLocales: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
     isArray: true;
   };
   entries: {
     type: SchemaModel<{
       key: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: false;
       };
       locale: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: false;
       };
       value: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: false;
       };
       context: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -135,39 +135,39 @@ declare const UpdateBlueprintTranslationCatalogCommand: OperationSpec<SchemaMode
   };
 }>, SchemaModel<{
   success: {
-    type: _lssm_lib_schema35.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema128.FieldType<boolean, boolean>;
     isOptional: false;
   };
   updatedAt: {
-    type: _lssm_lib_schema35.FieldType<Date, string>;
+    type: _lssm_lib_schema128.FieldType<Date, string>;
     isOptional: false;
   };
 }>, undefined>;
 declare const UpdateTenantTranslationOverridesCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   entries: {
     type: SchemaModel<{
       key: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: false;
       };
       locale: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: false;
       };
       value: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: false;
       };
       context: {
-        type: _lssm_lib_schema35.FieldType<string, string>;
+        type: _lssm_lib_schema128.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -175,67 +175,67 @@ declare const UpdateTenantTranslationOverridesCommand: OperationSpec<SchemaModel
     isArray: true;
   };
   defaultLocale: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
   };
   enabledLocales: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
 }>, SchemaModel<{
   success: {
-    type: _lssm_lib_schema35.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema128.FieldType<boolean, boolean>;
     isOptional: false;
   };
   updatedAt: {
-    type: _lssm_lib_schema35.FieldType<Date, string>;
+    type: _lssm_lib_schema128.FieldType<Date, string>;
     isOptional: false;
   };
 }>, undefined>;
 declare const GetResolvedBrandingQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   environment: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
   };
 }>, SchemaModel<{
   branding: {
-    type: _lssm_lib_schema35.FieldType<Record<string, unknown>, Record<string, unknown>>;
+    type: _lssm_lib_schema128.FieldType<Record<string, unknown>, Record<string, unknown>>;
     isOptional: false;
   };
 }>, undefined>;
 declare const ResolveMessageQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   locale: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
   key: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   value: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
   };
   source: {
-    type: _lssm_lib_schema35.FieldType<string, string>;
+    type: _lssm_lib_schema128.FieldType<string, string>;
     isOptional: true;
   };
 }>, undefined>;

package/dist/app-config/docs/app-config.docblock.js

@@ -13,7 +13,7 @@ const tech_contracts_app_config_DocBlocks = [{
 		"contracts",
 		"app-config"
 	],
-	body: "## App Configuration Layers\n\nApp orchestration is split into three explicit layers:\n\n1. **AppBlueprintSpec** – global, versioned description of what an app can look like. Stored in Git, no tenant/environment data.\n2. **TenantAppConfig** – tenant/environment overrides that the future Studio edits. Stored per tenant (DB/contract), mutable at runtime.\n3. **ResolvedAppConfig** – pure, merged view consumed by the runtime. Derived in-memory from a blueprint + tenant config.\n\n- Types & registry: `packages/libs/contracts/src/app-config/spec.ts`\n- Resolution helpers: `packages/libs/contracts/src/app-config/runtime.ts`\n- CLI wizard (blueprint scaffolding): `contractspec create app-config`\n\n### 1. AppBlueprintSpec\n\n```ts\nexport interface AppBlueprintSpec {\n  meta: AppBlueprintMeta;          // { name, version, appId, ownership }\n  capabilities?: { enabled?: CapabilityRef[]; disabled?: CapabilityRef[] };\n  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };\n  integrationSlots?: AppIntegrationSlot[];\n  branding?: BrandingDefaults;\n  dataViews?: Record<string, SpecPointer>;\n  workflows?: Record<string, SpecPointer>;\n  policies?: PolicyRef[];\n  theme?: AppThemeBinding;\n  telemetry?: TelemetryBinding;\n  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };\n  featureFlags?: FeatureFlagState[];\n  routes?: AppRouteConfig[];\n  notes?: string;\n}\n```\n\nRegister blueprints with `AppBlueprintRegistry`. Blueprints only capture the default/global experience.\n\n- **Integration slots** declare the categories and capability requirements an app expects (e.g. `\"primary-payments\"` must be a payments provider that supports managed or BYOK credentials). Slots never include secrets; tenants bind concrete connections later.\n- **Branding defaults** provide message-key based names, placeholder assets, and theme token references that downstream tenants can override.\n\n### 2. TenantAppConfig\n\n```ts\nexport interface TenantAppConfig {\n  meta: TenantAppConfigMeta;  // { id, tenantId, appId, blueprintName/version, environment?, version, timestamps }\n  capabilities?: { enable?: CapabilityRef[]; disable?: CapabilityRef[] };\n  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };\n  dataViewOverrides?: TenantSpecOverride[];\n  workflowOverrides?: TenantSpecOverride[];\n  additionalPolicies?: PolicyRef[];\n  themeOverride?: { primary?: ThemeRef | null; fallbacks?: ThemeRef[] };\n  telemetryOverride?: { spec?: SpecPointer | null; disabledEvents?: string[] };\n  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };\n  featureFlags?: FeatureFlagState[];\n  routeOverrides?: TenantRouteOverride[];\n  integrations?: AppIntegrationBinding[];\n  knowledge?: AppKnowledgeBinding[];\n  branding?: TenantBrandingConfig;\n  notes?: string;\n}\n```\n\nThis object represents what a tenant edits via the Studio (stored in DB/contracts later).\n\n- **AppIntegrationBinding** now maps `slotId` → `connectionId` (plus optional workflow scopes). It no longer carries capability lists; those are defined once in the slot.\n- **TenantBrandingConfig** allows per-tenant names, assets, and domain overrides while keeping secrets and large files out of blueprints.\n\n### 3. ResolvedAppConfig\n\n```ts\nexport interface ResolvedAppConfig {\n  appId: string;\n  tenantId: string;\n  environment?: string;\n  blueprintName: string;\n  blueprintVersion: number;\n  configVersion: number;\n  capabilities: { enabled: CapabilityRef[]; disabled: CapabilityRef[] };\n  features: { include: FeatureRef[]; exclude: FeatureRef[] };\n  dataViews: Record<string, SpecPointer>;\n  workflows: Record<string, SpecPointer>;\n  policies: PolicyRef[];\n  theme?: AppThemeBinding;\n  telemetry?: TelemetryBinding;\n  experiments: { catalog: ExperimentRef[]; active: ExperimentRef[]; paused: ExperimentRef[] };\n  featureFlags: FeatureFlagState[];\n  routes: AppRouteConfig[];\n  integrations: ResolvedIntegration[];\n  knowledge: ResolvedKnowledge[];\n  branding: ResolvedBranding;\n  notes?: string;\n}\n```\n\nUse `resolveAppConfig(blueprint, tenant)` to produce this merged view. No IO, no registry lookups—pure data merge.\n\n- `resolveAppConfig` validates slot/category/mode constraints when `integrationConnections` and `integrationSpecs` are provided.\n- `branding` merges blueprint defaults with tenant overrides, producing a runtime-friendly shape (resolved asset URLs, color values, and effective domain).\n\n### Materializing specs\n\n`composeAppConfig(blueprint, tenant, registries, { strict })`:\n\n1. Calls `resolveAppConfig` to build the merged pointers.\n2. Looks up referenced specs in the provided registries.\n3. Returns:\n   - `resolved` – the merged pointer view\n   - `capabilities`, `features`, `dataViews`, `workflows`, `policies`, `theme`, `telemetry`, `experiments`\n   - `missing` – unresolved references (strict mode throws).\n\n```ts\nconst blueprint = blueprintRegistry.get('core.app', 1)!;\nconst tenant = loadTenantConfigFromDB();\n\nconst composition = composeAppConfig(blueprint, tenant, {\n  capabilities,\n  features,\n  dataViews,\n  workflows,\n  policies,\n  themes,\n  telemetry,\n  experiments,\n});\n\nif (composition.missing.length) {\n  console.warn('Unresolved references', composition.missing);\n}\n```\n\n### CLI workflow\n\n```\ncontractspec create app-config\n```\n\nGenerates an `AppBlueprintSpec`. A separate flow will later scaffold tenant configs.\n\n### Best practices\n\n1. Keep blueprint and tenant versions monotonic; bump when referenced spec versions change.\n2. Favor stable slot keys (e.g. `dataViews.dashboard`) to align with Studio UX.\n3. Reference telemetry and experiments declared in their respective specs to maintain observability.\n4. Run `resolveAppConfig` in pure unit tests and `composeAppConfig(..., { strict: true })` in CI to catch drift early.\n5. Pair resolved configs with `TestSpec` scenarios to guard tenant experiences end-to-end.\n\n### Static validation\n\nUse the validation helpers in `@lssm/lib.contracts/app-config/validation` to keep blueprints and tenant configs safe before publish time.\n\n```ts\nimport {\n  validateConfig,\n  validateBlueprint,\n  validateTenantConfig,\n  validateResolvedConfig,\n} from '@lssm/lib.contracts/app-config/validation';\n\nconst context = {\n  integrationSpecs,\n  tenantConnections,\n  knowledgeSpaces,\n  knowledgeSources,\n  translationCatalogs: {\n    blueprint: blueprintCatalog,\n    platform: platformCatalog,\n  },\n  existingConfigs,\n};\n\nconst blueprintReport = validateBlueprint(blueprint, context);\nconst tenantReport = validateTenantConfig(blueprint, tenant, context);\nconst publishReport = validateConfig(blueprint, tenant, context);\n```\n\n- `ValidationResult` exposes `valid`, plus structured `errors`, `warnings`, and `info`.\n- Core rules cover capability references, integration slot bindings (category/ownership/capabilities), knowledge bindings, branding constraints (domains + assets), and translation coverage.\n- Call `validateBlueprint` in CI when committing new specs, and `validateConfig` before promoting/publishing a tenant config.\n- `validateResolvedConfig` can be used as a runtime pre-flight check when composing full configs for workflows.\n- CLI usage example (blueprint + tenant):\n\n```\npnpm contractspec validate \\\n  packages/examples/integration-stripe/blueprint.ts \\\n  --blueprint packages/examples/integration-stripe/blueprint.ts \\\n  --tenant-config packages/examples/integration-stripe/tenant.ts\n```\n- Repository script:\n\n```\nbun run validate:blueprints\n```\n\nRuns the static validator for the sample blueprints/tenants and is wired into CI.\n\n\n### Lifecycle types & events\n\nTo model multi-step configuration changes, use the lifecycle helpers exported from `@lssm/lib.contracts/app-config`:\n\n```ts\nimport type {\n  ConfigStatus,\n  TenantAppConfigVersion,\n  ConfigTransition,\n} from '@lssm/lib.contracts/app-config';\nimport {\n  ConfigDraftCreatedEvent,\n  ConfigPromotedToPreviewEvent,\n  ConfigPublishedEvent,\n  ConfigRolledBackEvent,\n} from '@lssm/lib.contracts/app-config';\n```\n\n- `ConfigStatus` enumerates the canonical states: `draft`, `preview`, `published`, `archived`, `superseded`.\n- `TenantAppConfigMeta` now includes lifecycle metadata (`status`, `createdBy`, `publishedBy`, `publishedAt`, `rolledBackFrom`, `rolledBackTo`, `changeSummary`).\n- `TenantAppConfigVersion` couples the lifecycle-aware metadata with the `TenantAppConfig` payload for history views.\n- `ConfigTransition` captures state changes with actor, timestamp, and optional reason.\n- Lifecycle events (`app_config.draft_created`, `app_config.promoted_to_preview`, `app_config.published`, `app_config.rolled_back`) standardize observability across services.\n- Lifecycle contract specs (`appConfig.lifecycle.*`) expose typed commands/queries for create → preview → publish → rollback flows.\n\n"
+	body: "## App Configuration Layers\n\nApp orchestration is split into three explicit layers:\n\n1. **AppBlueprintSpec** – global, versioned description of what an app can look like. Stored in Git, no tenant/environment data.\n2. **TenantAppConfig** – tenant/environment overrides that the future Studio edits. Stored per tenant (DB/contract), mutable at runtime.\n3. **ResolvedAppConfig** – pure, merged view consumed by the runtime. Derived in-memory from a blueprint + tenant config.\n\n- Types & registry: `packages/libs/contracts/src/app-config/spec.ts`\n- Resolution helpers: `packages/libs/contracts/src/app-config/runtime.ts`\n- CLI wizard (blueprint scaffolding): `contractspec create app-config`\n\n### 1. AppBlueprintSpec\n\n```ts\nexport interface AppBlueprintSpec {\n  meta: AppBlueprintMeta;          // { name, version, appId, ownership }\n  capabilities?: { enabled?: CapabilityRef[]; disabled?: CapabilityRef[] };\n  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };\n  integrationSlots?: AppIntegrationSlot[];\n  branding?: BrandingDefaults;\n  dataViews?: Record<string, SpecPointer>;\n  workflows?: Record<string, SpecPointer>;\n  policies?: PolicyRef[];\n  theme?: AppThemeBinding;\n  telemetry?: TelemetryBinding;\n  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };\n  featureFlags?: FeatureFlagState[];\n  routes?: AppRouteConfig[];\n  notes?: string;\n}\n```\n\nRegister blueprints with `AppBlueprintRegistry`. Blueprints only capture the default/global experience.\n\n- **Integration slots** declare the categories and capability requirements an app expects (e.g. `\"primary-payments\"` must be a payments provider that supports managed or BYOK credentials). Slots never include secrets; tenants bind concrete connections later.\n- **Branding defaults** provide message-key based names, placeholder assets, and theme token references that downstream tenants can override.\n\n### 2. TenantAppConfig\n\n```ts\nexport interface TenantAppConfig {\n  meta: TenantAppConfigMeta;  // { id, tenantId, appId, blueprintName/version, environment?, version, timestamps }\n  capabilities?: { enable?: CapabilityRef[]; disable?: CapabilityRef[] };\n  features?: { include?: FeatureRef[]; exclude?: FeatureRef[] };\n  dataViewOverrides?: TenantSpecOverride[];\n  workflowOverrides?: TenantSpecOverride[];\n  additionalPolicies?: PolicyRef[];\n  themeOverride?: { primary?: ThemeRef | null; fallbacks?: ThemeRef[] };\n  telemetryOverride?: { spec?: SpecPointer | null; disabledEvents?: string[] };\n  experiments?: { active?: ExperimentRef[]; paused?: ExperimentRef[] };\n  featureFlags?: FeatureFlagState[];\n  routeOverrides?: TenantRouteOverride[];\n  integrations?: AppIntegrationBinding[];\n  knowledge?: AppKnowledgeBinding[];\n  branding?: TenantBrandingConfig;\n  notes?: string;\n}\n```\n\nThis object represents what a tenant edits via the Studio (stored in DB/contracts later).\n\n- **AppIntegrationBinding** now maps `slotId` → `connectionId` (plus optional workflow scopes). It no longer carries capability lists; those are defined once in the slot.\n- **TenantBrandingConfig** allows per-tenant names, assets, and domain overrides while keeping secrets and large files out of blueprints.\n\n### 3. ResolvedAppConfig\n\n```ts\nexport interface ResolvedAppConfig {\n  appId: string;\n  tenantId: string;\n  environment?: string;\n  blueprintName: string;\n  blueprintVersion: number;\n  configVersion: number;\n  capabilities: { enabled: CapabilityRef[]; disabled: CapabilityRef[] };\n  features: { include: FeatureRef[]; exclude: FeatureRef[] };\n  dataViews: Record<string, SpecPointer>;\n  workflows: Record<string, SpecPointer>;\n  policies: PolicyRef[];\n  theme?: AppThemeBinding;\n  telemetry?: TelemetryBinding;\n  experiments: { catalog: ExperimentRef[]; active: ExperimentRef[]; paused: ExperimentRef[] };\n  featureFlags: FeatureFlagState[];\n  routes: AppRouteConfig[];\n  integrations: ResolvedIntegration[];\n  knowledge: ResolvedKnowledge[];\n  branding: ResolvedBranding;\n  notes?: string;\n}\n```\n\nUse `resolveAppConfig(blueprint, tenant)` to produce this merged view. No IO, no registry lookups—pure data merge.\n\n- `resolveAppConfig` validates slot/category/mode constraints when `integrationConnections` and `integrationSpecs` are provided.\n- `branding` merges blueprint defaults with tenant overrides, producing a runtime-friendly shape (resolved asset URLs, color values, and effective domain).\n\n### Materializing specs\n\n`composeAppConfig(blueprint, tenant, registries, { strict })`:\n\n1. Calls `resolveAppConfig` to build the merged pointers.\n2. Looks up referenced specs in the provided registries.\n3. Returns:\n   - `resolved` – the merged pointer view\n   - `capabilities`, `features`, `dataViews`, `workflows`, `policies`, `theme`, `telemetry`, `experiments`\n   - `missing` – unresolved references (strict mode throws).\n\n```ts\nconst blueprint = blueprintRegistry.get('core.app', 1)!;\nconst tenant = loadTenantConfigFromDB();\n\nconst composition = composeAppConfig(blueprint, tenant, {\n  capabilities,\n  features,\n  dataViews,\n  workflows,\n  policies,\n  themes,\n  telemetry,\n  experiments,\n});\n\nif (composition.missing.length) {\n  console.warn('Unresolved references', composition.missing);\n}\n```\n\n### CLI workflow\n\n```\ncontractspec create app-config\n```\n\nGenerates an `AppBlueprintSpec`. A separate flow will later scaffold tenant configs.\n\n### Best practices\n\n1. Keep blueprint and tenant versions monotonic; bump when referenced spec versions change.\n2. Favor stable slot keys (e.g. `dataViews.dashboard`) to align with Studio UX.\n3. Reference telemetry and experiments declared in their respective specs to maintain observability.\n4. Run `resolveAppConfig` in pure unit tests and `composeAppConfig(..., { strict: true })` in CI to catch drift early.\n5. Pair resolved configs with `TestSpec` scenarios to guard tenant experiences end-to-end.\n\n### Static validation\n\nUse the validation helpers in `@lssm/lib.contracts/app-config/validation` to keep blueprints and tenant configs safe before publish time.\n\n```ts\nimport {\n  validateConfig,\n  validateBlueprint,\n  validateTenantConfig,\n  validateResolvedConfig,\n} from '@lssm/lib.contracts/app-config/validation';\n\nconst context = {\n  integrationSpecs,\n  tenantConnections,\n  knowledgeSpaces,\n  knowledgeSources,\n  translationCatalogs: {\n    blueprint: blueprintCatalog,\n    platform: platformCatalog,\n  },\n  existingConfigs,\n};\n\nconst blueprintReport = validateBlueprint(blueprint, context);\nconst tenantReport = validateTenantConfig(blueprint, tenant, context);\nconst publishReport = validateConfig(blueprint, tenant, context);\n```\n\n- `ValidationResult` exposes `valid`, plus structured `errors`, `warnings`, and `info`.\n- Core rules cover capability references, integration slot bindings (category/ownership/capabilities), knowledge bindings, branding constraints (domains + assets), and translation coverage.\n- Call `validateBlueprint` in CI when committing new specs, and `validateConfig` before promoting/publishing a tenant config.\n- `validateResolvedConfig` can be used as a runtime pre-flight check when composing full configs for workflows.\n- CLI usage example (blueprint + tenant):\n\n```\nbuncontractspec validate \\\n  packages/examples/integration-stripe/blueprint.ts \\\n  --blueprint packages/examples/integration-stripe/blueprint.ts \\\n  --tenant-config packages/examples/integration-stripe/tenant.ts\n```\n- Repository script:\n\n```\nbun run validate:blueprints\n```\n\nRuns the static validator for the sample blueprints/tenants and is wired into CI.\n\n\n### Lifecycle types & events\n\nTo model multi-step configuration changes, use the lifecycle helpers exported from `@lssm/lib.contracts/app-config`:\n\n```ts\nimport type {\n  ConfigStatus,\n  TenantAppConfigVersion,\n  ConfigTransition,\n} from '@lssm/lib.contracts/app-config';\nimport {\n  ConfigDraftCreatedEvent,\n  ConfigPromotedToPreviewEvent,\n  ConfigPublishedEvent,\n  ConfigRolledBackEvent,\n} from '@lssm/lib.contracts/app-config';\n```\n\n- `ConfigStatus` enumerates the canonical states: `draft`, `preview`, `published`, `archived`, `superseded`.\n- `TenantAppConfigMeta` now includes lifecycle metadata (`status`, `createdBy`, `publishedBy`, `publishedAt`, `rolledBackFrom`, `rolledBackTo`, `changeSummary`).\n- `TenantAppConfigVersion` couples the lifecycle-aware metadata with the `TenantAppConfig` payload for history views.\n- `ConfigTransition` captures state changes with actor, timestamp, and optional reason.\n- Lifecycle events (`app_config.draft_created`, `app_config.promoted_to_preview`, `app_config.published`, `app_config.rolled_back`) standardize observability across services.\n- Lifecycle contract specs (`appConfig.lifecycle.*`) expose typed commands/queries for create → preview → publish → rollback flows.\n\n"
 }];
 registerDocBlocks(tech_contracts_app_config_DocBlocks);
 

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

@@ -1,120 +1,120 @@
 import { EventSpec } from "../events.js";
 import "../index.js";
-import * as _lssm_lib_schema84 from "@lssm/lib.schema";
+import * as _lssm_lib_schema177 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_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: false;
   };
   blueprintName: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   blueprintVersion: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: false;
   };
   createdBy: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   clonedFrom: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: true;
   };
 }>>;
 declare const ConfigPromotedToPreviewEvent: EventSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: false;
   };
   promotedBy: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   warnings: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
 }>>;
 declare const ConfigPublishedEvent: EventSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: false;
   };
   previousVersion: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: true;
   };
   publishedBy: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   changeSummary: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: true;
   };
   changedSections: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
 }>>;
 declare const ConfigRolledBackEvent: EventSpec<SchemaModel<{
   tenantId: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   newVersion: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: false;
   };
   rolledBackFrom: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: false;
   };
   rolledBackTo: {
-    type: _lssm_lib_schema84.FieldType<number, number>;
+    type: _lssm_lib_schema177.FieldType<number, number>;
     isOptional: false;
   };
   rolledBackBy: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
   reason: {
-    type: _lssm_lib_schema84.FieldType<string, string>;
+    type: _lssm_lib_schema177.FieldType<string, string>;
     isOptional: false;
   };
 }>>;