@contractspec/lib.contracts 1.49.0 → 1.51.0

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

@@ -1,52 +1,52 @@
 import { OperationSpec } from "../operations/operation.js";
-import { OperationSpecRegistry } from "../operations/registry.js";
 import "../operations/index.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 import { EventSpecMeta } from "../events.js";
 import "../index.js";
-import * as _contractspec_lib_schema392 from "@contractspec/lib.schema";
+import * as _contractspec_lib_schema74 from "@contractspec/lib.schema";
 import { SchemaModel } from "@contractspec/lib.schema";
 
 //#region src/app-config/lifecycle-contracts.d.ts
 declare const CreateTenantConfigDraftCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   blueprintName: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   blueprintVersion: {
-    type: _contractspec_lib_schema392.FieldType<number, number>;
+    type: _contractspec_lib_schema74.FieldType<number, number>;
     isOptional: false;
   };
   environment: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: true;
   };
   fromVersion: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: true;
   };
   createdBy: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   status: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   createdAt: {
-    type: _contractspec_lib_schema392.FieldType<Date, string>;
+    type: _contractspec_lib_schema74.FieldType<Date, string>;
     isOptional: false;
   };
 }>, {
@@ -55,32 +55,32 @@ declare const CreateTenantConfigDraftCommand: OperationSpec<SchemaModel<{
 }[]>;
 declare const PromoteTenantConfigToPreviewCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   promotedBy: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   status: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   warnings: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: true;
     isArray: true;
   };
@@ -90,44 +90,44 @@ declare const PromoteTenantConfigToPreviewCommand: OperationSpec<SchemaModel<{
 }[]>;
 declare const PublishTenantConfigCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   environment: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: true;
   };
   publishedBy: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   changeSummary: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: true;
   };
 }>, SchemaModel<{
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   status: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   previousVersion: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: true;
   };
   publishedAt: {
-    type: _contractspec_lib_schema392.FieldType<Date, string>;
+    type: _contractspec_lib_schema74.FieldType<Date, string>;
     isOptional: false;
   };
 }>, {
@@ -136,40 +136,40 @@ declare const PublishTenantConfigCommand: OperationSpec<SchemaModel<{
 }[]>;
 declare const RollbackTenantConfigCommand: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   toVersion: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   environment: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: true;
   };
   rolledBackBy: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   reason: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   newVersion: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   status: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   rolledBackFrom: {
-    type: _contractspec_lib_schema392.FieldType<number, number>;
+    type: _contractspec_lib_schema74.FieldType<number, number>;
     isOptional: false;
   };
 }>, {
@@ -178,22 +178,22 @@ declare const RollbackTenantConfigCommand: OperationSpec<SchemaModel<{
 }[]>;
 declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   versions: {
     type: SchemaModel<{
       meta: {
-        type: _contractspec_lib_schema392.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _contractspec_lib_schema74.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
       config: {
-        type: _contractspec_lib_schema392.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _contractspec_lib_schema74.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
     }>;
@@ -203,35 +203,35 @@ declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
   transitions: {
     type: SchemaModel<{
       tenantId: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema74.FieldType<string, string>;
         isOptional: false;
       };
       appId: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema74.FieldType<string, string>;
         isOptional: false;
       };
       fromStatus: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema74.FieldType<string, string>;
         isOptional: false;
       };
       toStatus: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema74.FieldType<string, string>;
         isOptional: false;
       };
       version: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema74.FieldType<string, string>;
         isOptional: false;
       };
       timestamp: {
-        type: _contractspec_lib_schema392.FieldType<Date, string>;
+        type: _contractspec_lib_schema74.FieldType<Date, string>;
         isOptional: false;
       };
       actor: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema74.FieldType<string, string>;
         isOptional: false;
       };
       reason: {
-        type: _contractspec_lib_schema392.FieldType<string, string>;
+        type: _contractspec_lib_schema74.FieldType<string, string>;
         isOptional: true;
       };
     }>;
@@ -241,26 +241,26 @@ declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
 }>, undefined>;
 declare const GetTenantConfigVersionQuery: OperationSpec<SchemaModel<{
   tenantId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   appId: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
   version: {
-    type: _contractspec_lib_schema392.FieldType<string, string>;
+    type: _contractspec_lib_schema74.FieldType<string, string>;
     isOptional: false;
   };
 }>, SchemaModel<{
   version: {
     type: SchemaModel<{
       meta: {
-        type: _contractspec_lib_schema392.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _contractspec_lib_schema74.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
       config: {
-        type: _contractspec_lib_schema392.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        type: _contractspec_lib_schema74.FieldType<Record<string, unknown>, Record<string, unknown>>;
         isOptional: false;
       };
     }>;

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

@@ -1,6 +1,6 @@
+import { CapabilityRef, CapabilityRegistry, CapabilitySpec } from "../capabilities/capabilities.js";
 import { PolicyRef, PolicySpec } from "../policy/spec.js";
 import { TelemetryRegistry, TelemetrySpec } from "../telemetry/spec.js";
-import { CapabilityRef, CapabilityRegistry, CapabilitySpec } from "../capabilities/capabilities.js";
 import "../capabilities/index.js";
 import { ExperimentRef, ExperimentRegistry, ExperimentSpec } from "../experiments/spec.js";
 import { FeatureModuleSpec, FeatureRef } from "../features/types.js";

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

@@ -1,6 +1,6 @@
+import { CapabilityRef } from "../capabilities/capabilities.js";
 import { OwnerShipMeta } from "../ownership.js";
 import { PolicyRef } from "../policy/spec.js";
-import { CapabilityRef } from "../capabilities/capabilities.js";
 import "../capabilities/index.js";
 import { ExperimentRef } from "../experiments/spec.js";
 import { FeatureModuleSpec, FeatureRef } from "../features/types.js";

package/dist/capabilities/capabilities.d.ts

@@ -1,39 +1,98 @@
+import { VersionedSpecRef } from "../versioning/refs.js";
 import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/capabilities/capabilities.d.ts
+/** Classification of capability types. */
 type CapabilityKind = 'api' | 'event' | 'data' | 'ui' | 'integration';
+/** Surfaces where capabilities can be exposed or consumed. */
 type CapabilitySurface = 'operation' | 'event' | 'workflow' | 'presentation' | 'resource';
+/**
+ * Reference to a capability on a specific surface.
+ * Extends VersionedSpecRef with surface and description context.
+ */
 interface CapabilitySurfaceRef {
+  /** The surface type where this capability is exposed. */
   surface: CapabilitySurface;
+  /** Unique key identifying the spec on that surface (e.g., operation key). */
   key: string;
-  version: string;
+  /** Semantic version of the spec on that surface. */
+  version?: string;
+  /** Optional description of what this capability provides. */
   description?: string;
 }
+/** Metadata for a capability spec, extending ownership with kind. */
 interface CapabilityMeta extends OwnerShipMeta {
+  /** The kind/category of this capability. */
   kind: CapabilityKind;
 }
+/**
+ * Requirement for a capability dependency.
+ * Used to declare what capabilities a spec needs.
+ */
 interface CapabilityRequirement {
+  /** Unique key of the required capability. */
   key: string;
+  /** Optional specific version required. */
   version?: string;
+  /** Optional kind filter for the requirement. */
   kind?: CapabilityKind;
+  /** If true, the requirement is optional and won't block if missing. */
   optional?: boolean;
+  /** Human-readable reason why this capability is required. */
   reason?: string;
 }
-interface CapabilityRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a capability spec.
+ * Uses key and version to identify a specific capability.
+ */
+type CapabilityRef = VersionedSpecRef;
 interface CapabilitySpec {
   meta: CapabilityMeta;
+  /** Capabilities this capability extends (inherits requirements from). */
+  extends?: CapabilityRef;
+  /** Surfaces (operations, events, presentations, etc.) this capability provides. */
   provides?: CapabilitySurfaceRef[];
+  /** Capabilities that must be present for this capability to function. */
   requires?: CapabilityRequirement[];
 }
 declare class CapabilityRegistry {
   private readonly items;
+  /** Reverse index: surface key -> capability key (built lazily) */
+  private surfaceIndex;
   register(spec: CapabilitySpec): this;
   list(): CapabilitySpec[];
   get(key: string, version?: string): CapabilitySpec | undefined;
   satisfies(requirement: CapabilityRequirement, additional?: CapabilityRef[] | undefined): boolean;
+  /** Build reverse index from surface specs to capabilities. */
+  private buildSurfaceIndex;
+  /** Get all operation keys provided by a capability. */
+  getOperationsFor(capabilityKey: string, version?: string): string[];
+  /** Get all event keys provided by a capability. */
+  getEventsFor(capabilityKey: string, version?: string): string[];
+  /** Get all presentation keys provided by a capability. */
+  getPresentationsFor(capabilityKey: string, version?: string): string[];
+  /** Get all workflow keys provided by a capability. */
+  getWorkflowsFor(capabilityKey: string, version?: string): string[];
+  /** Get all resource keys provided by a capability. */
+  getResourcesFor(capabilityKey: string, version?: string): string[];
+  /** Get capability refs that provide a specific operation. */
+  getCapabilitiesForOperation(operationKey: string): CapabilityRef[];
+  /** Get capability refs that provide a specific event. */
+  getCapabilitiesForEvent(eventKey: string): CapabilityRef[];
+  /** Get capability refs that provide a specific presentation. */
+  getCapabilitiesForPresentation(presentationKey: string): CapabilityRef[];
+  /** Get the ancestor chain for a capability (from immediate parent to root). */
+  getAncestors(capabilityKey: string, version?: string): CapabilitySpec[];
+  /**
+   * Get effective requirements for a capability, including inherited ones.
+   * Requirements from ancestors are included, with child requirements taking
+   * precedence over parent requirements for the same key.
+   */
+  getEffectiveRequirements(capabilityKey: string, version?: string): CapabilityRequirement[];
+  /**
+   * Get all surfaces provided by a capability, including inherited ones.
+   */
+  getEffectiveSurfaces(capabilityKey: string, version?: string): CapabilitySurfaceRef[];
 }
 declare function capabilityKey(spec: CapabilitySpec): string;
 declare function defineCapability(spec: CapabilitySpec): CapabilitySpec;

package/dist/capabilities/capabilities.js

@@ -4,10 +4,13 @@ import { compareVersions } from "compare-versions";
 const capKey = (key, version) => `${key}.v${version}`;
 var CapabilityRegistry = class {
 	items = /* @__PURE__ */ new Map();
+	/** Reverse index: surface key -> capability key (built lazily) */
+	surfaceIndex = null;
 	register(spec) {
 		const key = capKey(spec.meta.key, spec.meta.version);
 		if (this.items.has(key)) throw new Error(`Duplicate capability ${key}`);
 		this.items.set(key, spec);
+		this.surfaceIndex = null;
 		return this;
 	}
 	list() {
@@ -31,6 +34,128 @@ var CapabilityRegistry = class {
 		if (requirement.version != null && spec.meta.version !== requirement.version) return false;
 		return true;
 	}
+	/** Build reverse index from surface specs to capabilities. */
+	buildSurfaceIndex() {
+		if (this.surfaceIndex) return this.surfaceIndex;
+		this.surfaceIndex = /* @__PURE__ */ new Map();
+		for (const spec of this.items.values()) {
+			const capabilityKey$1 = capKey(spec.meta.key, spec.meta.version);
+			for (const surface of spec.provides ?? []) {
+				const surfaceKey = `${surface.surface}:${surface.key}`;
+				if (!this.surfaceIndex.has(surfaceKey)) this.surfaceIndex.set(surfaceKey, /* @__PURE__ */ new Set());
+				this.surfaceIndex.get(surfaceKey)?.add(capabilityKey$1);
+			}
+		}
+		return this.surfaceIndex;
+	}
+	/** Get all operation keys provided by a capability. */
+	getOperationsFor(capabilityKey$1, version) {
+		const spec = this.get(capabilityKey$1, version);
+		if (!spec) return [];
+		return spec.provides?.filter((s) => s.surface === "operation").map((s) => s.key) ?? [];
+	}
+	/** Get all event keys provided by a capability. */
+	getEventsFor(capabilityKey$1, version) {
+		const spec = this.get(capabilityKey$1, version);
+		if (!spec) return [];
+		return spec.provides?.filter((s) => s.surface === "event").map((s) => s.key) ?? [];
+	}
+	/** Get all presentation keys provided by a capability. */
+	getPresentationsFor(capabilityKey$1, version) {
+		const spec = this.get(capabilityKey$1, version);
+		if (!spec) return [];
+		return spec.provides?.filter((s) => s.surface === "presentation").map((s) => s.key) ?? [];
+	}
+	/** Get all workflow keys provided by a capability. */
+	getWorkflowsFor(capabilityKey$1, version) {
+		const spec = this.get(capabilityKey$1, version);
+		if (!spec) return [];
+		return spec.provides?.filter((s) => s.surface === "workflow").map((s) => s.key) ?? [];
+	}
+	/** Get all resource keys provided by a capability. */
+	getResourcesFor(capabilityKey$1, version) {
+		const spec = this.get(capabilityKey$1, version);
+		if (!spec) return [];
+		return spec.provides?.filter((s) => s.surface === "resource").map((s) => s.key) ?? [];
+	}
+	/** Get capability refs that provide a specific operation. */
+	getCapabilitiesForOperation(operationKey) {
+		const capKeys = this.buildSurfaceIndex().get(`operation:${operationKey}`);
+		if (!capKeys) return [];
+		return [...capKeys].map((k) => {
+			const spec = this.items.get(k);
+			return {
+				key: spec?.meta.key ?? "",
+				version: spec?.meta.version ?? ""
+			};
+		});
+	}
+	/** Get capability refs that provide a specific event. */
+	getCapabilitiesForEvent(eventKey) {
+		const capKeys = this.buildSurfaceIndex().get(`event:${eventKey}`);
+		if (!capKeys) return [];
+		return [...capKeys].map((k) => {
+			const spec = this.items.get(k);
+			return {
+				key: spec?.meta.key ?? "",
+				version: spec?.meta.version ?? ""
+			};
+		});
+	}
+	/** Get capability refs that provide a specific presentation. */
+	getCapabilitiesForPresentation(presentationKey) {
+		const capKeys = this.buildSurfaceIndex().get(`presentation:${presentationKey}`);
+		if (!capKeys) return [];
+		return [...capKeys].map((k) => {
+			const spec = this.items.get(k);
+			return {
+				key: spec?.meta.key ?? "",
+				version: spec?.meta.version ?? ""
+			};
+		});
+	}
+	/** Get the ancestor chain for a capability (from immediate parent to root). */
+	getAncestors(capabilityKey$1, version) {
+		const ancestors = [];
+		const visited = /* @__PURE__ */ new Set();
+		let current = this.get(capabilityKey$1, version);
+		while (current?.extends) {
+			const parentKey = capKey(current.extends.key, current.extends.version);
+			if (visited.has(parentKey)) break;
+			visited.add(parentKey);
+			const parent = this.get(current.extends.key, current.extends.version);
+			if (!parent) break;
+			ancestors.push(parent);
+			current = parent;
+		}
+		return ancestors;
+	}
+	/**
+	* Get effective requirements for a capability, including inherited ones.
+	* Requirements from ancestors are included, with child requirements taking
+	* precedence over parent requirements for the same key.
+	*/
+	getEffectiveRequirements(capabilityKey$1, version) {
+		const spec = this.get(capabilityKey$1, version);
+		if (!spec) return [];
+		const ancestors = this.getAncestors(capabilityKey$1, version);
+		const requirementMap = /* @__PURE__ */ new Map();
+		for (const ancestor of [...ancestors].reverse()) for (const req of ancestor.requires ?? []) requirementMap.set(req.key, req);
+		for (const req of spec.requires ?? []) requirementMap.set(req.key, req);
+		return [...requirementMap.values()];
+	}
+	/**
+	* Get all surfaces provided by a capability, including inherited ones.
+	*/
+	getEffectiveSurfaces(capabilityKey$1, version) {
+		const spec = this.get(capabilityKey$1, version);
+		if (!spec) return [];
+		const ancestors = this.getAncestors(capabilityKey$1, version);
+		const surfaces = [];
+		for (const ancestor of [...ancestors].reverse()) surfaces.push(...ancestor.provides ?? []);
+		surfaces.push(...spec.provides ?? []);
+		return surfaces;
+	}
 };
 function matchesRequirement(ref, requirement) {
 	if (ref.key !== requirement.key) return false;

package/dist/capabilities/context.d.ts

@@ -0,0 +1,88 @@
+import { CapabilityRef } from "./capabilities.js";
+
+//#region src/capabilities/context.d.ts
+
+/**
+ * Error thrown when a required capability is missing.
+ */
+declare class CapabilityMissingError extends Error {
+  readonly capabilityKey: string;
+  readonly requiredVersion?: string;
+  constructor(capabilityKey: string, requiredVersion?: string);
+}
+/**
+ * Runtime context for checking capability access.
+ *
+ * Created from a list of enabled capabilities (e.g., from user subscription,
+ * tenant config, or feature flags). Provides methods to check and require
+ * capabilities at runtime.
+ */
+interface CapabilityContext {
+  /** Set of enabled capability keys (without version). */
+  readonly capabilities: ReadonlySet<string>;
+  /** Map of capability key to version for version-specific checks. */
+  readonly capabilityVersions: ReadonlyMap<string, string>;
+  /**
+   * Check if a capability is enabled.
+   * @param key - Capability key to check
+   * @param version - Optional specific version to require
+   * @returns True if capability is enabled
+   */
+  hasCapability(key: string, version?: string): boolean;
+  /**
+   * Require a capability, throwing if not enabled.
+   * @param key - Capability key to require
+   * @param version - Optional specific version to require
+   * @throws {CapabilityMissingError} If capability is not enabled
+   */
+  requireCapability(key: string, version?: string): void;
+  /**
+   * Check if all specified capabilities are enabled.
+   * @param keys - Array of capability keys to check
+   * @returns True if all capabilities are enabled
+   */
+  hasAllCapabilities(keys: string[]): boolean;
+  /**
+   * Check if any of the specified capabilities are enabled.
+   * @param keys - Array of capability keys to check
+   * @returns True if at least one capability is enabled
+   */
+  hasAnyCapability(keys: string[]): boolean;
+  /**
+   * Get enabled capabilities matching a pattern.
+   * @param pattern - Glob-like pattern (supports * wildcard)
+   * @returns Array of matching capability keys
+   */
+  getMatchingCapabilities(pattern: string): string[];
+}
+/**
+ * Creates a capability context from enabled capabilities.
+ *
+ * @param enabledCapabilities - Array of capability refs that are enabled
+ * @returns CapabilityContext for checking/requiring capabilities
+ *
+ * @example
+ * ```typescript
+ * // From user subscription capabilities
+ * const userCaps = await getUserCapabilities(userId);
+ * const ctx = createCapabilityContext(userCaps);
+ *
+ * // In handler
+ * ctx.requireCapability('premium-features');
+ * ```
+ */
+declare function createCapabilityContext(enabledCapabilities: CapabilityRef[]): CapabilityContext;
+/**
+ * Creates an empty capability context (no capabilities enabled).
+ * Useful for anonymous users or testing.
+ */
+declare function createEmptyCapabilityContext(): CapabilityContext;
+/**
+ * Creates a capability context with all capabilities enabled (bypass).
+ * Useful for admin users or internal services.
+ *
+ * @param allCapabilities - Array of all capability refs to enable
+ */
+declare function createBypassCapabilityContext(allCapabilities: CapabilityRef[]): CapabilityContext;
+//#endregion
+export { CapabilityContext, CapabilityMissingError, createBypassCapabilityContext, createCapabilityContext, createEmptyCapabilityContext };