@contractspec/lib.contracts 1.44.0

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

@@ -0,0 +1,440 @@
+import { OwnersEnum, StabilityEnum, TagsEnum } from "../ownership.js";
+import { defineCommand, defineQuery } from "../operations/operation.js";
+import "../operations/index.js";
+import { ConfigDraftCreatedEvent, ConfigPromotedToPreviewEvent, ConfigPublishedEvent, ConfigRolledBackEvent } from "./events.js";
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/app-config/lifecycle-contracts.ts
+const LifecyclePolicy = {
+	auth: "admin",
+	policies: [{
+		key: "platform.app-config.manage",
+		version: 1
+	}]
+};
+const LifecycleReadPolicy = {
+	auth: "admin",
+	policies: [{
+		key: "platform.app-config.read",
+		version: 1
+	}]
+};
+const ConfigVersionRecord = new SchemaModel({
+	name: "ConfigVersionRecord",
+	fields: {
+		meta: {
+			type: ScalarTypeEnum.JSONObject(),
+			isOptional: false
+		},
+		config: {
+			type: ScalarTypeEnum.JSONObject(),
+			isOptional: false
+		}
+	}
+});
+const ConfigTransitionRecord = new SchemaModel({
+	name: "ConfigTransitionRecord",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		appId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		fromStatus: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		toStatus: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		timestamp: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		},
+		actor: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		reason: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const CreateDraftInput = new SchemaModel({
+	name: "CreateTenantConfigDraftInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		appId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		blueprintName: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		blueprintVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		environment: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		fromVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		createdBy: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		}
+	}
+});
+const CreateDraftOutput = new SchemaModel({
+	name: "CreateTenantConfigDraftOutput",
+	fields: {
+		version: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		createdAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		}
+	}
+});
+const CreateTenantConfigDraftCommand = defineCommand({
+	meta: {
+		key: "appConfig.lifecycle.createDraft",
+		version: 1,
+		description: "Creates a new draft tenant config version.",
+		owners: [OwnersEnum.PlatformSigil],
+		tags: [TagsEnum.Hygiene, "app-config"],
+		stability: StabilityEnum.Experimental,
+		goal: "Allow operators to start editing a new tenant config version.",
+		context: "Invoked by the Studio or automation when starting a new configuration run."
+	},
+	io: {
+		input: CreateDraftInput,
+		output: CreateDraftOutput
+	},
+	policy: LifecyclePolicy,
+	sideEffects: { emits: [{
+		ref: ConfigDraftCreatedEvent.meta,
+		when: "after successful draft creation"
+	}] }
+});
+const PromotePreviewInput = new SchemaModel({
+	name: "PromoteTenantConfigPreviewInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		appId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		promotedBy: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		}
+	}
+});
+const PromotePreviewOutput = new SchemaModel({
+	name: "PromoteTenantConfigPreviewOutput",
+	fields: {
+		version: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		warnings: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+			isArray: true
+		}
+	}
+});
+const PromoteTenantConfigToPreviewCommand = defineCommand({
+	meta: {
+		key: "appConfig.lifecycle.promoteToPreview",
+		version: 1,
+		description: "Promotes a draft tenant config to preview/testing state.",
+		owners: [OwnersEnum.PlatformSigil],
+		tags: [TagsEnum.Hygiene, "app-config"],
+		stability: StabilityEnum.Experimental,
+		goal: "Enable validation and testing of draft configurations.",
+		context: "Called when a draft passes initial checks and should be exposed to preview environments."
+	},
+	io: {
+		input: PromotePreviewInput,
+		output: PromotePreviewOutput
+	},
+	policy: LifecyclePolicy,
+	sideEffects: { emits: [{
+		ref: ConfigPromotedToPreviewEvent.meta,
+		when: "after promotion to preview"
+	}] }
+});
+const PublishConfigInput = new SchemaModel({
+	name: "PublishTenantConfigInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		appId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		environment: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		publishedBy: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		changeSummary: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const PublishConfigOutput = new SchemaModel({
+	name: "PublishTenantConfigOutput",
+	fields: {
+		version: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		previousVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		publishedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		}
+	}
+});
+const PublishTenantConfigCommand = defineCommand({
+	meta: {
+		key: "appConfig.lifecycle.publish",
+		version: 1,
+		description: "Publishes a preview tenant config to production.",
+		owners: [OwnersEnum.PlatformSigil],
+		tags: [TagsEnum.Hygiene, "app-config"],
+		stability: StabilityEnum.Experimental,
+		goal: "Promote tested configurations to production safely.",
+		context: "Triggered after validation passes and change management approvals are complete."
+	},
+	io: {
+		input: PublishConfigInput,
+		output: PublishConfigOutput
+	},
+	policy: LifecyclePolicy,
+	sideEffects: { emits: [{
+		ref: ConfigPublishedEvent.meta,
+		when: "after publish succeeds"
+	}] }
+});
+const RollbackConfigInput = new SchemaModel({
+	name: "RollbackTenantConfigInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		appId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		toVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		environment: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		rolledBackBy: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		reason: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		}
+	}
+});
+const RollbackConfigOutput = new SchemaModel({
+	name: "RollbackTenantConfigOutput",
+	fields: {
+		newVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		rolledBackFrom: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		}
+	}
+});
+const RollbackTenantConfigCommand = defineCommand({
+	meta: {
+		key: "appConfig.lifecycle.rollback",
+		version: 1,
+		description: "Rolls back to a previously published tenant config version.",
+		owners: [OwnersEnum.PlatformSigil],
+		tags: [TagsEnum.Hygiene, "app-config"],
+		stability: StabilityEnum.Experimental,
+		goal: "Provide rapid recovery when new configs regress production.",
+		context: "Called manually or automatically when monitoring detects regression and a rollback is required."
+	},
+	io: {
+		input: RollbackConfigInput,
+		output: RollbackConfigOutput
+	},
+	policy: LifecyclePolicy,
+	sideEffects: { emits: [{
+		ref: ConfigRolledBackEvent.meta,
+		when: "after rollback completes"
+	}] }
+});
+const ListVersionsInput = new SchemaModel({
+	name: "ListTenantConfigVersionsInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		appId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		}
+	}
+});
+const ListVersionsOutput = new SchemaModel({
+	name: "ListTenantConfigVersionsOutput",
+	fields: {
+		versions: {
+			type: ConfigVersionRecord,
+			isOptional: false,
+			isArray: true
+		},
+		transitions: {
+			type: ConfigTransitionRecord,
+			isOptional: true,
+			isArray: true
+		}
+	}
+});
+const ListTenantConfigVersionsQuery = defineQuery({
+	meta: {
+		key: "appConfig.lifecycle.listVersions",
+		version: 1,
+		description: "Lists all versions of a tenant configuration.",
+		owners: [OwnersEnum.PlatformSigil],
+		tags: ["app-config", TagsEnum.Hygiene],
+		stability: StabilityEnum.Experimental,
+		goal: "Support lifecycle views and change audit tooling.",
+		context: "Used by the Studio to render history timelines and by automation for change tracking."
+	},
+	io: {
+		input: ListVersionsInput,
+		output: ListVersionsOutput
+	},
+	policy: LifecycleReadPolicy
+});
+const GetVersionInput = new SchemaModel({
+	name: "GetTenantConfigVersionInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		appId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		}
+	}
+});
+const GetVersionOutput = new SchemaModel({
+	name: "GetTenantConfigVersionOutput",
+	fields: { version: {
+		type: ConfigVersionRecord,
+		isOptional: false
+	} }
+});
+const GetTenantConfigVersionQuery = defineQuery({
+	meta: {
+		key: "appConfig.lifecycle.getVersion",
+		version: 1,
+		description: "Fetches a single tenant config version by id.",
+		owners: [OwnersEnum.PlatformSigil],
+		tags: ["app-config", TagsEnum.Hygiene],
+		stability: StabilityEnum.Experimental,
+		goal: "Allow detail drill-down for lifecycle entries.",
+		context: "Used by automation to fetch config payloads for comparison or export."
+	},
+	io: {
+		input: GetVersionInput,
+		output: GetVersionOutput
+	},
+	policy: LifecycleReadPolicy
+});
+const lifecycleContracts = {
+	CreateTenantConfigDraftCommand,
+	PromoteTenantConfigToPreviewCommand,
+	PublishTenantConfigCommand,
+	RollbackTenantConfigCommand,
+	ListTenantConfigVersionsQuery,
+	GetTenantConfigVersionQuery
+};
+function registerAppConfigLifecycleContracts(registry) {
+	return registry.register(CreateTenantConfigDraftCommand).register(PromoteTenantConfigToPreviewCommand).register(PublishTenantConfigCommand).register(RollbackTenantConfigCommand).register(ListTenantConfigVersionsQuery).register(GetTenantConfigVersionQuery);
+}
+
+//#endregion
+export { CreateTenantConfigDraftCommand, GetTenantConfigVersionQuery, ListTenantConfigVersionsQuery, PromoteTenantConfigToPreviewCommand, PublishTenantConfigCommand, RollbackTenantConfigCommand, lifecycleContracts, registerAppConfigLifecycleContracts };

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

@@ -0,0 +1,27 @@
+import { TenantAppConfig } from "./spec.js";
+
+//#region src/app-config/lifecycle.d.ts
+type ConfigStatus = 'draft' | 'preview' | 'published' | 'archived' | 'superseded';
+interface TenantAppConfigVersion {
+  meta: TenantAppConfig['meta'];
+  config: TenantAppConfig;
+}
+interface ConfigTransition {
+  tenantId: string;
+  appId: string;
+  fromStatus: ConfigStatus;
+  toStatus: ConfigStatus;
+  version: number;
+  timestamp: string | Date;
+  actor: string;
+  reason?: string;
+}
+interface ConfigVersionHistory {
+  tenantId: string;
+  appId: string;
+  versions: TenantAppConfigVersion[];
+  transitions: ConfigTransition[];
+  currentPublished?: number;
+}
+//#endregion
+export { ConfigStatus, ConfigTransition, ConfigVersionHistory, TenantAppConfigVersion };

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

@@ -0,0 +1,120 @@
+import { CapabilityRef, CapabilityRegistry, CapabilitySpec } from "../capabilities/capabilities.js";
+import "../capabilities/index.js";
+import { PolicyRef, PolicySpec } from "../policy/spec.js";
+import { TelemetryRegistry, TelemetrySpec } from "../telemetry/spec.js";
+import { ExperimentRef, ExperimentRegistry, ExperimentSpec } from "../experiments/spec.js";
+import { DataViewSpec } from "../data-views/spec.js";
+import { DataViewRegistry } from "../data-views/registry.js";
+import "../data-views/index.js";
+import { WorkflowRegistry, WorkflowSpec } from "../workflow/spec.js";
+import { PolicyRegistry } from "../policy/registry.js";
+import { ThemeRegistry, ThemeSpec } from "../themes.js";
+import { IntegrationSpec, IntegrationSpecRegistry } from "../integrations/spec.js";
+import { IntegrationConnection } from "../integrations/connection.js";
+import { AppIntegrationBinding } from "../integrations/binding.js";
+import { KnowledgeSpaceRegistry, KnowledgeSpaceSpec } from "../knowledge/spec.js";
+import { KnowledgeSourceConfig } from "../knowledge/source.js";
+import { AppKnowledgeBinding } from "../knowledge/binding.js";
+import { ResolvedBranding } from "./branding.js";
+import { Locale, TranslationEntry } from "../translations/catalog.js";
+import { AppBlueprintSpec, AppIntegrationSlot, AppRouteConfig, AppThemeBinding, FeatureFlagState, SpecPointer, TelemetryBinding, TenantAppConfig, TranslationCatalogPointer } from "./spec.js";
+import { FeatureModuleSpec, FeatureRef } from "../features/types.js";
+import { FeatureRegistry } from "../features/registry.js";
+import "../features/index.js";
+
+//#region src/app-config/runtime.d.ts
+interface ResolvedIntegration {
+  slot: AppIntegrationSlot;
+  binding: AppIntegrationBinding;
+  connection: IntegrationConnection;
+  spec: IntegrationSpec;
+}
+interface ResolvedKnowledge {
+  binding: AppKnowledgeBinding;
+  space: KnowledgeSpaceSpec;
+  sources: KnowledgeSourceConfig[];
+}
+interface ResolvedTranslation {
+  defaultLocale: Locale;
+  supportedLocales: Locale[];
+  blueprintCatalog?: TranslationCatalogPointer;
+  tenantOverrides: TranslationEntry[];
+}
+interface ResolvedAppConfig {
+  appId: string;
+  tenantId: string;
+  environment?: string;
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+  capabilities: {
+    enabled: CapabilityRef[];
+    disabled: CapabilityRef[];
+  };
+  features: {
+    include: FeatureRef[];
+    exclude: FeatureRef[];
+  };
+  dataViews: Record<string, SpecPointer>;
+  workflows: Record<string, SpecPointer>;
+  policies: PolicyRef[];
+  theme?: AppThemeBinding;
+  telemetry?: TelemetryBinding;
+  experiments: {
+    catalog: ExperimentRef[];
+    active: ExperimentRef[];
+    paused: ExperimentRef[];
+  };
+  featureFlags: FeatureFlagState[];
+  routes: AppRouteConfig[];
+  integrations: ResolvedIntegration[];
+  knowledge: ResolvedKnowledge[];
+  translation: ResolvedTranslation;
+  branding: ResolvedBranding;
+  notes?: string;
+}
+interface AppComposition {
+  resolved: ResolvedAppConfig;
+  capabilities: CapabilitySpec[];
+  features: FeatureModuleSpec[];
+  dataViews: Record<string, DataViewSpec>;
+  workflows: Record<string, WorkflowSpec>;
+  policies: PolicySpec[];
+  theme?: ThemeSpec;
+  themeFallbacks: ThemeSpec[];
+  telemetry?: TelemetrySpec;
+  experiments: {
+    active: ExperimentSpec[];
+    paused: ExperimentSpec[];
+  };
+  integrations: ResolvedIntegration[];
+  knowledge: ResolvedKnowledge[];
+  missing: MissingReference[];
+}
+interface MissingReference {
+  type: 'capability' | 'feature' | 'dataView' | 'workflow' | 'policy' | 'theme' | 'telemetry' | 'experiment' | 'integrationConnection' | 'integrationSpec' | 'integrationSlot' | 'knowledgeSpace' | 'knowledgeSource';
+  identifier: string;
+}
+interface ResolveAppConfigDeps {
+  integrationSpecs?: IntegrationSpecRegistry;
+  integrationConnections?: IntegrationConnection[];
+  knowledgeSpaces?: KnowledgeSpaceRegistry;
+  knowledgeSources?: KnowledgeSourceConfig[];
+}
+interface AppCompositionDeps extends ResolveAppConfigDeps {
+  capabilities?: CapabilityRegistry;
+  features?: FeatureRegistry;
+  dataViews?: DataViewRegistry;
+  workflows?: WorkflowRegistry;
+  policies?: PolicyRegistry;
+  themes?: ThemeRegistry;
+  telemetry?: TelemetryRegistry;
+  experiments?: ExperimentRegistry;
+}
+interface ComposeOptions {
+  strict?: boolean;
+}
+declare function resolveAppConfig(blueprint: AppBlueprintSpec, tenant: TenantAppConfig, deps?: ResolveAppConfigDeps): ResolvedAppConfig;
+declare function composeAppConfig(blueprint: AppBlueprintSpec, tenant: TenantAppConfig, deps: AppCompositionDeps, options?: ComposeOptions): AppComposition;
+//#endregion
+export { AppComposition, AppCompositionDeps, ComposeOptions, MissingReference, ResolveAppConfigDeps, ResolvedAppConfig, ResolvedIntegration, ResolvedKnowledge, ResolvedTranslation, composeAppConfig, resolveAppConfig };