@lssm/lib.contracts-spec 17.3.2

package/dist/capabilities/capabilities.d.ts

@@ -0,0 +1,109 @@
+/** Classification of capability types. */
+import type { DocBlock } from '../docs/types.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import type { VersionedSpecRef } from '../versioning/index.js';
+export type CapabilityKind = 'api' | 'event' | 'data' | 'ui' | 'integration';
+/** Surfaces where capabilities can be exposed or consumed. */
+export type CapabilitySurface = 'operation' | 'event' | 'workflow' | 'presentation' | 'visual-scenario' | 'resource' | 'navigation';
+/**
+ * Reference to a capability on a specific surface.
+ * Extends VersionedSpecRef with surface and description context.
+ */
+export 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;
+    /** 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. */
+export 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.
+ */
+export 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;
+}
+/**
+ * Reference to a capability spec.
+ * Uses key and version to identify a specific capability.
+ */
+export type CapabilityRef = VersionedSpecRef;
+export 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[];
+}
+export 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 visual scenario keys provided by a capability. */
+    getVisualScenariosFor(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[];
+    /**
+     * Index of capability keys keyed by `"<surface>:<surfaceKey>"`.
+     *
+     * Used by surface-specific registries (e.g. `NavRegistry`) to validate
+     * that a referenced capability actually provides the expected surface.
+     */
+    indexBySurface(surface: CapabilitySurface): Map<string, Set<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 capability refs that provide a specific visual scenario. */
+    getCapabilitiesForVisualScenario(visualScenarioKey: 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[];
+}
+export declare function capabilityKey(spec: CapabilitySpec): string;
+export declare function defineCapability(spec: CapabilitySpec): CapabilitySpec;
+export declare const tech_contracts_capabilities_DocBlocks: DocBlock[];

package/dist/capabilities/capabilities.js

@@ -0,0 +1,187 @@
+export class CapabilityRegistry{items=new Map;surfaceIndex=null;register(e){const s=o(e.meta.key,e.meta.version);if(this.items.has(s))throw Error(`Duplicate capability ${s}`);this.items.set(s,e);this.surfaceIndex=null;return this}list(){return[...this.items.values()]}get(e,s){if(s!=null)return this.items.get(o(e,s));let i;for(const t of this.items.values()){if(t.meta.key!==e)continue;if(!i||p(t.meta.version,i.meta.version)>0)i=t}return i}satisfies(e,s){if(e.optional)return!0;if(s?.some((t)=>c(t,e)))return!0;const i=e.version?this.get(e.key,e.version):this.get(e.key);if(!i)return!1;if(e.kind&&i.meta.kind!==e.kind)return!1;if(e.version!=null&&i.meta.version!==e.version)return!1;return!0}buildSurfaceIndex(){if(this.surfaceIndex)return this.surfaceIndex;this.surfaceIndex=new Map;for(const e of this.items.values()){const s=o(e.meta.key,e.meta.version);for(const i of e.provides??[]){const t=`${i.surface}:${i.key}`;if(!this.surfaceIndex.has(t))this.surfaceIndex.set(t,new Set);this.surfaceIndex.get(t)?.add(s)}}return this.surfaceIndex}getOperationsFor(e,s){const i=this.get(e,s);if(!i)return[];return i.provides?.filter((t)=>t.surface==="operation").map((t)=>t.key)??[]}getEventsFor(e,s){const i=this.get(e,s);if(!i)return[];return i.provides?.filter((t)=>t.surface==="event").map((t)=>t.key)??[]}getPresentationsFor(e,s){const i=this.get(e,s);if(!i)return[];return i.provides?.filter((t)=>t.surface==="presentation").map((t)=>t.key)??[]}getVisualScenariosFor(e,s){const i=this.get(e,s);if(!i)return[];return i.provides?.filter((t)=>t.surface==="visual-scenario").map((t)=>t.key)??[]}getWorkflowsFor(e,s){const i=this.get(e,s);if(!i)return[];return i.provides?.filter((t)=>t.surface==="workflow").map((t)=>t.key)??[]}getResourcesFor(e,s){const i=this.get(e,s);if(!i)return[];return i.provides?.filter((t)=>t.surface==="resource").map((t)=>t.key)??[]}indexBySurface(e){const s=this.buildSurfaceIndex(),i=new Map,t=`${e}:`;for(const[a,r]of s)if(a.startsWith(t))i.set(a,r);return i}getCapabilitiesForOperation(e){const i=this.buildSurfaceIndex().get(`operation:${e}`);if(!i)return[];return[...i].map((t)=>{const a=this.items.get(t);return{key:a?.meta.key??"",version:a?.meta.version??""}})}getCapabilitiesForEvent(e){const i=this.buildSurfaceIndex().get(`event:${e}`);if(!i)return[];return[...i].map((t)=>{const a=this.items.get(t);return{key:a?.meta.key??"",version:a?.meta.version??""}})}getCapabilitiesForPresentation(e){const i=this.buildSurfaceIndex().get(`presentation:${e}`);if(!i)return[];return[...i].map((t)=>{const a=this.items.get(t);return{key:a?.meta.key??"",version:a?.meta.version??""}})}getCapabilitiesForVisualScenario(e){const i=this.buildSurfaceIndex().get(`visual-scenario:${e}`);if(!i)return[];return[...i].map((t)=>{const a=this.items.get(t);return{key:a?.meta.key??"",version:a?.meta.version??""}})}getAncestors(e,s){const i=[],t=new Set;let a=this.get(e,s);while(a?.extends){const r=o(a.extends.key,a.extends.version);if(t.has(r))break;t.add(r);const n=this.get(a.extends.key,a.extends.version);if(!n)break;i.push(n);a=n}return i}getEffectiveRequirements(e,s){const i=this.get(e,s);if(!i)return[];const t=this.getAncestors(e,s),a=new Map;for(const r of[...t].reverse())for(const n of r.requires??[])a.set(n.key,n);for(const r of i.requires??[])a.set(r.key,r);return[...a.values()]}getEffectiveSurfaces(e,s){const i=this.get(e,s);if(!i)return[];const t=this.getAncestors(e,s),a=[];for(const r of[...t].reverse())a.push(...r.provides??[]);a.push(...i.provides??[]);return a}}import{compareVersions as p}from"compare-versions";const o=(e,s)=>`${e}.v${s}`;function c(e,s){if(e.key!==s.key)return!1;if(s.version!=null&&e.version!==s.version)return!1;return!0}export function capabilityKey(e){return o(e.meta.key,e.meta.version)}export function defineCapability(e){return e}export const tech_contracts_capabilities_DocBlocks=[{id:"docs.tech.contracts.capabilities",title:"CapabilitySpec Overview",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",tags:["tech","contracts","capabilities"],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 \u2192 Specs
+registry.getOperationsFor('payments');      // ['payments.charge.create', ...]
+registry.getEventsFor('payments');          // ['payments.charge.succeeded', ...]
+registry.getPresentationsFor('payments');   // ['payments.dashboard', ...]
+
+// Reverse lookups: Spec \u2192 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
+
+// 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
+
+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
+
+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
+`}];

package/dist/capabilities/context.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Runtime capability context for opt-in capability enforcement.
+ *
+ * Provides a context object that can be used to check if a user/tenant
+ * has access to specific capabilities at runtime.
+ *
+ * @module capabilities/context
+ *
+ * @example
+ * ```typescript
+ * import { createCapabilityContext } from '@lssm/lib.contracts-spec';
+ *
+ * // Create context from user's enabled capabilities
+ * const ctx = createCapabilityContext([
+ *   { key: 'payments', version: '1.0.0' },
+ *   { key: 'analytics', version: '2.0.0' },
+ * ]);
+ *
+ * // Check capabilities
+ * if (ctx.hasCapability('payments')) {
+ *   // User can access payments features
+ * }
+ *
+ * // Require capability (throws if missing)
+ * ctx.requireCapability('payments');
+ * ```
+ */
+import type { CapabilityRef } from './capabilities.js';
+/**
+ * Error thrown when a required capability is missing.
+ */
+export 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.
+ */
+export 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');
+ * ```
+ */
+export declare function createCapabilityContext(enabledCapabilities: CapabilityRef[]): CapabilityContext;
+/**
+ * Creates an empty capability context (no capabilities enabled).
+ * Useful for anonymous users or testing.
+ */
+export 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
+ */
+export declare function createBypassCapabilityContext(allCapabilities: CapabilityRef[]): CapabilityContext;

package/dist/capabilities/context.js

@@ -0,0 +1 @@
+class s{capabilities;capabilityVersions;constructor(i){const t=new Set,e=new Map;for(const a of i){t.add(a.key);e.set(a.key,a.version)}this.capabilities=t;this.capabilityVersions=e}hasCapability(i,t){if(!this.capabilities.has(i))return!1;if(t!=null)return this.capabilityVersions.get(i)===t;return!0}requireCapability(i,t){if(!this.hasCapability(i,t))throw new CapabilityMissingError(i,t)}hasAllCapabilities(i){return i.every((t)=>this.capabilities.has(t))}hasAnyCapability(i){return i.some((t)=>this.capabilities.has(t))}getMatchingCapabilities(i){if(!i.includes("*"))return this.capabilities.has(i)?[i]:[];const t=i.replace(/[.+^${}()|[\]\\]/g,"\\$&").replace(/\*/g,".*"),e=new RegExp(`^${t}$`);return[...this.capabilities].filter((a)=>e.test(a))}}export class CapabilityMissingError extends Error{capabilityKey;requiredVersion;constructor(i,t){const e=t?`.v${t}`:"";super(`Missing required capability: ${i}${e}`);this.name="CapabilityMissingError";this.capabilityKey=i;this.requiredVersion=t}}export function createCapabilityContext(i){return new s(i)}export function createEmptyCapabilityContext(){return new s([])}export function createBypassCapabilityContext(i){return new s(i)}

package/dist/capabilities/guards.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Capability guards for runtime enforcement.
+ *
+ * Provides utilities to assert that operations/events/presentations
+ * have their required capabilities enabled before execution.
+ *
+ * @module capabilities/guards
+ *
+ * @example
+ * ```typescript
+ * import { assertCapabilityForOperation } from '@lssm/lib.contracts-spec';
+ *
+ * // In a handler or middleware
+ * assertCapabilityForOperation(ctx, operation);
+ * ```
+ */
+import type { AnyEventSpec } from '../events.js';
+import type { AnyOperationSpec } from '../operations/operation.js';
+import type { PresentationSpec } from '../presentations/presentations.js';
+import type { CapabilityContext } from './context.js';
+/** Result of a capability guard check. */
+export 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);
+ * }
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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)
+ */
+export 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)
+ */
+export 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)
+ */
+export declare function filterPresentationsByCapability(ctx: CapabilityContext, presentations: PresentationSpec[]): PresentationSpec[];

package/dist/capabilities/guards.js

@@ -0,0 +1 @@
+import{CapabilityMissingError as n}from"./context.js";export function checkCapabilityForOperation(e,t){if(!t.capability)return{allowed:!0};const{key:i,version:a}=t.capability;if(e.hasCapability(i,a))return{allowed:!0};return{allowed:!1,missingCapability:{key:i,version:a},reason:`Operation "${t.meta.key}" requires capability "${i}.v${a}"`}}export function assertCapabilityForOperation(e,t){const i=checkCapabilityForOperation(e,t);if(!i.allowed&&i.missingCapability)throw new n(i.missingCapability.key,i.missingCapability.version)}export function checkCapabilityForEvent(e,t){if(!t.capability)return{allowed:!0};const{key:i,version:a}=t.capability;if(e.hasCapability(i,a))return{allowed:!0};return{allowed:!1,missingCapability:{key:i,version:a},reason:`Event "${t.meta.key}" requires capability "${i}.v${a}"`}}export function assertCapabilityForEvent(e,t){const i=checkCapabilityForEvent(e,t);if(!i.allowed&&i.missingCapability)throw new n(i.missingCapability.key,i.missingCapability.version)}export function checkCapabilityForPresentation(e,t){if(!t.capability)return{allowed:!0};const{key:i,version:a}=t.capability;if(e.hasCapability(i,a))return{allowed:!0};return{allowed:!1,missingCapability:{key:i,version:a},reason:`Presentation "${t.meta.key}" requires capability "${i}.v${a}"`}}export function assertCapabilityForPresentation(e,t){const i=checkCapabilityForPresentation(e,t);if(!i.allowed&&i.missingCapability)throw new n(i.missingCapability.key,i.missingCapability.version)}export function filterOperationsByCapability(e,t){return t.filter((i)=>checkCapabilityForOperation(e,i).allowed)}export function filterEventsByCapability(e,t){return t.filter((i)=>checkCapabilityForEvent(e,i).allowed)}export function filterPresentationsByCapability(e,t){return t.filter((i)=>checkCapabilityForPresentation(e,i).allowed)}

package/dist/capabilities/index.d.js

@@ -0,0 +1 @@
+export*from"./agent-workflow.js";export*from"./capabilities.js";export*from"./context.js";export*from"./guards.js";export*from"./meeting-recorder.js";export*from"./openbanking.js";export*from"./validation.js";

package/dist/capabilities/index.d.ts

@@ -0,0 +1,7 @@
+export * from './agent-workflow.js';
+export * from './capabilities.js';
+export * from './context.js';
+export * from './guards.js';
+export * from './meeting-recorder.js';
+export * from './openbanking.js';
+export * from './validation.js';

package/dist/capabilities/index.js

@@ -0,0 +1 @@
+export*from"./agent-workflow.js";export*from"./capabilities.js";export*from"./context.js";export*from"./guards.js";export*from"./meeting-recorder.js";export*from"./openbanking.js";export*from"./validation.js";

package/dist/capabilities/meeting-recorder.d.ts

@@ -0,0 +1,5 @@
+import type { CapabilityRegistry, CapabilitySpec } from '../capabilities/index.js';
+export declare const meetingRecorderMeetingsReadCapability: CapabilitySpec;
+export declare const meetingRecorderTranscriptsReadCapability: CapabilitySpec;
+export declare const meetingRecorderWebhooksCapability: CapabilitySpec;
+export declare function registerMeetingRecorderCapabilities(registry: CapabilityRegistry): CapabilityRegistry;

package/dist/capabilities/meeting-recorder.js

@@ -0,0 +1 @@
+import{StabilityEnum as e}from"../ownership.js";const r=["platform.integrations"];const i=["meeting-recorder","transcripts","integrations"];export const meetingRecorderMeetingsReadCapability={meta:{key:"meeting-recorder.meetings.read",version:"1.0.0",kind:"integration",title:"Meeting Recorder Meetings (Read)",description:"Provides read-only access to recorded meetings and their metadata.",domain:"integrations",owners:[...r],tags:[...i,"meetings"],stability:e.Experimental},provides:[{surface:"operation",key:"meeting-recorder.meetings.list",version:"1.0.0",description:"List meetings available from the recorder provider."},{surface:"operation",key:"meeting-recorder.meetings.get",version:"1.0.0",description:"Fetch detailed metadata for a specific meeting."}]};export const meetingRecorderTranscriptsReadCapability={meta:{key:"meeting-recorder.transcripts.read",version:"1.0.0",kind:"integration",title:"Meeting Recorder Transcripts (Read)",description:"Enables retrieval of transcripts for recorded meetings from external providers.",domain:"integrations",owners:[...r],tags:[...i,"transcripts"],stability:e.Experimental},provides:[{surface:"operation",key:"meeting-recorder.transcripts.get",version:"1.0.0",description:"Fetch the transcript for a specific meeting recording."},{surface:"operation",key:"meeting-recorder.transcripts.sync",version:"1.0.0",description:"Trigger a transcript sync from the recorder provider."}]};export const meetingRecorderWebhooksCapability={meta:{key:"meeting-recorder.webhooks",version:"1.0.0",kind:"integration",title:"Meeting Recorder Webhooks",description:"Allows processing of webhook events for meeting transcript readiness.",domain:"integrations",owners:[...r],tags:[...i,"webhooks"],stability:e.Experimental},provides:[{surface:"operation",key:"meeting-recorder.webhooks.ingest",version:"1.0.0",description:"Ingest and verify meeting recorder webhook payloads."}]};export function registerMeetingRecorderCapabilities(t){return t.register(meetingRecorderMeetingsReadCapability).register(meetingRecorderTranscriptsReadCapability).register(meetingRecorderWebhooksCapability)}

package/dist/capabilities/openbanking.d.ts

@@ -0,0 +1,5 @@
+import type { CapabilityRegistry, CapabilitySpec } from '../capabilities/index.js';
+export declare const openBankingAccountsReadCapability: CapabilitySpec;
+export declare const openBankingTransactionsReadCapability: CapabilitySpec;
+export declare const openBankingBalancesReadCapability: CapabilitySpec;
+export declare function registerOpenBankingCapabilities(registry: CapabilityRegistry): CapabilityRegistry;

package/dist/capabilities/openbanking.js

@@ -0,0 +1 @@
+import{StabilityEnum as n}from"../ownership.js";const e=["platform.finance"];const a=["open-banking","finance"];export const openBankingAccountsReadCapability={meta:{key:"openbanking.accounts.read",version:"1.0.0",kind:"integration",title:"Open Banking Accounts (Read)",description:"Provides read-only access to linked bank accounts, including account summaries and metadata.",domain:"finance",owners:[...e],tags:[...a],stability:n.Experimental},provides:[{surface:"operation",key:"openbanking.accounts.list",version:"1.0.0",description:"List bank accounts linked to a Powens open banking connection."},{surface:"operation",key:"openbanking.accounts.get",version:"1.0.0",description:"Retrieve the canonical bank account record for a specific account."},{surface:"operation",key:"openbanking.accounts.sync",version:"1.0.0",description:"Trigger a refresh of bank account metadata from the open banking provider."}]};export const openBankingTransactionsReadCapability={meta:{key:"openbanking.transactions.read",version:"1.0.0",kind:"integration",title:"Open Banking Transactions (Read)",description:"Enables retrieval of transaction history for linked bank accounts via open banking providers.",domain:"finance",owners:[...e],tags:[...a,"transactions"],stability:n.Experimental},provides:[{surface:"operation",key:"openbanking.transactions.list",version:"1.0.0",description:"List transactions for a given bank account with optional date filtering."},{surface:"operation",key:"openbanking.transactions.sync",version:"1.0.0",description:"Synchronise transactions from the open banking provider into the canonical ledger."}]};export const openBankingBalancesReadCapability={meta:{key:"openbanking.balances.read",version:"1.0.0",kind:"integration",title:"Open Banking Balances (Read)",description:"Allows querying of current and available balances for linked bank accounts via open banking providers.",domain:"finance",owners:[...e],tags:[...a,"balances"],stability:n.Experimental},provides:[{surface:"operation",key:"openbanking.balances.get",version:"1.0.0",description:"Retrieve the latest known balances for a specified bank account."},{surface:"operation",key:"openbanking.balances.refresh",version:"1.0.0",description:"Force a balance refresh from the open banking provider."}]};export function registerOpenBankingCapabilities(i){return i.register(openBankingAccountsReadCapability).register(openBankingTransactionsReadCapability).register(openBankingBalancesReadCapability)}