@contractspec/lib.contracts 1.50.0 → 1.51.0

package/dist/capabilities/context.js

@@ -0,0 +1,87 @@
+//#region src/capabilities/context.ts
+/**
+* Error thrown when a required capability is missing.
+*/
+var CapabilityMissingError = class extends Error {
+	capabilityKey;
+	requiredVersion;
+	constructor(capabilityKey, requiredVersion) {
+		const versionSuffix = requiredVersion ? `.v${requiredVersion}` : "";
+		super(`Missing required capability: ${capabilityKey}${versionSuffix}`);
+		this.name = "CapabilityMissingError";
+		this.capabilityKey = capabilityKey;
+		this.requiredVersion = requiredVersion;
+	}
+};
+var CapabilityContextImpl = class {
+	capabilities;
+	capabilityVersions;
+	constructor(enabledCapabilities) {
+		const capSet = /* @__PURE__ */ new Set();
+		const versionMap = /* @__PURE__ */ new Map();
+		for (const cap of enabledCapabilities) {
+			capSet.add(cap.key);
+			versionMap.set(cap.key, cap.version);
+		}
+		this.capabilities = capSet;
+		this.capabilityVersions = versionMap;
+	}
+	hasCapability(key, version) {
+		if (!this.capabilities.has(key)) return false;
+		if (version != null) return this.capabilityVersions.get(key) === version;
+		return true;
+	}
+	requireCapability(key, version) {
+		if (!this.hasCapability(key, version)) throw new CapabilityMissingError(key, version);
+	}
+	hasAllCapabilities(keys) {
+		return keys.every((k) => this.capabilities.has(k));
+	}
+	hasAnyCapability(keys) {
+		return keys.some((k) => this.capabilities.has(k));
+	}
+	getMatchingCapabilities(pattern) {
+		if (!pattern.includes("*")) return this.capabilities.has(pattern) ? [pattern] : [];
+		const regexPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+		const regex = /* @__PURE__ */ new RegExp(`^${regexPattern}$`);
+		return [...this.capabilities].filter((key) => regex.test(key));
+	}
+};
+/**
+* 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');
+* ```
+*/
+function createCapabilityContext(enabledCapabilities) {
+	return new CapabilityContextImpl(enabledCapabilities);
+}
+/**
+* Creates an empty capability context (no capabilities enabled).
+* Useful for anonymous users or testing.
+*/
+function createEmptyCapabilityContext() {
+	return new CapabilityContextImpl([]);
+}
+/**
+* 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
+*/
+function createBypassCapabilityContext(allCapabilities) {
+	return new CapabilityContextImpl(allCapabilities);
+}
+
+//#endregion
+export { CapabilityMissingError, createBypassCapabilityContext, createCapabilityContext, createEmptyCapabilityContext };

package/dist/capabilities/docs/capabilities.docblock.js

@@ -4,7 +4,7 @@ import { registerDocBlocks } from "../../docs/registry.js";
 const tech_contracts_capabilities_DocBlocks = [{
 	id: "docs.tech.contracts.capabilities",
 	title: "CapabilitySpec Overview",
-	summary: "Capability specs provide a canonical, versioned contract for what a module offers (`provides`) and what it depends on (`requires`). They enable safe composition across features, automated validation during `installFeature`, and consistent documentation for shared surfaces (APIs, events, workflows, UI, resources).",
+	summary: "Capability specs define what a module provides (operations, events, presentations) and requires (dependencies). They enable bidirectional linking, inheritance, runtime enforcement, and automated validation.",
 	kind: "reference",
 	visibility: "public",
 	route: "/docs/tech/contracts/capabilities",
@@ -13,7 +13,196 @@ const tech_contracts_capabilities_DocBlocks = [{
 		"contracts",
 		"capabilities"
 	],
-	body: "# CapabilitySpec Overview\n\n## Purpose\n\nCapability specs provide a canonical, versioned contract for what a module offers (`provides`) and what it depends on (`requires`). They enable safe composition across features, automated validation during `installFeature`, and consistent documentation for shared surfaces (APIs, events, workflows, UI, resources).\n\n## Schema\n\nDefined in `@contractspec/lib.contracts/src/capabilities.ts`.\n\n```ts\nexport interface CapabilitySpec {\n  meta: CapabilityMeta;              // ownership metadata + { key, version, kind }\n  provides?: CapabilitySurfaceRef[]; // what concrete surfaces this capability exposes\n  requires?: CapabilityRequirement[];// capabilities that must already exist\n}\n```\n\n- **CapabilityMeta**\n  - `key`: stable slug (e.g., `payments.stripe`)\n  - `version`: bump on breaking changes\n  - `kind`: `'api' | 'event' | 'data' | 'ui' | 'integration'`\n  - ownership fields (`title`, `description`, `domain`, `owners`, `tags`, `stability`)\n- **CapabilitySurfaceRef**\n  - `surface`: `'operation' | 'event' | 'workflow' | 'presentation' | 'resource'`\n  - `name` / `version`: points to the declared contract (operation name, event name, etc.)\n  - optional `description`\n- **CapabilityRequirement**\n  - `key`: capability slug to satisfy\n  - `version?`: pin to an exact version when required (defaults to highest registered)\n  - `kind?`: extra guard if the same key hosts multiple kinds\n  - `optional?`: skip strict enforcement (informational requirement)\n  - `reason?`: why this dependency exists (docs + tooling)\n\n## Registry\n\n`CapabilityRegistry` provides:\n\n- `register(spec)`: register a capability (`key + version` must be unique)\n- `get(key, version?)`: retrieve the exact or highest version\n- `list()`: inspect all capabilities\n- `satisfies(requirement, additional?)`: check if a requirement is met (includes locally provided capabilities passed via `additional`)\n\n## Feature Integration\n\n`FeatureModuleSpec` now accepts:\n\n```ts\ncapabilities?: {\n  provides?: CapabilityRef[];    // capabilities this feature exposes\n  requires?: CapabilityRequirement[]; // capabilities the feature needs\n};\n```\n\nDuring `installFeature`:\n\n1. `provides` entries must exist in the `CapabilityRegistry`.\n2. `requires` entries must be satisfied either by:\n   - the same feature’s `provides`,\n   - or existing capabilities already registered in the global registry.\n\nErrors are thrown when dependencies cannot be satisfied, preventing unsafe module composition.\n\n## Authoring Guidelines\n\n1. **Register capability specs** in a shared package (e.g., `packages/.../capabilities`) before referencing them in features.\n2. **Version consciously**: bump capability versions when the provided surfaces or contract semantics change.\n3. **Document dependencies** via `reason` strings to help operators understand why a capability is required.\n4. **Prefer stable keys** that map to business/technical domains (`billing.invoices`, `payments.stripe`, `cms.assets`).\n5. When introducing new capability kinds, update the `CapabilityKind` union and accompanying docs/tests.\n\n## Tooling (Roadmap)\n\n- CLI validation warns when feature specs reference missing capabilities.\n- Future build steps will leverage capability data to scaffold adapters and enforce policy in generated code.\n- Capability metadata will surface in docs/LLM guides to describe module marketplaces and installation flows.\n\n"
+	body: `# CapabilitySpec Overview
+
+## Purpose
+
+Capabilities are **module interfaces** that define:
+1. What operations, events, and presentations a module exposes (\`provides\`)
+2. What other capabilities it depends on (\`requires\`)
+3. Inheritance hierarchies via \`extends\`
+
+They enable:
+- **Bidirectional linking**: Specs reference capabilities, capabilities list their specs
+- **Dependency validation**: Features can't install without satisfying requirements
+- **Runtime enforcement**: Check capabilities before executing operations
+- **Inheritance**: Build capability hierarchies with shared requirements
+
+## Schema
+
+\`\`\`ts
+export interface CapabilitySpec {
+  meta: CapabilityMeta;              // ownership metadata + { key, version, kind }
+  extends?: CapabilityRef;           // NEW: inherit from parent capability
+  provides?: CapabilitySurfaceRef[]; // surfaces this capability exposes
+  requires?: CapabilityRequirement[];// capabilities that must exist
+}
+\`\`\`
+
+### Bidirectional Linking
+
+Operations, events, and presentations can now declare their capability:
+
+\`\`\`ts
+// In OperationSpec
+{
+  meta: { key: 'payments.charge.create', ... },
+  capability: { key: 'payments', version: '1.0.0' }, // Links to capability
+  io: { ... }
+}
+
+// In CapabilitySpec
+{
+  meta: { key: 'payments', version: '1.0.0', ... },
+  provides: [
+    { surface: 'operation', key: 'payments.charge.create' }
+  ]
+}
+\`\`\`
+
+Validation ensures both sides match via \`validateCapabilityConsistency()\`.
+
+## Registry Query Methods
+
+The \`CapabilityRegistry\` now provides rich query capabilities:
+
+\`\`\`ts
+// Forward lookups: Capability → Specs
+registry.getOperationsFor('payments');      // ['payments.charge.create', ...]
+registry.getEventsFor('payments');          // ['payments.charge.succeeded', ...]
+registry.getPresentationsFor('payments');   // ['payments.dashboard', ...]
+
+// Reverse lookups: Spec → Capabilities
+registry.getCapabilitiesForOperation('payments.charge.create');
+registry.getCapabilitiesForEvent('payments.charge.succeeded');
+registry.getCapabilitiesForPresentation('payments.dashboard');
+
+// Inheritance
+registry.getAncestors('payments.stripe');           // Parent chain
+registry.getEffectiveRequirements('payments.stripe'); // Includes inherited
+registry.getEffectiveSurfaces('payments.stripe');     // Includes inherited
+\`\`\`
+
+## Inheritance
+
+Capabilities can extend other capabilities:
+
+\`\`\`ts
+// Base capability
+defineCapability({
+  meta: { key: 'payments.base', version: '1.0.0', ... },
+  requires: [{ key: 'auth', version: '1.0.0' }],
+  provides: [{ surface: 'operation', key: 'payments.list' }]
+});
+
+// Child capability inherits requirements
+defineCapability({
+  meta: { key: 'payments.stripe', version: '1.0.0', ... },
+  extends: { key: 'payments.base', version: '1.0.0' },
+  requires: [{ key: 'encryption', version: '1.0.0' }], // Added
+  provides: [{ surface: 'operation', key: 'payments.stripe.charge' }]
+});
+
+// getEffectiveRequirements('payments.stripe') returns:
+// [{ key: 'auth', ... }, { key: 'encryption', ... }]
+\`\`\`
+
+## Runtime Enforcement
+
+Use \`CapabilityContext\` for opt-in runtime checks:
+
+\`\`\`ts
+import { createCapabilityContext, assertCapabilityForOperation } from '@contractspec/lib.contracts';
+
+// Create context from user's enabled capabilities
+const ctx = createCapabilityContext(user.capabilities);
+
+// Check capability
+if (ctx.hasCapability('payments')) {
+  // User can access payments features
+}
+
+// Assert capability (throws if missing)
+ctx.requireCapability('payments');
+
+// Guard an operation
+assertCapabilityForOperation(ctx, paymentOperation);
+
+// Filter operations by enabled capabilities
+const allowedOps = filterOperationsByCapability(ctx, allOperations);
+\`\`\`
+
+## Validation
+
+Validate bidirectional consistency between capabilities and specs:
+
+\`\`\`ts
+import { validateCapabilityConsistency, findOrphanSpecs } from '@contractspec/lib.contracts';
+
+const result = validateCapabilityConsistency({
+  capabilities: capabilityRegistry,
+  operations: operationRegistry,
+  events: eventRegistry,
+  presentations: presentationRegistry,
+});
+
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+
+// Find specs without capability assignment (informational)
+const orphans = findOrphanSpecs({ capabilities, operations });
+\`\`\`
+
+## Feature Integration
+
+During \`installFeature()\`:
+1. \`provides\` capabilities must exist in the registry
+2. \`requires\` must be satisfied by registered capabilities or local \`provides\`
+3. Referenced operations/events/presentations must exist
+
+## Authoring Guidelines
+
+1. **Register capabilities first** before referencing them in features
+2. **Use bidirectional linking** - set \`capability\` on specs and list them in \`provides\`
+3. **Version consciously** - bump versions on breaking changes
+4. **Document dependencies** with \`reason\` strings
+5. **Use inheritance** for capability families with shared requirements
+6. **Validate during CI** with \`validateCapabilityConsistency()\`
+
+## Error Handling
+
+\`\`\`ts
+import { CapabilityMissingError } from '@contractspec/lib.contracts';
+
+try {
+  ctx.requireCapability('premium-features');
+} catch (err) {
+  if (err instanceof CapabilityMissingError) {
+    console.log('Missing:', err.capabilityKey);
+    console.log('Required version:', err.requiredVersion);
+  }
+}
+\`\`\`
+
+## API Reference
+
+### Types
+- \`CapabilitySpec\` - Capability definition
+- \`CapabilityRef\` - Reference to a capability (key + version)
+- \`CapabilitySurfaceRef\` - Reference to a provided surface
+- \`CapabilityRequirement\` - Dependency requirement
+- \`CapabilityContext\` - Runtime capability context
+- \`CapabilityValidationResult\` - Validation result
+
+### Functions
+- \`defineCapability(spec)\` - Define a capability spec
+- \`createCapabilityContext(caps)\` - Create runtime context
+- \`validateCapabilityConsistency(deps)\` - Validate bidirectional links
+- \`findOrphanSpecs(deps)\` - Find specs without capability assignment
+- \`assertCapabilityForOperation/Event/Presentation(ctx, spec)\` - Guards
+- \`filterOperationsByCapability(ctx, ops)\` - Filter by enabled capabilities
+`
 }];
 registerDocBlocks(tech_contracts_capabilities_DocBlocks);
 

package/dist/capabilities/guards.d.ts

@@ -0,0 +1,110 @@
+import { PresentationSpec } from "../presentations/presentations.js";
+import { AnyOperationSpec } from "../operations/operation.js";
+import { CapabilityContext } from "./context.js";
+import { AnyEventSpec } from "../events.js";
+
+//#region src/capabilities/guards.d.ts
+
+/** Result of a capability guard check. */
+interface CapabilityGuardResult {
+  /** Whether the guard passed. */
+  allowed: boolean;
+  /** Missing capability if guard failed. */
+  missingCapability?: {
+    key: string;
+    version: string;
+  };
+  /** Reason for denial if guard failed. */
+  reason?: string;
+}
+/**
+ * Check if an operation's capability is enabled in the context.
+ *
+ * @param ctx - Capability context to check against
+ * @param operation - Operation spec to check
+ * @returns Guard result indicating if operation is allowed
+ *
+ * @example
+ * ```typescript
+ * const result = checkCapabilityForOperation(ctx, myOperation);
+ * if (!result.allowed) {
+ *   console.log('Denied:', result.reason);
+ * }
+ * ```
+ */
+declare function checkCapabilityForOperation(ctx: CapabilityContext, operation: AnyOperationSpec): CapabilityGuardResult;
+/**
+ * Assert that an operation's capability is enabled, throwing if not.
+ *
+ * @param ctx - Capability context to check against
+ * @param operation - Operation spec to check
+ * @throws {CapabilityMissingError} If capability is not enabled
+ *
+ * @example
+ * ```typescript
+ * // Throws if capability missing
+ * assertCapabilityForOperation(ctx, myOperation);
+ *
+ * // Safe to proceed with operation
+ * await handler(input);
+ * ```
+ */
+declare function assertCapabilityForOperation(ctx: CapabilityContext, operation: AnyOperationSpec): void;
+/**
+ * Check if an event's capability is enabled in the context.
+ *
+ * @param ctx - Capability context to check against
+ * @param event - Event spec to check
+ * @returns Guard result indicating if event is allowed
+ */
+declare function checkCapabilityForEvent(ctx: CapabilityContext, event: AnyEventSpec): CapabilityGuardResult;
+/**
+ * Assert that an event's capability is enabled, throwing if not.
+ *
+ * @param ctx - Capability context to check against
+ * @param event - Event spec to check
+ * @throws {CapabilityMissingError} If capability is not enabled
+ */
+declare function assertCapabilityForEvent(ctx: CapabilityContext, event: AnyEventSpec): void;
+/**
+ * Check if a presentation's capability is enabled in the context.
+ *
+ * @param ctx - Capability context to check against
+ * @param presentation - Presentation spec to check
+ * @returns Guard result indicating if presentation is allowed
+ */
+declare function checkCapabilityForPresentation(ctx: CapabilityContext, presentation: PresentationSpec): CapabilityGuardResult;
+/**
+ * Assert that a presentation's capability is enabled, throwing if not.
+ *
+ * @param ctx - Capability context to check against
+ * @param presentation - Presentation spec to check
+ * @throws {CapabilityMissingError} If capability is not enabled
+ */
+declare function assertCapabilityForPresentation(ctx: CapabilityContext, presentation: PresentationSpec): void;
+/**
+ * Filter operations to only those with enabled capabilities.
+ *
+ * @param ctx - Capability context to check against
+ * @param operations - Operations to filter
+ * @returns Operations that have their capabilities enabled (or no capability requirement)
+ */
+declare function filterOperationsByCapability(ctx: CapabilityContext, operations: AnyOperationSpec[]): AnyOperationSpec[];
+/**
+ * Filter events to only those with enabled capabilities.
+ *
+ * @param ctx - Capability context to check against
+ * @param events - Events to filter
+ * @returns Events that have their capabilities enabled (or no capability requirement)
+ */
+declare function filterEventsByCapability(ctx: CapabilityContext, events: AnyEventSpec[]): AnyEventSpec[];
+/**
+ * Filter presentations to only those with enabled capabilities.
+ *
+ * @param ctx - Capability context to check against
+ * @param presentations - Presentations to filter
+ * @returns Presentations that have their capabilities enabled (or no capability requirement)
+ */
+declare function filterPresentationsByCapability(ctx: CapabilityContext, presentations: PresentationSpec[]): PresentationSpec[];
+//#endregion
+export { CapabilityGuardResult, assertCapabilityForEvent, assertCapabilityForOperation, assertCapabilityForPresentation, checkCapabilityForEvent, checkCapabilityForOperation, checkCapabilityForPresentation, filterEventsByCapability, filterOperationsByCapability, filterPresentationsByCapability };

package/dist/capabilities/guards.js

@@ -0,0 +1,146 @@
+import { CapabilityMissingError } from "./context.js";
+
+//#region src/capabilities/guards.ts
+/**
+* Check if an operation's capability is enabled in the context.
+*
+* @param ctx - Capability context to check against
+* @param operation - Operation spec to check
+* @returns Guard result indicating if operation is allowed
+*
+* @example
+* ```typescript
+* const result = checkCapabilityForOperation(ctx, myOperation);
+* if (!result.allowed) {
+*   console.log('Denied:', result.reason);
+* }
+* ```
+*/
+function checkCapabilityForOperation(ctx, operation) {
+	if (!operation.capability) return { allowed: true };
+	const { key, version } = operation.capability;
+	if (ctx.hasCapability(key, version)) return { allowed: true };
+	return {
+		allowed: false,
+		missingCapability: {
+			key,
+			version
+		},
+		reason: `Operation "${operation.meta.key}" requires capability "${key}.v${version}"`
+	};
+}
+/**
+* Assert that an operation's capability is enabled, throwing if not.
+*
+* @param ctx - Capability context to check against
+* @param operation - Operation spec to check
+* @throws {CapabilityMissingError} If capability is not enabled
+*
+* @example
+* ```typescript
+* // Throws if capability missing
+* assertCapabilityForOperation(ctx, myOperation);
+*
+* // Safe to proceed with operation
+* await handler(input);
+* ```
+*/
+function assertCapabilityForOperation(ctx, operation) {
+	const result = checkCapabilityForOperation(ctx, operation);
+	if (!result.allowed && result.missingCapability) throw new CapabilityMissingError(result.missingCapability.key, result.missingCapability.version);
+}
+/**
+* Check if an event's capability is enabled in the context.
+*
+* @param ctx - Capability context to check against
+* @param event - Event spec to check
+* @returns Guard result indicating if event is allowed
+*/
+function checkCapabilityForEvent(ctx, event) {
+	if (!event.capability) return { allowed: true };
+	const { key, version } = event.capability;
+	if (ctx.hasCapability(key, version)) return { allowed: true };
+	return {
+		allowed: false,
+		missingCapability: {
+			key,
+			version
+		},
+		reason: `Event "${event.meta.key}" requires capability "${key}.v${version}"`
+	};
+}
+/**
+* Assert that an event's capability is enabled, throwing if not.
+*
+* @param ctx - Capability context to check against
+* @param event - Event spec to check
+* @throws {CapabilityMissingError} If capability is not enabled
+*/
+function assertCapabilityForEvent(ctx, event) {
+	const result = checkCapabilityForEvent(ctx, event);
+	if (!result.allowed && result.missingCapability) throw new CapabilityMissingError(result.missingCapability.key, result.missingCapability.version);
+}
+/**
+* Check if a presentation's capability is enabled in the context.
+*
+* @param ctx - Capability context to check against
+* @param presentation - Presentation spec to check
+* @returns Guard result indicating if presentation is allowed
+*/
+function checkCapabilityForPresentation(ctx, presentation) {
+	if (!presentation.capability) return { allowed: true };
+	const { key, version } = presentation.capability;
+	if (ctx.hasCapability(key, version)) return { allowed: true };
+	return {
+		allowed: false,
+		missingCapability: {
+			key,
+			version
+		},
+		reason: `Presentation "${presentation.meta.key}" requires capability "${key}.v${version}"`
+	};
+}
+/**
+* Assert that a presentation's capability is enabled, throwing if not.
+*
+* @param ctx - Capability context to check against
+* @param presentation - Presentation spec to check
+* @throws {CapabilityMissingError} If capability is not enabled
+*/
+function assertCapabilityForPresentation(ctx, presentation) {
+	const result = checkCapabilityForPresentation(ctx, presentation);
+	if (!result.allowed && result.missingCapability) throw new CapabilityMissingError(result.missingCapability.key, result.missingCapability.version);
+}
+/**
+* Filter operations to only those with enabled capabilities.
+*
+* @param ctx - Capability context to check against
+* @param operations - Operations to filter
+* @returns Operations that have their capabilities enabled (or no capability requirement)
+*/
+function filterOperationsByCapability(ctx, operations) {
+	return operations.filter((op) => checkCapabilityForOperation(ctx, op).allowed);
+}
+/**
+* Filter events to only those with enabled capabilities.
+*
+* @param ctx - Capability context to check against
+* @param events - Events to filter
+* @returns Events that have their capabilities enabled (or no capability requirement)
+*/
+function filterEventsByCapability(ctx, events) {
+	return events.filter((ev) => checkCapabilityForEvent(ctx, ev).allowed);
+}
+/**
+* Filter presentations to only those with enabled capabilities.
+*
+* @param ctx - Capability context to check against
+* @param presentations - Presentations to filter
+* @returns Presentations that have their capabilities enabled (or no capability requirement)
+*/
+function filterPresentationsByCapability(ctx, presentations) {
+	return presentations.filter((pres) => checkCapabilityForPresentation(ctx, pres).allowed);
+}
+
+//#endregion
+export { assertCapabilityForEvent, assertCapabilityForOperation, assertCapabilityForPresentation, checkCapabilityForEvent, checkCapabilityForOperation, checkCapabilityForPresentation, filterEventsByCapability, filterOperationsByCapability, filterPresentationsByCapability };

package/dist/capabilities/index.d.ts

@@ -1,3 +1,6 @@
 import { CapabilityKind, CapabilityMeta, CapabilityRef, CapabilityRegistry, CapabilityRequirement, CapabilitySpec, CapabilitySurface, CapabilitySurfaceRef, capabilityKey, defineCapability } from "./capabilities.js";
+import { CapabilityValidationDeps, CapabilityValidationError, CapabilityValidationResult, findOrphanSpecs, validateCapabilityConsistency } from "./validation.js";
+import { CapabilityContext, CapabilityMissingError, createBypassCapabilityContext, createCapabilityContext, createEmptyCapabilityContext } from "./context.js";
+import { CapabilityGuardResult, assertCapabilityForEvent, assertCapabilityForOperation, assertCapabilityForPresentation, checkCapabilityForEvent, checkCapabilityForOperation, checkCapabilityForPresentation, filterEventsByCapability, filterOperationsByCapability, filterPresentationsByCapability } from "./guards.js";
 import { openBankingAccountsReadCapability, openBankingBalancesReadCapability, openBankingTransactionsReadCapability, registerOpenBankingCapabilities } from "./openbanking.js";
-export { CapabilityKind, CapabilityMeta, CapabilityRef, CapabilityRegistry, CapabilityRequirement, CapabilitySpec, CapabilitySurface, CapabilitySurfaceRef, capabilityKey, defineCapability, openBankingAccountsReadCapability, openBankingBalancesReadCapability, openBankingTransactionsReadCapability, registerOpenBankingCapabilities };
+export { CapabilityContext, CapabilityGuardResult, CapabilityKind, CapabilityMeta, CapabilityMissingError, CapabilityRef, CapabilityRegistry, CapabilityRequirement, CapabilitySpec, CapabilitySurface, CapabilitySurfaceRef, CapabilityValidationDeps, CapabilityValidationError, CapabilityValidationResult, assertCapabilityForEvent, assertCapabilityForOperation, assertCapabilityForPresentation, capabilityKey, checkCapabilityForEvent, checkCapabilityForOperation, checkCapabilityForPresentation, createBypassCapabilityContext, createCapabilityContext, createEmptyCapabilityContext, defineCapability, filterEventsByCapability, filterOperationsByCapability, filterPresentationsByCapability, findOrphanSpecs, openBankingAccountsReadCapability, openBankingBalancesReadCapability, openBankingTransactionsReadCapability, registerOpenBankingCapabilities, validateCapabilityConsistency };

package/dist/capabilities/index.js

@@ -1,4 +1,7 @@
 import { CapabilityRegistry, capabilityKey, defineCapability } from "./capabilities.js";
+import { findOrphanSpecs, validateCapabilityConsistency } from "./validation.js";
+import { CapabilityMissingError, createBypassCapabilityContext, createCapabilityContext, createEmptyCapabilityContext } from "./context.js";
+import { assertCapabilityForEvent, assertCapabilityForOperation, assertCapabilityForPresentation, checkCapabilityForEvent, checkCapabilityForOperation, checkCapabilityForPresentation, filterEventsByCapability, filterOperationsByCapability, filterPresentationsByCapability } from "./guards.js";
 import { openBankingAccountsReadCapability, openBankingBalancesReadCapability, openBankingTransactionsReadCapability, registerOpenBankingCapabilities } from "./openbanking.js";
 
-export { CapabilityRegistry, capabilityKey, defineCapability, openBankingAccountsReadCapability, openBankingBalancesReadCapability, openBankingTransactionsReadCapability, registerOpenBankingCapabilities };
+export { CapabilityMissingError, CapabilityRegistry, assertCapabilityForEvent, assertCapabilityForOperation, assertCapabilityForPresentation, capabilityKey, checkCapabilityForEvent, checkCapabilityForOperation, checkCapabilityForPresentation, createBypassCapabilityContext, createCapabilityContext, createEmptyCapabilityContext, defineCapability, filterEventsByCapability, filterOperationsByCapability, filterPresentationsByCapability, findOrphanSpecs, openBankingAccountsReadCapability, openBankingBalancesReadCapability, openBankingTransactionsReadCapability, registerOpenBankingCapabilities, validateCapabilityConsistency };

package/dist/capabilities/validation.d.ts

@@ -0,0 +1,76 @@
+import { CapabilityRegistry, CapabilitySurface } from "./capabilities.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
+import { PresentationRegistry } from "../presentations/registry.js";
+import "../presentations/index.js";
+import { EventRegistry } from "../events.js";
+
+//#region src/capabilities/validation.d.ts
+
+/** Single validation error describing an inconsistency. */
+interface CapabilityValidationError {
+  /** Type of validation error. */
+  type: 'missing_surface_spec' | 'orphan_spec' | 'capability_not_found' | 'surface_not_in_provides';
+  /** Human-readable error message. */
+  message: string;
+  /** Capability key involved (if applicable). */
+  capabilityKey?: string;
+  /** Surface type involved (if applicable). */
+  surface?: CapabilitySurface;
+  /** Spec key involved (if applicable). */
+  specKey?: string;
+}
+/** Result of capability consistency validation. */
+interface CapabilityValidationResult {
+  /** Whether validation passed with no errors. */
+  valid: boolean;
+  /** List of validation errors found. */
+  errors: CapabilityValidationError[];
+  /** List of warnings (non-blocking issues). */
+  warnings: CapabilityValidationError[];
+}
+/** Registries needed for full bidirectional validation. */
+interface CapabilityValidationDeps {
+  capabilities: CapabilityRegistry;
+  operations?: OperationSpecRegistry;
+  events?: EventRegistry;
+  presentations?: PresentationRegistry;
+}
+/**
+ * Validates bidirectional consistency between capabilities and their surfaces.
+ *
+ * Checks:
+ * 1. Forward validation: Every surface ref in capability `provides` exists
+ * 2. Reverse validation: Every spec with `capability` field is in that capability's `provides`
+ *
+ * @param deps - Registries to validate against
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateCapabilityConsistency({
+ *   capabilities: capabilityRegistry,
+ *   operations: operationRegistry,
+ *   events: eventRegistry,
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error('Capability validation failed:', result.errors);
+ * }
+ * ```
+ */
+declare function validateCapabilityConsistency(deps: CapabilityValidationDeps): CapabilityValidationResult;
+/**
+ * Finds specs that have no capability assignment (orphan specs).
+ * This is informational - orphan specs are allowed but may indicate
+ * incomplete capability modeling.
+ *
+ * @param deps - Registries to check
+ * @returns List of spec keys without capability assignment
+ */
+declare function findOrphanSpecs(deps: CapabilityValidationDeps): {
+  operations: string[];
+  events: string[];
+  presentations: string[];
+};
+//#endregion
+export { CapabilityValidationDeps, CapabilityValidationError, CapabilityValidationResult, findOrphanSpecs, validateCapabilityConsistency };