@stackwright-services/capabilities 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,750 @@
+import { CapabilityDefinition, PredicateCondition } from '@stackwright-services/types';
+import { z } from 'zod';
+
+/**
+ * Runtime capability handler -- the actual implementation function.
+ *
+ * For transforms: pure function, no side effects.
+ * For effects: may perform I/O (HTTP calls, notifications, etc.)
+ */
+type CapabilityHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: CapabilityContext) => Promise<TOutput>;
+/**
+ * Minimal message bus interface for capability handlers.
+ *
+ * This is a subset of MessageBusProvider (from @stackwright-services/runtime).
+ * Defined inline to avoid circular dependency (capabilities ← runtime).
+ * Runtime's MessageBusProvider structurally satisfies this interface.
+ */
+interface CapabilityMessageBus {
+    publish(topic: string, message: {
+        payload: unknown;
+        traceContext?: Record<string, string>;
+        metadata?: {
+            timestamp?: string;
+            source?: string;
+            correlationId?: string;
+            messageId?: string;
+        };
+    }): Promise<{
+        messageId: string;
+        topic: string;
+        success: boolean;
+    }>;
+}
+/**
+ * Minimal data source provider interface for capability handlers.
+ *
+ * This is a subset of DataSourceProvider (from @stackwright-services/runtime).
+ * Defined inline to avoid circular dependency (capabilities ← runtime).
+ * Runtime's DataSourceProvider structurally satisfies this interface.
+ *
+ * Used by service.call to delegate to a typed provider when one is installed,
+ * falling back to raw HTTP when the source is not known by any provider.
+ */
+interface CapabilityDataSourceProvider {
+    /** Enumerate all sources this provider knows. Used to check resolvability before execute(). */
+    listSources(): Array<{
+        id: string;
+    }>;
+    /**
+     * Execute a named operation against a source.
+     * @param source - Source ID (without transport prefix, e.g. "equipment-api")
+     * @param operation - Operation name (e.g. "listUnits")
+     * @param params - Operation parameters
+     */
+    execute(source: string, operation: string, params: unknown): Promise<{
+        data: unknown;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Minimal notification provider interface for capability handlers.
+ *
+ * This is a subset of NotificationProvider (from @stackwright-services/runtime).
+ * Defined inline to avoid circular dependency (capabilities ← runtime).
+ * Runtime's NotificationProvider structurally satisfies this interface.
+ */
+interface CapabilityNotificationProvider {
+    send(notification: {
+        /** Recipient user identifier — the provider resolves this to a delivery address */
+        recipient: string;
+        /** Delivery channel */
+        channel: 'email' | 'sms' | 'push' | 'in-app';
+        /** Template name for the notification content */
+        template: string;
+        /** Typed payload for template interpolation */
+        payload: unknown;
+        /** Optional subject line (for email, push) */
+        subject?: string;
+        /** Trace context for observability */
+        traceContext?: Record<string, string>;
+        /** Message metadata */
+        metadata?: {
+            timestamp?: string;
+            source?: string;
+            correlationId?: string;
+        };
+    }): Promise<{
+        notificationId: string;
+        channel: string;
+        success: boolean;
+    }>;
+}
+/**
+ * Runtime context passed to every capability handler.
+ * Provides controlled access to runtime services without ambient permissions.
+ */
+interface CapabilityContext {
+    /** Trace ID for observability correlation */
+    traceId: string;
+    /** Logger scoped to this capability invocation */
+    logger: CapabilityLogger;
+    /** Message bus for publishing events (injected by runtime, optional) */
+    messageBus?: CapabilityMessageBus;
+    /** Notification provider for sending user notifications (injected by runtime, optional) */
+    notificationProvider?: CapabilityNotificationProvider;
+    /**
+     * Data source provider for typed, permission-scoped source access (injected by runtime, optional).
+     * When present and a source is resolvable, service.call delegates to this instead of raw HTTP.
+     */
+    dataSourceProvider?: CapabilityDataSourceProvider;
+}
+interface CapabilityLogger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * A registered capability -- definition + handler + runtime schemas.
+ */
+interface RegisteredCapability<TInput = unknown, TOutput = unknown> {
+    /** The capability definition (from types package) */
+    definition: CapabilityDefinition;
+    /** The runtime handler function */
+    handler: CapabilityHandler<TInput, TOutput>;
+    /** Zod schema for runtime input validation */
+    inputSchema: z.ZodType<TInput>;
+    /** Zod schema for runtime output validation */
+    outputSchema: z.ZodType<TOutput>;
+}
+/**
+ * The capability registry -- the audited library of what the system can do.
+ *
+ * This is the backend mirror of the frontend content-type registry.
+ * Citizen developers compose from it; engineers extend it.
+ * Registration is the audit chokepoint.
+ */
+declare class CapabilityRegistry {
+    private capabilities;
+    /**
+     * Register a capability. This is a security-relevant operation --
+     * every registration should be audited.
+     *
+     * @throws if a capability with the same name is already registered
+     */
+    register<TInput, TOutput>(definition: CapabilityDefinition, handler: CapabilityHandler<TInput, TOutput>, inputSchema: z.ZodType<TInput>, outputSchema: z.ZodType<TOutput>): void;
+    /**
+     * Look up a capability by name.
+     * @returns the registered capability, or undefined if not found
+     */
+    lookup(name: string): RegisteredCapability | undefined;
+    /**
+     * Get a capability by name, throwing if not found.
+     * @throws if the capability is not registered
+     */
+    get(name: string): RegisteredCapability;
+    /**
+     * List all registered capabilities.
+     */
+    listAll(): RegisteredCapability[];
+    /**
+     * List all registered capability names.
+     */
+    listNames(): string[];
+    /**
+     * Filter capabilities by kind (transform or effect).
+     */
+    filterByKind(kind: 'transform' | 'effect'): RegisteredCapability[];
+    /**
+     * Check if a capability is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Get the count of registered capabilities.
+     */
+    get size(): number;
+    /**
+     * Clear all registrations. Primarily for testing.
+     */
+    clear(): void;
+}
+/**
+ * The global default registry instance.
+ * Packages register their capabilities here at import time.
+ */
+declare const defaultRegistry: CapabilityRegistry;
+
+declare const UnitsConvertInput: z.ZodObject<{
+    value: z.ZodNumber;
+    from: z.ZodString;
+    to: z.ZodString;
+    category: z.ZodEnum<["length", "weight", "temperature", "volume"]>;
+}, "strip", z.ZodTypeAny, {
+    value: number;
+    from: string;
+    to: string;
+    category: "length" | "weight" | "temperature" | "volume";
+}, {
+    value: number;
+    from: string;
+    to: string;
+    category: "length" | "weight" | "temperature" | "volume";
+}>;
+type UnitsConvertInput = z.infer<typeof UnitsConvertInput>;
+declare const UnitsConvertOutput: z.ZodObject<{
+    result: z.ZodNumber;
+    from: z.ZodString;
+    to: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    result: number;
+    from: string;
+    to: string;
+}, {
+    result: number;
+    from: string;
+    to: string;
+}>;
+type UnitsConvertOutput = z.infer<typeof UnitsConvertOutput>;
+declare const unitsConvertHandler: CapabilityHandler<UnitsConvertInput, UnitsConvertOutput>;
+
+declare const TextFormatInput: z.ZodObject<{
+    template: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, "strip", z.ZodTypeAny, {
+    params: Record<string, string | number | boolean>;
+    template: string;
+}, {
+    params: Record<string, string | number | boolean>;
+    template: string;
+}>;
+type TextFormatInput = z.infer<typeof TextFormatInput>;
+declare const TextFormatOutput: z.ZodObject<{
+    result: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    result: string;
+}, {
+    result: string;
+}>;
+type TextFormatOutput = z.infer<typeof TextFormatOutput>;
+declare const textFormatHandler: CapabilityHandler<TextFormatInput, TextFormatOutput>;
+
+declare const CollectionFilterInput: z.ZodObject<{
+    items: z.ZodArray<z.ZodUnknown, "many">;
+    conditions: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodString;
+        value: z.ZodOptional<z.ZodUnknown>;
+        value_field: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        op: string;
+        value?: unknown;
+        value_field?: string | undefined;
+    }, {
+        field: string;
+        op: string;
+        value?: unknown;
+        value_field?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    items: unknown[];
+    conditions: {
+        field: string;
+        op: string;
+        value?: unknown;
+        value_field?: string | undefined;
+    }[];
+}, {
+    items: unknown[];
+    conditions: {
+        field: string;
+        op: string;
+        value?: unknown;
+        value_field?: string | undefined;
+    }[];
+}>;
+type CollectionFilterInput = z.infer<typeof CollectionFilterInput>;
+declare const CollectionFilterOutput: z.ZodObject<{
+    items: z.ZodArray<z.ZodUnknown, "many">;
+    count: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    count: number;
+    items: unknown[];
+}, {
+    count: number;
+    items: unknown[];
+}>;
+type CollectionFilterOutput = z.infer<typeof CollectionFilterOutput>;
+/**
+ * Evaluate a single typed predicate condition against an item.
+ *
+ * This function implements the CLOSED operator set from PredicateOperator.
+ * It uses an exhaustive switch -- adding an operator requires updating this function.
+ *
+ * @security-critical -- only the 13 operators in the closed enum are supported.
+ */
+declare function evaluatePredicate(item: unknown, condition: PredicateCondition): boolean;
+declare const collectionFilterHandler: CapabilityHandler<CollectionFilterInput, CollectionFilterOutput>;
+
+declare const CollectionAggregateInput: z.ZodObject<{
+    items: z.ZodArray<z.ZodUnknown, "many">;
+    field: z.ZodString;
+    operation: z.ZodEnum<["count", "sum", "avg", "min", "max"]>;
+}, "strip", z.ZodTypeAny, {
+    items: unknown[];
+    field: string;
+    operation: "count" | "sum" | "avg" | "min" | "max";
+}, {
+    items: unknown[];
+    field: string;
+    operation: "count" | "sum" | "avg" | "min" | "max";
+}>;
+type CollectionAggregateInput = z.infer<typeof CollectionAggregateInput>;
+declare const CollectionAggregateOutput: z.ZodObject<{
+    result: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    result: number;
+}, {
+    result: number;
+}>;
+type CollectionAggregateOutput = z.infer<typeof CollectionAggregateOutput>;
+declare const collectionAggregateHandler: CapabilityHandler<CollectionAggregateInput, CollectionAggregateOutput>;
+
+declare const CollectionJoinInput: z.ZodObject<{
+    /** Left-side items array */
+    leftItems: z.ZodArray<z.ZodUnknown, "many">;
+    /** Right-side items array */
+    rightItems: z.ZodArray<z.ZodUnknown, "many">;
+    /** Field path on left items to join on */
+    leftField: z.ZodString;
+    /** Field path on right items to join on */
+    rightField: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    leftItems: unknown[];
+    rightItems: unknown[];
+    leftField: string;
+    rightField: string;
+}, {
+    leftItems: unknown[];
+    rightItems: unknown[];
+    leftField: string;
+    rightField: string;
+}>;
+type CollectionJoinInput = z.infer<typeof CollectionJoinInput>;
+declare const CollectionJoinOutput: z.ZodObject<{
+    /** Merged items where left[leftField] === right[rightField] */
+    items: z.ZodArray<z.ZodObject<{
+        left: z.ZodUnknown;
+        right: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        left?: unknown;
+        right?: unknown;
+    }, {
+        left?: unknown;
+        right?: unknown;
+    }>, "many">;
+    /** Count of matched items */
+    count: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    count: number;
+    items: {
+        left?: unknown;
+        right?: unknown;
+    }[];
+}, {
+    count: number;
+    items: {
+        left?: unknown;
+        right?: unknown;
+    }[];
+}>;
+type CollectionJoinOutput = z.infer<typeof CollectionJoinOutput>;
+/**
+ * Join two arrays on matching field values for cross-domain data correlation.
+ *
+ * Pure transform (no I/O, trivially auditable).
+ * Uses hash-based lookup for O(n+m) performance instead of O(n*m).
+ *
+ * @example
+ * join(patients, generators, 'currentFacility', 'facilityId')
+ * → [{ left: patient, right: generator }, ...]
+ */
+declare const collectionJoinHandler: CapabilityHandler<CollectionJoinInput, CollectionJoinOutput>;
+
+declare const DateShiftInput: z.ZodObject<{
+    date: z.ZodString;
+    duration: z.ZodString;
+    direction: z.ZodEnum<["add", "subtract"]>;
+}, "strip", z.ZodTypeAny, {
+    date: string;
+    direction: "add" | "subtract";
+    duration: string;
+}, {
+    date: string;
+    direction: "add" | "subtract";
+    duration: string;
+}>;
+type DateShiftInput = z.infer<typeof DateShiftInput>;
+declare const DateShiftOutput: z.ZodObject<{
+    result: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    result: string;
+}, {
+    result: string;
+}>;
+type DateShiftOutput = z.infer<typeof DateShiftOutput>;
+declare const dateShiftHandler: CapabilityHandler<DateShiftInput, DateShiftOutput>;
+
+declare const EventsFilterInput: z.ZodObject<{
+    /** The event payload to evaluate */
+    event: z.ZodUnknown;
+    /** Typed predicate conditions -- all must pass for the event to pass through */
+    conditions: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodString;
+        value: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        op: string;
+        value?: unknown;
+    }, {
+        field: string;
+        op: string;
+        value?: unknown;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    conditions: {
+        field: string;
+        op: string;
+        value?: unknown;
+    }[];
+    event?: unknown;
+}, {
+    conditions: {
+        field: string;
+        op: string;
+        value?: unknown;
+    }[];
+    event?: unknown;
+}>;
+type EventsFilterInput = z.infer<typeof EventsFilterInput>;
+declare const EventsFilterOutput: z.ZodObject<{
+    /** The event if it passed all conditions, or null if filtered out */
+    event: z.ZodNullable<z.ZodUnknown>;
+    /** Whether the event passed all conditions */
+    passed: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    passed: boolean;
+    event?: unknown;
+}, {
+    passed: boolean;
+    event?: unknown;
+}>;
+type EventsFilterOutput = z.infer<typeof EventsFilterOutput>;
+declare const eventsFilterHandler: CapabilityHandler<EventsFilterInput, EventsFilterOutput>;
+
+/**
+ * Register all built-in transform capabilities with the given registry.
+ */
+declare function registerTransforms(registry: CapabilityRegistry): void;
+
+declare const ServiceCallInput: z.ZodObject<{
+    /** The URL to call (raw HTTP fallback — always required so the effect works without a provider) */
+    url: z.ZodString;
+    /** HTTP method */
+    method: z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE"]>;
+    /**
+     * Data source ID for provider delegation (e.g. "equipment-api").
+     * When provided alongside `operation`, and a DataSourceProvider in context can resolve
+     * this source, the call is delegated to the provider instead of raw HTTP.
+     * Falls back to `url`+`method` when no provider is installed or source is not known.
+     */
+    source: z.ZodOptional<z.ZodString>;
+    /**
+     * Operation name for provider delegation (e.g. "listUnits").
+     * Must be provided together with `source` to trigger provider delegation.
+     */
+    operation: z.ZodOptional<z.ZodString>;
+    /** Request headers */
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Request body (for POST/PUT/PATCH, or provider operation params when delegating) */
+    body: z.ZodOptional<z.ZodUnknown>;
+    /** Expected response type (defaults to 'json') */
+    responseType: z.ZodOptional<z.ZodEnum<["json", "text"]>>;
+    /** Timeout in milliseconds (defaults to 30000) */
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    operation?: string | undefined;
+    source?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    body?: unknown;
+    responseType?: "json" | "text" | undefined;
+    timeout?: number | undefined;
+}, {
+    url: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    operation?: string | undefined;
+    source?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    body?: unknown;
+    responseType?: "json" | "text" | undefined;
+    timeout?: number | undefined;
+}>;
+type ServiceCallInput = z.infer<typeof ServiceCallInput>;
+declare const ServiceCallOutput: z.ZodObject<{
+    /** HTTP status code */
+    status: z.ZodNumber;
+    /** Response headers */
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    /** Response body */
+    body: z.ZodUnknown;
+    /** Whether the call was successful (2xx status) */
+    ok: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    status: number;
+    headers: Record<string, string>;
+    ok: boolean;
+    body?: unknown;
+}, {
+    status: number;
+    headers: Record<string, string>;
+    ok: boolean;
+    body?: unknown;
+}>;
+type ServiceCallOutput = z.infer<typeof ServiceCallOutput>;
+/**
+ * Service call effect -- invokes an HTTP endpoint.
+ *
+ * This is the raw-HTTP escape hatch and also the provider-delegation bridge:
+ * - When `source` + `operation` are given and a DataSourceProvider in context
+ *   knows about the source, execution is delegated to the provider (typed, validated).
+ * - Otherwise (no provider, or source not resolvable) it falls back to raw Fetch.
+ *
+ * This is an Effect capability: it touches the outside world.
+ * Required permissions are declared in the definition and used
+ * for least-privilege derivation at compile time.
+ *
+ * Uses the standard Fetch API -- works in Node.js 22+, Lambda, and edge.
+ */
+declare const serviceCallHandler: CapabilityHandler<ServiceCallInput, ServiceCallOutput>;
+
+declare const EventsPublishInput: z.ZodObject<{
+    /** Topic to publish to (e.g. "bus:equipment-status" or "equipment-status") */
+    topic: z.ZodString;
+    /** Message payload to publish */
+    payload: z.ZodUnknown;
+    /** Optional metadata to include with the message */
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Logical source identifier */
+        source: z.ZodOptional<z.ZodString>;
+        /** Correlation ID for request-scoped grouping */
+        correlationId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source?: string | undefined;
+        correlationId?: string | undefined;
+    }, {
+        source?: string | undefined;
+        correlationId?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    topic: string;
+    payload?: unknown;
+    metadata?: {
+        source?: string | undefined;
+        correlationId?: string | undefined;
+    } | undefined;
+}, {
+    topic: string;
+    payload?: unknown;
+    metadata?: {
+        source?: string | undefined;
+        correlationId?: string | undefined;
+    } | undefined;
+}>;
+type EventsPublishInput = z.infer<typeof EventsPublishInput>;
+declare const EventsPublishOutput: z.ZodObject<{
+    /** Provider-assigned message ID */
+    messageId: z.ZodString;
+    /** Topic the message was published to (without bus: prefix) */
+    topic: z.ZodString;
+    /** Whether publishing succeeded */
+    success: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    topic: string;
+    messageId: string;
+    success: boolean;
+}, {
+    topic: string;
+    messageId: string;
+    success: boolean;
+}>;
+type EventsPublishOutput = z.infer<typeof EventsPublishOutput>;
+/**
+ * Strip the "bus:" prefix from a topic if present.
+ * YAML writes "bus:equipment-status"; the provider receives "equipment-status".
+ */
+declare function stripBusPrefix(topic: string): string;
+/**
+ * events.publish effect — publishes a message to a message bus topic.
+ *
+ * This is an Effect capability: it touches the outside world.
+ * The MessageBusProvider is injected via CapabilityContext.messageBus.
+ *
+ * Declares required permissions for least-privilege derivation:
+ *   { resource: 'bus:<topic>', action: 'publish' }
+ */
+declare const eventsPublishHandler: CapabilityHandler<EventsPublishInput, EventsPublishOutput>;
+/**
+ * events.publish capability definition.
+ *
+ * This is an Effect — it declares requiredPermissions.
+ * At compile time, the permission derivation system reads these to generate
+ * least-privilege IAM policies / RBAC manifests.
+ *
+ * Permission: { resource: 'bus:*', action: 'publish' }
+ * The compiler can narrow the wildcard to specific topics by inspecting the
+ * flow's step parameters (e.g. bus:equipment-status).
+ */
+declare const eventsPublishDefinition: {
+    kind: "effect";
+    name: string;
+    description: string;
+    inputSchema: string;
+    outputSchema: string;
+    requiredPermissions: {
+        resource: string;
+        action: string;
+    }[];
+};
+
+/**
+ * Supported notification channels.
+ * The set is closed — adding a new channel is a deliberate, audited act.
+ */
+declare const NotificationChannel: z.ZodEnum<["email", "sms", "push", "in-app"]>;
+type NotificationChannel = z.infer<typeof NotificationChannel>;
+declare const NotifyUserInput: z.ZodObject<{
+    /** Recipient user identifier — the provider resolves this to a delivery address */
+    recipient: z.ZodString;
+    /** Delivery channel */
+    channel: z.ZodEnum<["email", "sms", "push", "in-app"]>;
+    /** Template name for the notification content */
+    template: z.ZodString;
+    /** Typed payload for template interpolation */
+    payload: z.ZodUnknown;
+    /** Optional subject line (for email, push) */
+    subject: z.ZodOptional<z.ZodString>;
+    /** Optional metadata to include with the notification */
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Logical source identifier */
+        source: z.ZodOptional<z.ZodString>;
+        /** Correlation ID for request-scoped grouping */
+        correlationId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source?: string | undefined;
+        correlationId?: string | undefined;
+    }, {
+        source?: string | undefined;
+        correlationId?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    template: string;
+    recipient: string;
+    channel: "email" | "sms" | "push" | "in-app";
+    payload?: unknown;
+    metadata?: {
+        source?: string | undefined;
+        correlationId?: string | undefined;
+    } | undefined;
+    subject?: string | undefined;
+}, {
+    template: string;
+    recipient: string;
+    channel: "email" | "sms" | "push" | "in-app";
+    payload?: unknown;
+    metadata?: {
+        source?: string | undefined;
+        correlationId?: string | undefined;
+    } | undefined;
+    subject?: string | undefined;
+}>;
+type NotifyUserInput = z.infer<typeof NotifyUserInput>;
+declare const NotifyUserOutput: z.ZodObject<{
+    /** Provider-assigned notification ID */
+    notificationId: z.ZodString;
+    /** Channel the notification was sent through */
+    channel: z.ZodString;
+    /** Whether sending succeeded */
+    success: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    channel: string;
+    notificationId: string;
+}, {
+    success: boolean;
+    channel: string;
+    notificationId: string;
+}>;
+type NotifyUserOutput = z.infer<typeof NotifyUserOutput>;
+/**
+ * notify.user effect — sends a notification to a user via a configured channel.
+ *
+ * This is an Effect capability: it touches the outside world.
+ * The NotificationProvider is injected via CapabilityContext.notificationProvider.
+ *
+ * Multi-channel (email, SMS, push, in-app) via a NotificationProvider adapter.
+ * Template-based with typed payload — the provider resolves the template name
+ * to actual content and interpolates the payload.
+ *
+ * Declares required permissions for least-privilege derivation:
+ *   { resource: 'notification:<channel>', action: 'send' }
+ */
+declare const notifyUserHandler: CapabilityHandler<NotifyUserInput, NotifyUserOutput>;
+/**
+ * notify.user capability definition.
+ *
+ * This is an Effect — it declares requiredPermissions.
+ * At compile time, the permission derivation system reads these to generate
+ * least-privilege IAM policies / RBAC manifests.
+ *
+ * Permission: { resource: 'notification:*', action: 'send' }
+ * The compiler can narrow the wildcard to specific channels by inspecting the
+ * flow's step parameters (e.g. notification:email).
+ */
+declare const notifyUserDefinition: {
+    kind: "effect";
+    name: string;
+    description: string;
+    inputSchema: string;
+    outputSchema: string;
+    requiredPermissions: {
+        resource: string;
+        action: string;
+    }[];
+};
+
+/**
+ * Register all effect capabilities.
+ * Effects touch the outside world and declare required permissions.
+ */
+declare function registerEffects(registry: CapabilityRegistry): void;
+
+/**
+ * Register all built-in capabilities (transforms + effects).
+ */
+declare function registerAllCapabilities(registry: CapabilityRegistry): void;
+
+export { type CapabilityContext, type CapabilityHandler, type CapabilityLogger, type CapabilityMessageBus, type CapabilityNotificationProvider, CapabilityRegistry, CollectionAggregateInput, CollectionAggregateOutput, CollectionFilterInput, CollectionFilterOutput, CollectionJoinInput, CollectionJoinOutput, DateShiftInput, DateShiftOutput, EventsFilterInput, EventsFilterOutput, EventsPublishInput, EventsPublishOutput, NotificationChannel, NotifyUserInput, NotifyUserOutput, type RegisteredCapability, ServiceCallInput, ServiceCallOutput, TextFormatInput, TextFormatOutput, UnitsConvertInput, UnitsConvertOutput, collectionAggregateHandler, collectionFilterHandler, collectionJoinHandler, dateShiftHandler, defaultRegistry, evaluatePredicate, eventsFilterHandler, eventsPublishDefinition, eventsPublishHandler, notifyUserDefinition, notifyUserHandler, registerAllCapabilities, registerEffects, registerTransforms, serviceCallHandler, stripBusPrefix, textFormatHandler, unitsConvertHandler };