@contractspec/lib.contracts 0.0.0-canary-20260119225944 → 0.0.0-canary-20260202053150

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 };

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);