@stackwright-services/runtime 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,985 @@
+import { CapabilityContext } from '@stackwright-services/capabilities';
+import { HttpTrigger, EventTrigger, ScheduleTrigger, QueueTrigger } from '@stackwright-services/types';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { SNSClient } from '@aws-sdk/client-sns';
+import { SQSClient } from '@aws-sdk/client-sqs';
+export { CapabilityDescriptor, DataSourceDescriptorEntry, PrebuildRegistration, TriggerTypeDescriptor, registerServices } from './prebuild/index.mjs';
+
+/**
+ * Options for creating an HTTP trigger runtime.
+ */
+interface HttpTriggerOptions {
+    /** The HTTP trigger configuration from the flow */
+    trigger: HttpTrigger;
+    /** Flow handler function */
+    handler: (input: unknown, context: CapabilityContext) => Promise<unknown>;
+    /** Optional input validation schema */
+    inputSchema?: z.ZodType;
+    /** Optional output validation schema */
+    outputSchema?: z.ZodType;
+}
+/**
+ * Typed error response for consistent error handling.
+ */
+interface ServiceError {
+    error: string;
+    code: string;
+    details?: unknown;
+}
+/**
+ * Create a Hono app for an HTTP trigger.
+ *
+ * This is the runtime entry point for HTTP-triggered flows.
+ * The same code works on:
+ * - Node.js (via @hono/node-server)
+ * - AWS Lambda (via Lambda Web Adapter)
+ * - Edge runtimes (Cloudflare Workers, Deno Deploy)
+ */
+declare function createHttpTrigger(options: HttpTriggerOptions): Hono;
+
+/**
+ * Message payload carried through the bus.
+ * The payload is typed at the flow level; here it is `unknown` because
+ * the provider is transport-agnostic.
+ */
+interface BusMessage {
+    /** Message payload (typed at the flow level via Zod schemas) */
+    payload: unknown;
+    /** W3C Trace Context headers for distributed trace propagation */
+    traceContext?: Record<string, string>;
+    /** Message metadata */
+    metadata?: MessageMetadata;
+}
+interface MessageMetadata {
+    /** ISO 8601 timestamp of when the message was produced */
+    timestamp?: string;
+    /** Logical source identifier (e.g. the flow that published) */
+    source?: string;
+    /** Correlation ID for request-scoped grouping */
+    correlationId?: string;
+    /** Unique message ID (assigned by the provider if not supplied) */
+    messageId?: string;
+}
+interface PublishResult {
+    /** Provider-assigned message ID */
+    messageId: string;
+    /** Topic the message was published to */
+    topic: string;
+    /** Whether publishing succeeded */
+    success: boolean;
+}
+/**
+ * Handler function invoked when a message arrives on a subscribed topic.
+ */
+type MessageHandler = (message: BusMessage) => Promise<void>;
+/**
+ * A live subscription to a topic. Call cancel() to stop receiving messages.
+ */
+interface Subscription {
+    /** Unique subscription ID */
+    id: string;
+    /** The topic this subscription is listening on */
+    topic: string;
+    /** Cancel this subscription — stops message delivery */
+    cancel(): Promise<void>;
+}
+/**
+ * MessageBusProvider adapter interface.
+ *
+ * Same adapter pattern as ObservabilityProvider:
+ * - Interface defined here
+ * - InMemoryMessageBusProvider for testing (in-memory delivery)
+ * - Concrete adapters (SQS/SNS, Kafka, etc.) bind at the deployment target
+ * - Factory selects provider based on environment configuration
+ *
+ * Topic format: the YAML writes `bus:<topic-name>` (e.g. `bus:equipment-status`).
+ * The provider receives just the topic name (e.g. `equipment-status`) after the
+ * `bus:` prefix is stripped by the trigger adapter or effect that calls it.
+ *
+ * Concrete bus implementations (SQS, Kafka, NATS) are hidden behind this interface.
+ * A citizen developer's YAML references `bus:equipment-status`; it never knows
+ * whether the underlying transport is SQS in the demo or Kafka in the cluster.
+ */
+interface MessageBusProvider {
+    /** Publish a message to a topic */
+    publish(topic: string, message: BusMessage): Promise<PublishResult>;
+    /** Subscribe to a topic with a handler. Returns a Subscription handle. */
+    subscribe(topic: string, handler: MessageHandler): Promise<Subscription>;
+    /** Unsubscribe — equivalent to calling subscription.cancel() */
+    unsubscribe(subscription: Subscription): Promise<void>;
+}
+
+/**
+ * Trigger adapter interface -- the seam between trigger types and the runtime.
+ * Each trigger type (http, schedule, queue, event) has its own adapter.
+ */
+interface TriggerAdapter {
+    /** Trigger type this adapter handles */
+    readonly type: string;
+    /** Start listening for this trigger */
+    start(): Promise<void>;
+    /** Stop listening */
+    stop(): Promise<void>;
+}
+
+/**
+ * Options for creating an event trigger adapter.
+ */
+interface EventTriggerOptions {
+    /** The event trigger configuration from the flow */
+    trigger: EventTrigger;
+    /** Message bus provider to subscribe through */
+    messageBus: MessageBusProvider;
+    /** Flow handler function invoked for each valid message */
+    handler: (input: unknown, context: CapabilityContext) => Promise<unknown>;
+    /** Optional Zod schema for input validation — invalid messages are logged and skipped */
+    inputSchema?: z.ZodType;
+}
+/**
+ * EventTriggerAdapter — subscribes to a MessageBusProvider topic and routes
+ * incoming messages through the compiled flow handler.
+ *
+ * Bus consumers must never crash: handler errors are logged, not rethrown.
+ * Validation failures are logged as warnings and the message is skipped.
+ */
+declare class EventTriggerAdapter implements TriggerAdapter {
+    readonly type = "event";
+    readonly topic: string;
+    private readonly messageBus;
+    private readonly handler;
+    private readonly inputSchema;
+    private subscription;
+    constructor(options: EventTriggerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleMessage;
+}
+
+/**
+ * Options for creating a schedule trigger adapter.
+ */
+interface ScheduleTriggerOptions {
+    /** The schedule trigger configuration from the flow */
+    trigger: ScheduleTrigger;
+    /** Flow handler function invoked on each tick */
+    handler: (input: unknown, context: CapabilityContext) => Promise<unknown>;
+    /** Optional Zod schema for input validation */
+    inputSchema?: z.ZodType;
+    /**
+     * Override interval in milliseconds for local dev / testing.
+     * When not provided, defaults to 60_000ms and logs a warning that
+     * cron parsing is not built-in. In production, scheduling is handled
+     * by infrastructure (EventBridge, CronJob on K8s, etc.).
+     */
+    intervalMs?: number;
+}
+/**
+ * ScheduleTriggerAdapter — local-dev / test scheduler that fires the flow
+ * handler on a fixed interval.
+ *
+ * NOT a production cron implementation. In production the cron expression
+ * is consumed by infrastructure (EventBridge rules, K8s CronJobs, etc.)
+ * and this adapter is not used.
+ *
+ * Handler errors are caught and logged — the scheduler never crashes.
+ */
+declare class ScheduleTriggerAdapter implements TriggerAdapter {
+    readonly type = "schedule";
+    readonly cron: string;
+    private readonly handler;
+    private readonly inputSchema;
+    private readonly intervalMs;
+    private timer;
+    constructor(options: ScheduleTriggerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private tick;
+}
+
+/**
+ * Options for creating a queue trigger adapter.
+ */
+interface QueueTriggerOptions {
+    /** The queue trigger configuration from the flow */
+    trigger: QueueTrigger;
+    /** Message bus provider to subscribe through */
+    messageBus: MessageBusProvider;
+    /** Flow handler function invoked for each valid message */
+    handler: (input: unknown, context: CapabilityContext) => Promise<unknown>;
+    /** Optional Zod schema for input validation — invalid messages are logged and skipped */
+    inputSchema?: z.ZodType;
+}
+/**
+ * QueueTriggerAdapter — subscribes to a MessageBusProvider topic and routes
+ * incoming messages through the compiled flow handler.
+ *
+ * Semantically represents point-to-point delivery (single consumer), unlike
+ * the fan-out semantics of EventTriggerAdapter. At the runtime adapter level
+ * both use messageBus.subscribe() — the distinction lives in the concrete
+ * bus implementation (SQS vs SNS+SQS, competing consumers vs broadcast).
+ *
+ * Bus consumers must never crash: handler errors are logged, not rethrown.
+ * Validation failures are logged as warnings and the message is skipped.
+ */
+declare class QueueTriggerAdapter implements TriggerAdapter {
+    readonly type = "queue";
+    readonly queueName: string;
+    private readonly messageBus;
+    private readonly handler;
+    private readonly inputSchema;
+    private subscription;
+    constructor(options: QueueTriggerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleMessage;
+}
+
+/**
+ * ObservabilityProvider interface -- what the compiled flow code calls.
+ * The compiler generates code that calls these methods.
+ * The runtime injects either OTel or no-op based on configuration.
+ */
+interface ObservabilityProvider {
+    /** Start a span for a capability invocation */
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>): SpanHandle;
+    /** Record a metric (counter, histogram, etc.) */
+    recordMetric(name: string, value: number, tags?: Record<string, string>): void;
+}
+interface SpanHandle {
+    /** Set an attribute on the span */
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Mark the span as errored */
+    setError(error: Error): void;
+    /** End the span (record duration) */
+    end(): void;
+}
+
+/**
+ * No-op observability provider -- zero runtime cost.
+ * Used when OTel is not configured (the default).
+ * All methods are no-ops that return immediately.
+ */
+declare class NoopObservabilityProvider implements ObservabilityProvider {
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>): SpanHandle;
+    recordMetric(name: string, value: number, tags?: Record<string, string>): void;
+}
+/** Singleton no-op provider */
+declare const noopProvider: NoopObservabilityProvider;
+
+/**
+ * OpenTelemetry-compatible observability provider.
+ *
+ * In Phase 1, this uses structured console logging with span semantics.
+ * In Phase 2+, this wraps @opentelemetry/api (trace + metrics).
+ *
+ * The interface is stable -- upgrading to real OTel is a drop-in replacement.
+ */
+declare class OtelObservabilityProvider implements ObservabilityProvider {
+    private readonly serviceName;
+    constructor(serviceName?: string);
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>): SpanHandle;
+    recordMetric(name: string, value: number, tags?: Record<string, string>): void;
+}
+
+/**
+ * Create an observability provider based on environment configuration.
+ *
+ * - OTEL_ENABLED=true (or "1") -> OtelObservabilityProvider
+ * - Otherwise -> NoopObservabilityProvider (zero cost)
+ *
+ * The provider is injected into compiled flow code, not imported.
+ * This means zero runtime overhead when observability is disabled.
+ */
+declare function createObservabilityProvider(options?: {
+    serviceName?: string;
+}): ObservabilityProvider;
+
+/**
+ * AuditProvider interface -- records structured audit events for capability invocations.
+ *
+ * Audit events capture WHAT happened (capability, inputs, outputs, status)
+ * while ObservabilityProvider captures HOW it performed (latency, spans, metrics).
+ *
+ * These are two views of one stream -- same invocation, different concerns.
+ */
+/** Structured audit event -- one per capability invocation */
+interface AuditEvent {
+    /** Event type discriminator */
+    type: 'capability_invocation' | 'workflow_transition' | 'flow_start' | 'flow_end';
+    /** W3C trace ID (propagated from request context) */
+    traceId: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Flow or workflow ID */
+    flowId: string;
+    /** Step name within the flow */
+    stepName: string;
+    /** Capability that was invoked (e.g. 'collection.filter') */
+    capabilityName: string;
+    /** Truncated SHA-256 of serialized input (first 16 hex chars) */
+    inputHash: string;
+    /** Truncated SHA-256 of serialized output (first 16 hex chars) */
+    outputHash: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Success or failure */
+    status: 'success' | 'error';
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/** Provider interface -- implementations decide WHERE events go */
+interface AuditProvider {
+    /** Record a single audit event */
+    record(event: AuditEvent): void;
+    /** Flush any buffered events (for graceful shutdown) */
+    flush(): Promise<void>;
+}
+
+/** No-op audit provider -- zero runtime cost when auditing is disabled */
+declare class NoopAuditProvider implements AuditProvider {
+    record(_event: AuditEvent): void;
+    flush(): Promise<void>;
+}
+/** Singleton no-op audit provider */
+declare const noopAuditProvider: NoopAuditProvider;
+
+/**
+ * Console audit provider -- writes events to stderr as JSON Lines.
+ *
+ * Works in Lambda (stderr -> CloudWatch), containers (stderr -> log collector),
+ * and local dev (stderr -> terminal).
+ *
+ * Uses stderr to avoid mixing with application stdout.
+ */
+declare class ConsoleAuditProvider implements AuditProvider {
+    record(event: AuditEvent): void;
+    flush(): Promise<void>;
+}
+
+/**
+ * Create an audit provider based on environment configuration.
+ *
+ * - STACKWRIGHT_AUDIT=true (or "1") -> ConsoleAuditProvider (stderr JSON Lines)
+ * - Otherwise -> NoopAuditProvider (zero cost)
+ *
+ * Defaults to OFF in production, can be enabled with env var.
+ */
+declare function createAuditProvider(): AuditProvider;
+
+/**
+ * Compute a truncated SHA-256 hash of a value.
+ *
+ * Used for audit events -- captures enough to detect "did the input/output change?"
+ * without storing full payloads (which may be large or contain PII).
+ *
+ * Returns first 16 hex characters of SHA-256.
+ * Deterministic: same input always produces same hash.
+ */
+declare function auditHash(value: unknown): string;
+
+/**
+ * In-memory MessageBusProvider — delivers messages locally within the process.
+ *
+ * Used for:
+ * - Unit and integration testing (no infrastructure required)
+ * - Local development (stackwright-services dev mode)
+ * - Default when no external bus is configured
+ *
+ * Messages published to a topic are delivered synchronously to all
+ * subscribed handlers for that topic.
+ */
+declare class InMemoryMessageBusProvider implements MessageBusProvider {
+    private subscriptions;
+    private nextId;
+    publish(topic: string, message: BusMessage): Promise<PublishResult>;
+    subscribe(topic: string, handler: MessageHandler): Promise<Subscription>;
+    unsubscribe(subscription: Subscription): Promise<void>;
+    /** Helper for testing: get count of active subscriptions for a topic */
+    getSubscriptionCount(topic: string): number;
+    /** Helper for testing: clear all subscriptions */
+    clear(): void;
+}
+/** Singleton in-memory provider for convenience */
+declare const inMemoryBusProvider: InMemoryMessageBusProvider;
+
+/**
+ * SQS/SNS MessageBusProvider — the first concrete adapter.
+ *
+ * Architecture:
+ * - PUBLISH: Uses SNS Publish to deliver messages to a topic ARN.
+ * - SUBSCRIBE: Uses SQS long-polling (ReceiveMessage) to consume from a queue URL.
+ *
+ * Topic/queue resolution:
+ * - Logical topic name → SNS Topic ARN via config map or env var:
+ *   BUS_TOPIC_{UPPER_SNAKE_NAME}_ARN (e.g. BUS_TOPIC_EQUIPMENT_STATUS_ARN)
+ * - Logical queue name → SQS Queue URL via config map or env var:
+ *   BUS_QUEUE_{UPPER_SNAKE_NAME}_URL (e.g. BUS_QUEUE_EQUIPMENT_STATUS_URL)
+ *
+ * Trace propagation:
+ * - traceContext serialized as SNS/SQS MessageAttributes (StringValue)
+ * - metadata fields (timestamp, source, correlationId) also as MessageAttributes
+ *
+ * Graceful shutdown:
+ * - Each subscription has a polling loop with an `active` flag
+ * - stop()/unsubscribe() sets active=false, polling loop exits after current
+ *   ReceiveMessage returns
+ *
+ * AWS credentials:
+ * - Uses standard AWS SDK v3 credential chain (env vars, instance profile, etc.)
+ * - NO credential handling in this adapter
+ *
+ * Design note: This is a thin wrapper. No retry logic beyond SDK defaults,
+ * no DLQ support, no batch processing. Production hardening is a separate bead.
+ */
+
+interface SqsSnsConfig {
+    /** AWS region (defaults to AWS_REGION env var or 'us-east-1') */
+    region?: string;
+    /** SNS Topic ARN mapping: logical name → ARN. Overrides env vars. */
+    topicArns?: Record<string, string>;
+    /** SQS Queue URL mapping: logical name → URL. Overrides env vars. */
+    queueUrls?: Record<string, string>;
+    /** SQS long-poll wait time in seconds (default: 20, max for long-polling) */
+    waitTimeSeconds?: number;
+    /** Max messages per ReceiveMessage call (default: 10) */
+    maxMessages?: number;
+    /**
+     * Minimum delay between poll cycles in ms (default: 100).
+     * Prevents tight-spinning when waitTimeSeconds is low or the queue is
+     * empty and the SDK resolves instantly. In production with
+     * waitTimeSeconds=20 the 100ms gap is negligible.
+     */
+    pollIntervalMs?: number;
+    /** Optional SNS client (for testing/DI) */
+    snsClient?: SNSClient;
+    /** Optional SQS client (for testing/DI) */
+    sqsClient?: SQSClient;
+}
+declare class SqsSnsMessageBusProvider implements MessageBusProvider {
+    private readonly snsClient;
+    private readonly sqsClient;
+    private readonly topicArns;
+    private readonly queueUrls;
+    private readonly waitTimeSeconds;
+    private readonly maxMessages;
+    private readonly pollIntervalMs;
+    private readonly pollingStates;
+    constructor(config?: SqsSnsConfig);
+    publish(topic: string, message: BusMessage): Promise<PublishResult>;
+    subscribe(topic: string, handler: MessageHandler): Promise<Subscription>;
+    unsubscribe(subscription: Subscription): Promise<void>;
+    private resolveTopicArn;
+    private resolveQueueUrl;
+    private buildSnsAttributes;
+    private poll;
+    private parseSqsMessage;
+    private extractTraceContext;
+    private extractMetadata;
+}
+
+/**
+ * Create a MessageBusProvider based on environment configuration.
+ *
+ * - MESSAGE_BUS_PROVIDER=memory (or unset) -> InMemoryMessageBusProvider
+ * - MESSAGE_BUS_PROVIDER=sqs -> SQS/SNS adapter
+ *
+ * Same pattern as createObservabilityProvider().
+ */
+declare function createMessageBusProvider(options?: {
+    /** Override the provider type (defaults to env var) */
+    provider?: string;
+    /** Provider-specific config (e.g. SqsSnsConfig for 'sqs') */
+    config?: Record<string, unknown>;
+}): MessageBusProvider;
+
+/**
+ * Supported notification channels.
+ * The set is closed — adding a new channel is a deliberate, audited act.
+ */
+type NotificationChannel = 'email' | 'sms' | 'push' | 'in-app';
+/**
+ * Notification payload carried to the provider.
+ * The payload is typed at the flow level; here it is `unknown` because
+ * the provider is transport-agnostic.
+ */
+interface NotificationMessage {
+    /** Recipient user identifier — the provider resolves this to a delivery address */
+    recipient: string;
+    /** Delivery channel */
+    channel: NotificationChannel;
+    /** Template name for the notification content */
+    template: string;
+    /** Typed payload for template interpolation */
+    payload: unknown;
+    /** Optional subject line (for email, push) */
+    subject?: string;
+    /** W3C Trace Context headers for distributed trace propagation */
+    traceContext?: Record<string, string>;
+    /** Notification metadata */
+    metadata?: NotificationMetadata;
+}
+interface NotificationMetadata {
+    /** ISO 8601 timestamp of when the notification was produced */
+    timestamp?: string;
+    /** Logical source identifier (e.g. the flow that triggered the notification) */
+    source?: string;
+    /** Correlation ID for request-scoped grouping */
+    correlationId?: string;
+}
+interface SendResult {
+    /** Provider-assigned notification ID */
+    notificationId: string;
+    /** Channel the notification was sent through */
+    channel: string;
+    /** Whether sending succeeded */
+    success: boolean;
+}
+/**
+ * NotificationProvider adapter interface.
+ *
+ * Same adapter pattern as MessageBusProvider and ObservabilityProvider:
+ * - Interface defined here
+ * - InMemoryNotificationProvider for testing (records notifications in-memory)
+ * - Concrete adapters (SendGrid, Twilio, FCM, etc.) bind at the deployment target
+ * - Factory selects provider based on environment configuration
+ *
+ * Multi-channel (email, SMS, push, in-app) — the provider resolves the
+ * recipient identifier to an actual delivery address for each channel.
+ *
+ * Template-based — the provider looks up the template name and interpolates
+ * the typed payload. Template management is the provider's concern, not the
+ * capability's.
+ */
+interface NotificationProvider {
+    /** Send a notification to a user */
+    send(notification: NotificationMessage): Promise<SendResult>;
+}
+
+/**
+ * In-memory NotificationProvider — records notifications locally for inspection.
+ *
+ * Used for:
+ * - Unit and integration testing (no infrastructure required)
+ * - Local development (stackwright-services dev mode)
+ * - Default when no external notification service is configured
+ *
+ * Notifications are stored in-memory and can be inspected via helper methods.
+ */
+declare class InMemoryNotificationProvider implements NotificationProvider {
+    private notifications;
+    private nextId;
+    send(notification: NotificationMessage): Promise<SendResult>;
+    /** Helper for testing: get all sent notifications */
+    getSentNotifications(): ReadonlyArray<NotificationMessage & {
+        notificationId: string;
+    }>;
+    /** Helper for testing: get notifications filtered by channel */
+    getByChannel(channel: string): ReadonlyArray<NotificationMessage & {
+        notificationId: string;
+    }>;
+    /** Helper for testing: get notifications filtered by recipient */
+    getByRecipient(recipient: string): ReadonlyArray<NotificationMessage & {
+        notificationId: string;
+    }>;
+    /** Helper for testing: get count of sent notifications */
+    get sentCount(): number;
+    /** Helper for testing: clear all recorded notifications */
+    clear(): void;
+}
+/** Singleton in-memory provider for convenience */
+declare const inMemoryNotificationProvider: InMemoryNotificationProvider;
+
+/**
+ * Create a NotificationProvider based on environment configuration.
+ *
+ * - NOTIFICATION_PROVIDER=memory (or unset) -> InMemoryNotificationProvider
+ * - NOTIFICATION_PROVIDER=sendgrid -> (future: SendGrid adapter)
+ * - NOTIFICATION_PROVIDER=twilio -> (future: Twilio adapter)
+ *
+ * Same pattern as createMessageBusProvider() and createObservabilityProvider().
+ */
+declare function createNotificationProvider(options?: {
+    /** Override the provider type (defaults to env var) */
+    provider?: string;
+}): NotificationProvider;
+
+/**
+ * Claims extracted from an authentication token.
+ */
+interface AuthClaims {
+    /** Subject identifier (user ID) */
+    sub: string;
+    /** Roles assigned to the user */
+    roles: string[];
+    /** Token expiration timestamp (Unix seconds) */
+    exp?: number;
+    /** Additional claims — extensible */
+    [key: string]: unknown;
+}
+/**
+ * Token validation result.
+ */
+interface TokenValidationResult {
+    valid: boolean;
+    claims?: AuthClaims;
+    error?: string;
+}
+/**
+ * AuthProvider adapter interface.
+ *
+ * Same adapter pattern as MessageBusProvider and ObservabilityProvider.
+ * Concrete implementations (OIDC, CAC/PKI) are discovered via IoC
+ * when @stackwright-pro/auth is installed.
+ *
+ * Used by:
+ * - HTTP trigger to validate requests
+ * - Workflow guard_role to gate transitions
+ */
+interface AuthProvider {
+    /** Provider name for logging/diagnostics */
+    readonly name: string;
+    /** Validate a token and return claims if valid */
+    validateToken(token: string): Promise<TokenValidationResult>;
+    /** Extract claims from an already-validated token (fast path) */
+    extractClaims(token: string): Promise<AuthClaims>;
+    /** Check if claims include the required role */
+    checkRole(claims: AuthClaims, role: string): boolean;
+}
+
+/**
+ * No-op AuthProvider — fail-closed default.
+ *
+ * Used when no auth provider is configured:
+ * - validateToken() always returns { valid: false } (reject all tokens)
+ * - extractClaims() throws (no claims without a real provider)
+ * - checkRole() always returns false (deny all role checks)
+ *
+ * This is intentionally fail-closed: if you forget to install a real
+ * auth provider, every auth check fails rather than silently passing.
+ */
+declare class NoopAuthProvider implements AuthProvider {
+    readonly name = "noop";
+    validateToken(token: string): Promise<TokenValidationResult>;
+    extractClaims(token: string): Promise<AuthClaims>;
+    checkRole(claims: AuthClaims, role: string): boolean;
+}
+/** Singleton no-op provider */
+declare const noopAuthProvider: NoopAuthProvider;
+
+type AuthProviderType = 'noop' | 'oidc' | 'cac';
+/**
+ * Create an AuthProvider based on the requested type.
+ *
+ * - 'noop' (or unset) -> NoopAuthProvider (fail-closed default)
+ * - 'oidc' -> Future: lazy require('@stackwright-pro/auth-oidc')
+ * - 'cac' -> Future: lazy require('@stackwright-pro/auth-cac')
+ *
+ * Same pattern as createMessageBusProvider() and createObservabilityProvider().
+ */
+declare function createAuthProvider(type?: AuthProviderType): AuthProvider;
+
+/**
+ * Descriptor for a data source exposed by an installed provider.
+ */
+interface DataSourceDescriptor {
+    /**
+     * Unique source ID. Matches the `source:` YAML reference without the transport prefix.
+     * e.g. "equipment-api" (from `openapi:equipment-api`).
+     */
+    id: string;
+    /** Transport protocol this source is backed by */
+    transport: 'openapi' | 'pulse';
+    /** List of named operations this source supports */
+    operations: string[];
+    /** Human-readable description (optional, from adapter metadata) */
+    description?: string;
+}
+/**
+ * Result returned by a DataSourceProvider execute() call.
+ */
+interface DataSourceResult {
+    /** The raw data returned by the operation */
+    data: unknown;
+    /** Optional provider-level metadata (pagination cursors, rate-limit headers, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * DataSourceProvider adapter interface.
+ *
+ * Same adapter pattern as MessageBusProvider and ObservabilityProvider:
+ * - Interface defined here
+ * - NoopDataSourceProvider for environments where no provider is installed
+ * - Concrete adapters (OpenAPI, Pulse) discovered via IoC at factory time
+ * - Factory selects provider based on installed packages + environment config
+ *
+ * Source reference format: `<transport>:<id>` (e.g. `openapi:equipment-api`, `pulse:fleet-db`).
+ * The provider receives the id and operation after the prefix is stripped by the
+ * capability or trigger that calls it.
+ *
+ * This is the typed, permission-scoped replacement for the raw `service.call` effect.
+ * Citizen YAML references a named source + operation; the provider resolves it to a
+ * typed, Zod-validated client call and the compiler derives least-privilege permissions
+ * from the declared source references.
+ */
+interface DataSourceProvider {
+    /** Provider name for logging/diagnostics */
+    readonly name: string;
+    /**
+     * Enumerate all data sources this provider knows about.
+     * Called at prebuild time to expand the valid `source:` schema surface.
+     */
+    listSources(): DataSourceDescriptor[];
+    /**
+     * 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", "getUnit")
+     * @param params - Operation parameters (typed at the source level)
+     * @returns Typed result wrapped in DataSourceResult
+     * @throws If the source or operation is not known, or if the call fails
+     */
+    execute(source: string, operation: string, params: unknown): Promise<DataSourceResult>;
+}
+
+/**
+ * NoopDataSourceProvider — used when no data source provider is installed.
+ *
+ * listSources() returns an empty array (no sources available to the schema expander).
+ * execute() throws a descriptive error pointing to the correct package to install.
+ *
+ * This is the fail-closed default, consistent with NoopAuthProvider.
+ */
+declare class NoopDataSourceProvider implements DataSourceProvider {
+    readonly name = "noop";
+    listSources(): DataSourceDescriptor[];
+    execute(_source: string, _operation: string, _params: unknown): Promise<DataSourceResult>;
+}
+declare const noopDataSourceProvider: NoopDataSourceProvider;
+
+/**
+ * Create a DataSourceProvider based on installed packages and environment configuration.
+ *
+ * Resolution order (first match wins):
+ * 1. `options.provider` — explicit code-level override
+ * 2. `DATA_SOURCE_PROVIDER` env var — environment-level override
+ * 3. IoC auto-discovery — scans for installed adapter packages via require.resolve()
+ *    a. `@stackwright-pro/openapi/datasource-adapter` (checked first)
+ *    b. `@stackwright-pro/pulse/datasource-adapter`
+ * 4. NoopDataSourceProvider — fail-closed default, throws on execute()
+ *
+ * Same pattern as createMessageBusProvider() and createAuthProvider().
+ *
+ * @example Default (IoC — install the package, nothing else needed)
+ * ```typescript
+ * // With @stackwright-pro/pulse in node_modules:
+ * const provider = createDataSourceProvider();
+ * // → PulseDataSourceProvider (auto-discovered)
+ *
+ * // With nothing installed:
+ * const provider = createDataSourceProvider();
+ * // → NoopDataSourceProvider (execute() will throw)
+ * ```
+ *
+ * @example Explicit override with config (useful in tests and custom setups)
+ * ```typescript
+ * const provider = createDataSourceProvider({
+ *   provider: 'pulse',
+ *   config: {
+ *     sources: [{
+ *       id: 'fleet-db',
+ *       operations: { queryGeneratorStatus: mockHandler },
+ *     }],
+ *   },
+ * });
+ * ```
+ *
+ * @example Environment-level override (force noop in isolated tests)
+ * ```bash
+ * DATA_SOURCE_PROVIDER=noop node my-service.js
+ * DATA_SOURCE_PROVIDER=pulse node my-service.js  # force pulse even if openapi is installed
+ * ```
+ */
+declare function createDataSourceProvider(options?: {
+    /** Override the provider type ('openapi' | 'pulse' | 'noop') */
+    provider?: string;
+    /** Provider-specific config passed through to the adapter */
+    config?: Record<string, unknown>;
+}): DataSourceProvider;
+
+/**
+ * Result of a prebuild-time data source scan.
+ */
+interface DataSourceScanResult {
+    /** All sources discovered across all installed providers */
+    sources: DataSourceDescriptor[];
+    /** Which provider packages were found (for logging/diagnostics) */
+    detectedProviders: string[];
+}
+/**
+ * Scan installed packages at prebuild time to discover available data sources.
+ *
+ * This is called by the compiler and prebuild hook (yo8) to expand the valid
+ * `source:` schema surface. If @stackwright-pro/openapi or @stackwright-pro/pulse
+ * are installed and expose an adapter registry, their sources are enumerated here.
+ *
+ * This is a pure filesystem/module-resolution operation — no network, no side effects.
+ * It is safe to call at build time (no running server required).
+ *
+ * Returns an empty sources array if no providers are installed, which causes the
+ * compiler to emit a warning (not an error) when a `source:` reference is encountered.
+ */
+declare function scanDataSources(): DataSourceScanResult;
+
+/**
+ * A typed operation handler for a single OpenAPI operation.
+ * Receives the caller-supplied params and returns the operation result.
+ * Implementations are typically generated typed client methods.
+ */
+type OpenApiOperationHandler = (params: unknown) => Promise<unknown>;
+/**
+ * Registration entry for a single OpenAPI-backed data source.
+ */
+interface OpenApiSourceRegistration {
+    /** Source ID — matches the id in `source: openapi:<id>` YAML references */
+    id: string;
+    /** Human-readable description (forwarded to DataSourceDescriptor) */
+    description?: string;
+    /** Map of operation name → typed handler function */
+    operations: Record<string, OpenApiOperationHandler>;
+}
+/**
+ * Configuration for OpenApiDataSourceProvider.
+ */
+interface OpenApiAdapterConfig {
+    /** Data sources to register. Each source has a set of named operation handlers. */
+    sources: OpenApiSourceRegistration[];
+}
+/**
+ * OpenApiDataSourceProvider — wraps registered OpenAPI operation handlers as a DataSourceProvider.
+ *
+ * Architecture:
+ * - Callers register named sources at construction time, each with a map of operation handlers.
+ * - `listSources()` returns the full descriptor table for all registered sources.
+ * - `execute(source, operation, params)` dispatches to the registered handler.
+ * - Handlers are typically generated typed OpenAPI client methods (from @stackwright-pro/openapi),
+ *   but any function with the right signature works — useful for testing with mocks.
+ *
+ * Design rationale:
+ * - Same registry pattern as SqsSnsMessageBusProvider (wraps external clients, injectable for testing).
+ * - `@stackwright-pro/openapi` uses this adapter when registering its generated clients; the adapter
+ *   is transport-agnostic and does not hard-import that package.
+ * - The `DataSourceResult.metadata` field carries the raw handler response shape for callers
+ *   that need the full structure beyond `data`.
+ *
+ * Error semantics:
+ * - Unknown source → rejects with a descriptive Error (not throws sync).
+ * - Unknown operation → rejects with a descriptive Error.
+ * - Handler errors propagate as-is (the handler is responsible for shaping them).
+ */
+declare class OpenApiDataSourceProvider implements DataSourceProvider {
+    private readonly config;
+    readonly name = "openapi";
+    private readonly sourcesMap;
+    constructor(config: OpenApiAdapterConfig);
+    listSources(): DataSourceDescriptor[];
+    execute(source: string, operation: string, params: unknown): Promise<DataSourceResult>;
+}
+/**
+ * Factory function — creates an OpenApiDataSourceProvider from config.
+ * This is the entry point called by createDataSourceProvider() and
+ * by @stackwright-pro/openapi's datasource-adapter when installed.
+ */
+declare function createOpenApiDataSourceProvider(config: OpenApiAdapterConfig): DataSourceProvider;
+/**
+ * Prebuild-time source listing — returns an empty array because registered
+ * sources are known only at runtime when handlers are wired.
+ *
+ * @stackwright-pro/openapi's datasource-adapter overrides this with a static
+ * manifest of all generated clients, enabling the compiler to validate
+ * `source: openapi:*` references at build time.
+ */
+declare function listDataSources$1(): DataSourceDescriptor[];
+
+/**
+ * A typed operation handler for a single Pulse operation.
+ * Receives the caller-supplied params and returns the operation result.
+ * Implementations are typically generated typed client methods.
+ */
+type PulseOperationHandler = (params: unknown) => Promise<unknown>;
+/**
+ * Registration entry for a single Pulse-backed data source.
+ */
+interface PulseSourceRegistration {
+    /** Source ID — matches the id in `source: pulse:<id>` YAML references */
+    id: string;
+    /** Human-readable description (forwarded to DataSourceDescriptor) */
+    description?: string;
+    /** Map of operation name → typed handler function */
+    operations: Record<string, PulseOperationHandler>;
+}
+/**
+ * Configuration for PulseDataSourceProvider.
+ */
+interface PulseAdapterConfig {
+    /** Data sources to register. Each source has a set of named operation handlers. */
+    sources: PulseSourceRegistration[];
+}
+/**
+ * PulseDataSourceProvider — wraps registered Pulse operation handlers as a DataSourceProvider.
+ *
+ * Architecture:
+ * - Callers register named sources at construction time, each with a map of operation handlers.
+ * - `listSources()` returns the full descriptor table for all registered sources.
+ * - `execute(source, operation, params)` dispatches to the registered handler.
+ * - Handlers are typically generated typed Pulse client methods (from @stackwright-pro/pulse),
+ *   but any function with the right signature works — useful for testing with mocks.
+ *
+ * Design rationale:
+ * - Same registry pattern as SqsSnsMessageBusProvider (wraps external clients, injectable for testing).
+ * - `@stackwright-pro/pulse` uses this adapter when registering its generated clients; the adapter
+ *   is transport-agnostic and does not hard-import that package.
+ * - The `DataSourceResult.metadata` field carries the raw handler response shape for callers
+ *   that need the full structure beyond `data`.
+ *
+ * Usage example:
+ * ```typescript
+ * const provider = createPulseDataSourceProvider({
+ *   sources: [{
+ *     id: 'fleet-db',
+ *     operations: { queryMetrics: pulseClient.queryMetrics },
+ *   }],
+ * });
+ * // Matches `source: pulse:fleet-db` YAML references
+ * ```
+ *
+ * Error semantics:
+ * - Unknown source → rejects with a descriptive Error (not throws sync).
+ * - Unknown operation → rejects with a descriptive Error.
+ * - Handler errors propagate as-is (the handler is responsible for shaping them).
+ */
+declare class PulseDataSourceProvider implements DataSourceProvider {
+    private readonly config;
+    readonly name = "pulse";
+    private readonly sourcesMap;
+    constructor(config: PulseAdapterConfig);
+    listSources(): DataSourceDescriptor[];
+    execute(source: string, operation: string, params: unknown): Promise<DataSourceResult>;
+}
+/**
+ * Factory function — creates a PulseDataSourceProvider from config.
+ * This is the entry point called by createDataSourceProvider() and
+ * by @stackwright-pro/pulse's datasource-adapter when installed.
+ */
+declare function createPulseDataSourceProvider(config: PulseAdapterConfig): DataSourceProvider;
+/**
+ * Prebuild-time source listing — returns an empty array because registered
+ * sources are known only at runtime when handlers are wired.
+ *
+ * @stackwright-pro/pulse's datasource-adapter overrides this with a static
+ * manifest of all generated clients, enabling the compiler to validate
+ * `source: pulse:*` references at build time.
+ */
+declare function listDataSources(): DataSourceDescriptor[];
+
+export { type AuditEvent, type AuditProvider, type AuthClaims, type AuthProvider, type AuthProviderType, type BusMessage, ConsoleAuditProvider, type DataSourceDescriptor, type DataSourceProvider, type DataSourceResult, type DataSourceScanResult, EventTriggerAdapter, type EventTriggerOptions, type HttpTriggerOptions, InMemoryMessageBusProvider, InMemoryNotificationProvider, type MessageBusProvider, type MessageHandler, type MessageMetadata, NoopAuditProvider, NoopAuthProvider, NoopDataSourceProvider, NoopObservabilityProvider, type NotificationChannel, type NotificationMessage, type NotificationMetadata, type NotificationProvider, type ObservabilityProvider, type OpenApiAdapterConfig, OpenApiDataSourceProvider, type OpenApiOperationHandler, type OpenApiSourceRegistration, OtelObservabilityProvider, type PublishResult, type PulseAdapterConfig, PulseDataSourceProvider, type PulseOperationHandler, type PulseSourceRegistration, QueueTriggerAdapter, type QueueTriggerOptions, ScheduleTriggerAdapter, type ScheduleTriggerOptions, type SendResult, type ServiceError, type SpanHandle, type SqsSnsConfig, SqsSnsMessageBusProvider, type Subscription, type TokenValidationResult, type TriggerAdapter, auditHash, createAuditProvider, createAuthProvider, createDataSourceProvider, createHttpTrigger, createMessageBusProvider, createNotificationProvider, createObservabilityProvider, createOpenApiDataSourceProvider, createPulseDataSourceProvider, inMemoryBusProvider, inMemoryNotificationProvider, listDataSources$1 as listOpenApiDataSources, listDataSources as listPulseDataSources, noopAuditProvider, noopAuthProvider, noopDataSourceProvider, noopProvider, scanDataSources };