@enterstellar-ai/adapters 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,769 @@
+import { AuthAdapter, DataAdapter, ErrorAdapter, AnalyticsAdapter, EnterstellarError } from '@enterstellar-ai/types';
+export { AnalyticsAdapter, AuthAdapter, DataAdapter, ErrorAdapter } from '@enterstellar-ai/types';
+
+/**
+ * @module @enterstellar-ai/adapters/types
+ * @description Module-local configuration types for adapter factories.
+ *
+ * These types define the "input" shape that consumers pass to
+ * `createAuthAdapter()`, `createDataAdapter()`, etc. The actual adapter
+ * interfaces (`AuthAdapter`, `DataAdapter`, `ErrorAdapter`, `AnalyticsAdapter`)
+ * live in `@enterstellar-ai/types/adapters` and are re-exported from the barrel.
+ *
+ * Each config type mirrors its corresponding adapter interface, plus a
+ * mandatory `name` field for identification in error messages and DevTools.
+ *
+ * @see Bible §4.15
+ * @see Design Choices AD1–AD5
+ * @see Design Choice T1 — interfaces for behavior, types for data shapes
+ */
+/**
+ * Configuration for {@link createAuthAdapter}.
+ *
+ * The consumer provides their implementation of each method. The factory
+ * validates the config and wraps each method to catch errors → `EnterstellarError`
+ * per Design Choice AD5.
+ *
+ * @example
+ * ```ts
+ * const auth = createAuthAdapter({
+ *   name: 'supabase-auth',
+ *   getSession: async () => {
+ *     const { data } = await supabase.auth.getSession();
+ *     if (!data.session) return null;
+ *     return { userId: data.session.user.id, roles: ['clinician'] };
+ *   },
+ *   hasRole: async (role) => {
+ *     const session = await supabase.auth.getSession();
+ *     return session.data.session?.user.role === role;
+ *   },
+ *   onAuthChange: (cb) => {
+ *     const { data } = supabase.auth.onAuthStateChange((_event, session) => {
+ *       cb(session ? { userId: session.user.id, roles: ['clinician'] } : null);
+ *     });
+ *     return () => data.subscription.unsubscribe();
+ *   },
+ * });
+ * ```
+ */
+type AuthAdapterConfig = {
+    /**
+     * Human-readable adapter name for error messages and DevTools display.
+     *
+     * @example `'supabase-auth'`, `'clerk-auth'`, `'firebase-auth'`
+     */
+    readonly name: string;
+    /**
+     * Returns the current authentication session, or `null` if unauthenticated.
+     *
+     * @returns Session object with user ID and role list.
+     */
+    readonly getSession: () => Promise<{
+        userId: string;
+        roles: string[];
+    } | null>;
+    /**
+     * Checks whether the current user has a specific role.
+     * Essential for RBAC — clinical vs. admin zone visibility.
+     *
+     * @param role - The role to check (e.g., `'clinician'`, `'admin'`).
+     * @returns `true` if the user has the specified role.
+     */
+    readonly hasRole: (role: string) => Promise<boolean>;
+    /**
+     * Subscribes to authentication state changes.
+     *
+     * Essential for reactive auth gating — zones re-evaluate visibility
+     * when sessions expire or roles change.
+     *
+     * @param callback - Called when auth state changes. Receives the new
+     *   session object, or `null` if the user became unauthenticated.
+     * @returns An unsubscribe function (synchronous).
+     */
+    readonly onAuthChange: (callback: (session: {
+        userId: string;
+        roles: string[];
+    } | null) => void) => () => void;
+};
+/**
+ * Configuration for {@link createDataAdapter}.
+ *
+ * Resolves abstract data source names (e.g., `'patients.vitals'`) to actual
+ * data using convention-based dot-notation resolution (AD3).
+ *
+ * @example
+ * ```ts
+ * const data = createDataAdapter({
+ *   name: 'supabase-data',
+ *   query: async (resource, params) => {
+ *     const { data } = await supabase.from(resource).select('*').match(params ?? {});
+ *     return data ?? [];
+ *   },
+ *   mutate: async (resource, action, payload) => {
+ *     if (action === 'create') {
+ *       const { data } = await supabase.from(resource).insert(payload).select().single();
+ *       return data;
+ *     }
+ *     return null;
+ *   },
+ *   subscribe: (resource, callback) => {
+ *     const channel = supabase.channel(resource)
+ *       .on('postgres_changes', { event: '*', schema: 'public', table: resource },
+ *         () => { void query(resource).then(callback); })
+ *       .subscribe();
+ *     return () => { void supabase.removeChannel(channel); };
+ *   },
+ * });
+ * ```
+ */
+type DataAdapterConfig = {
+    /**
+     * Human-readable adapter name for error messages and DevTools display.
+     *
+     * @example `'supabase-data'`, `'firebase-data'`, `'prisma-data'`
+     */
+    readonly name: string;
+    /**
+     * Queries a resource by name with optional parameters.
+     *
+     * @param resource - The resource/table/collection to query (dot-notation per AD3).
+     * @param params - Optional query parameters (filters, pagination, sorting).
+     * @returns Array of records matching the query.
+     */
+    readonly query: (resource: string, params?: Readonly<Record<string, unknown>>) => Promise<readonly Record<string, unknown>[]>;
+    /**
+     * Performs a mutation (create, update, delete) on a resource.
+     *
+     * @param resource - The resource to mutate.
+     * @param action - The mutation type: `'create'`, `'update'`, or `'delete'`.
+     * @param data - The mutation payload.
+     * @returns The mutated record, or `null` for deletes.
+     */
+    readonly mutate: (resource: string, action: 'create' | 'update' | 'delete', data: Readonly<Record<string, unknown>>) => Promise<Record<string, unknown> | null>;
+    /**
+     * Subscribes to real-time changes on a resource.
+     * Essential for live data updates in Enterstellar zones (AD4 — realtime at v1).
+     *
+     * @param resource - The resource to subscribe to.
+     * @param callback - Called when the resource changes.
+     * @returns An unsubscribe function (synchronous).
+     */
+    readonly subscribe: (resource: string, callback: (data: readonly Record<string, unknown>[]) => void) => () => void;
+};
+/**
+ * Configuration for {@link createErrorAdapter}.
+ *
+ * Implementations provide retry logic, error reporting, and PII sanitization.
+ * All methods are async per AD2 — `shouldRetry` and `sanitize` support
+ * production use cases such as remote circuit breaker checks and external
+ * PII detection services. Raw vendor errors are wrapped into `EnterstellarError`
+ * per AD5.
+ *
+ * @example
+ * ```ts
+ * const errors = createErrorAdapter({
+ *   name: 'sentry-error',
+ *   report: async (error, context) => {
+ *     Sentry.captureException(error, { extra: context });
+ *   },
+ *   shouldRetry: async (error, attempt) => attempt < 3 && isTransient(error),
+ *   sanitize: async (error) => {
+ *     const sanitized = new Error(error.message.replace(/\d{3}-\d{2}-\d{4}/g, '[REDACTED]'));
+ *     sanitized.stack = error.stack;
+ *     return sanitized;
+ *   },
+ * });
+ * ```
+ */
+type ErrorAdapterConfig = {
+    /**
+     * Human-readable adapter name for error messages and DevTools display.
+     *
+     * @example `'sentry-error'`, `'datadog-error'`, `'console-error'`
+     */
+    readonly name: string;
+    /**
+     * Reports an error to the external error tracking service.
+     *
+     * @param error - The error to report (may be an `EnterstellarError`).
+     * @param context - Optional contextual metadata for the error report.
+     */
+    readonly report: (error: Error, context?: Readonly<Record<string, unknown>>) => Promise<void>;
+    /**
+     * Determines whether a failed operation should be retried.
+     *
+     * Async to support production implementations that consult remote
+     * circuit breakers or rate-limit services before deciding.
+     *
+     * @param error - The error that caused the failure.
+     * @param attemptNumber - The current retry attempt (1-based).
+     * @returns `true` if the operation should be retried.
+     */
+    readonly shouldRetry: (error: Error, attemptNumber: number) => Promise<boolean>;
+    /**
+     * Sanitizes an error before it is logged or displayed.
+     * Must strip any PII or sensitive data from the error message and stack.
+     *
+     * Async to support production implementations that call external
+     * PII detection services for HIPAA-compliant sanitization.
+     *
+     * @param error - The error to sanitize.
+     * @returns A sanitized copy of the error.
+     */
+    readonly sanitize: (error: Error) => Promise<Error>;
+};
+/**
+ * Configuration for {@link createAnalyticsAdapter}.
+ *
+ * Implementations forward user interaction events and identity to analytics
+ * services. Both methods are fire-and-forget (void return).
+ *
+ * @example
+ * ```ts
+ * const analytics = createAnalyticsAdapter({
+ *   name: 'mixpanel-analytics',
+ *   track: (event, properties) => {
+ *     mixpanel.track(event, properties);
+ *   },
+ *   identify: (userId, traits) => {
+ *     mixpanel.identify(userId);
+ *     if (traits) mixpanel.people.set(traits);
+ *   },
+ * });
+ * ```
+ */
+type AnalyticsAdapterConfig = {
+    /**
+     * Human-readable adapter name for error messages and DevTools display.
+     *
+     * @example `'mixpanel-analytics'`, `'amplitude-analytics'`, `'posthog-analytics'`
+     */
+    readonly name: string;
+    /**
+     * Tracks a named event with optional properties.
+     * Fire-and-forget — no return value.
+     *
+     * @param event - The event name (e.g., `'zone_rendered'`, `'intent_resolved'`).
+     * @param properties - Optional event properties for segmentation.
+     */
+    readonly track: (event: string, properties?: Readonly<Record<string, unknown>>) => void;
+    /**
+     * Identifies the current user for analytics attribution.
+     * Fire-and-forget — no return value.
+     *
+     * @param userId - Unique user identifier.
+     * @param traits - Optional user traits (role, plan, etc.).
+     */
+    readonly identify: (userId: string, traits?: Readonly<Record<string, unknown>>) => void;
+};
+/**
+ * Discriminated adapter type name.
+ * Used by {@link validateAdapterConfig} to determine which fields to validate.
+ */
+type AdapterType = 'auth' | 'data' | 'error' | 'analytics';
+
+/**
+ * @module @enterstellar-ai/adapters/create-auth-adapter
+ * @description Factory functions for creating validated `AuthAdapter` instances.
+ *
+ * - `createAuthAdapter(config)` — wraps a consumer-provided implementation,
+ *   validates config via {@link validateAdapterConfig}, and wraps every method
+ *   in error handling per Design Choice AD5 (raw vendor errors never leak).
+ *
+ * - `createNoopAuthAdapter()` — returns a no-op adapter for testing and
+ *   development when no real auth provider is connected.
+ *
+ * Both factories return a plain object with closures (R1 pattern — no classes).
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD1 — minimal but complete: getSession, hasRole, onAuthChange
+ * @see Design Choice AD2 — always async (I/O methods)
+ * @see Design Choice AD5 — wrap into EnterstellarError
+ */
+
+/**
+ * Creates a validated `AuthAdapter` from consumer-provided config.
+ *
+ * The factory:
+ * 1. Validates the config (name + required methods) — throws `ENS-7001` on failure.
+ * 2. Wraps `getSession()` and `hasRole()` in error handling → `ENS-7005` on throw.
+ * 3. Wraps `onAuthChange()` in error handling → `ENS-7002` on throw.
+ *
+ * Consumers never see raw vendor errors — all failures are `EnterstellarError` (AD5).
+ *
+ * @param config - The adapter implementation with a `name` and all required methods.
+ * @returns A frozen `AuthAdapter` instance.
+ * @throws `EnterstellarError` with code `ENS-7001` if config validation fails.
+ *
+ * @example
+ * ```ts
+ * import { createAuthAdapter } from '@enterstellar-ai/adapters';
+ *
+ * const auth = createAuthAdapter({
+ *   name: 'supabase-auth',
+ *   getSession: async () => {
+ *     const { data } = await supabase.auth.getSession();
+ *     if (!data.session) return null;
+ *     return { userId: data.session.user.id, roles: ['clinician'] };
+ *   },
+ *   hasRole: async (role) => {
+ *     const session = await supabase.auth.getSession();
+ *     return session.data.session?.user.role === role;
+ *   },
+ *   onAuthChange: (cb) => {
+ *     const { data } = supabase.auth.onAuthStateChange((_event, session) => {
+ *       cb(session ? { userId: session.user.id, roles: ['clinician'] } : null);
+ *     });
+ *     return () => data.subscription.unsubscribe();
+ *   },
+ * });
+ * ```
+ */
+declare function createAuthAdapter(config: AuthAdapterConfig): AuthAdapter;
+/**
+ * Creates a no-op `AuthAdapter` for testing and development.
+ *
+ * All methods resolve to safe defaults:
+ * - `getSession()` → `null` (unauthenticated)
+ * - `hasRole()` → `false` (no permissions)
+ * - `onAuthChange()` → no-op unsubscribe function (never fires)
+ *
+ * @returns A frozen, no-op `AuthAdapter` instance.
+ *
+ * @example
+ * ```ts
+ * import { createNoopAuthAdapter } from '@enterstellar-ai/adapters';
+ *
+ * const auth = createNoopAuthAdapter();
+ * await auth.getSession(); // null
+ * await auth.hasRole('admin'); // false
+ * const unsub = auth.onAuthChange(() => {}); // never called
+ * unsub(); // no-op
+ * ```
+ */
+declare function createNoopAuthAdapter(): AuthAdapter;
+
+/**
+ * @module @enterstellar-ai/adapters/create-data-adapter
+ * @description Factory functions for creating validated `DataAdapter` instances.
+ *
+ * - `createDataAdapter(config)` — wraps a consumer-provided implementation,
+ *   validates config via {@link validateAdapterConfig}, and wraps every method
+ *   in error handling per Design Choice AD5 (raw vendor errors never leak).
+ *
+ * - `createNoopDataAdapter()` — returns a no-op adapter for testing and
+ *   development when no real data source is connected.
+ *
+ * Both factories return a plain object with closures (R1 pattern — no classes).
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD1 — minimal but complete: query, mutate, subscribe
+ * @see Design Choice AD2 — always async (except subscribe's sync unsubscribe return)
+ * @see Design Choice AD3 — convention-based dot-notation resolver
+ * @see Design Choice AD5 — wrap into EnterstellarError
+ */
+
+/**
+ * Creates a validated `DataAdapter` from consumer-provided config.
+ *
+ * The factory:
+ * 1. Validates the config (name + required methods) — throws `ENS-7001` on failure.
+ * 2. Wraps `query()` in error handling → `ENS-7003` on throw (includes resource name).
+ * 3. Wraps `mutate()` in error handling → `ENS-7004` on throw (includes resource + action).
+ * 4. Wraps `subscribe()` in error handling → `ENS-7002` on throw (generic method error).
+ *
+ * Consumers never see raw vendor errors — all failures are `EnterstellarError` (AD5).
+ *
+ * @param config - The adapter implementation with a `name` and all required methods.
+ * @returns A frozen `DataAdapter` instance.
+ * @throws `EnterstellarError` with code `ENS-7001` if config validation fails.
+ *
+ * @example
+ * ```ts
+ * import { createDataAdapter } from '@enterstellar-ai/adapters';
+ *
+ * const data = createDataAdapter({
+ *   name: 'supabase-data',
+ *   query: async (resource, params) => {
+ *     const { data } = await supabase.from(resource).select('*').match(params ?? {});
+ *     return data ?? [];
+ *   },
+ *   mutate: async (resource, action, payload) => {
+ *     if (action === 'create') {
+ *       const { data } = await supabase.from(resource).insert(payload).select().single();
+ *       return data;
+ *     }
+ *     return null;
+ *   },
+ *   subscribe: (resource, callback) => {
+ *     const channel = supabase.channel(resource)
+ *       .on('postgres_changes', { event: '*', schema: 'public', table: resource },
+ *         () => { data.query(resource).then(callback); })
+ *       .subscribe();
+ *     return () => { void supabase.removeChannel(channel); };
+ *   },
+ * });
+ * ```
+ */
+declare function createDataAdapter(config: DataAdapterConfig): DataAdapter;
+/**
+ * Creates a no-op `DataAdapter` for testing and development.
+ *
+ * All methods resolve to safe defaults:
+ * - `query()` → `[]` (empty result set)
+ * - `mutate()` → `null` (no record returned)
+ * - `subscribe()` → no-op unsubscribe function
+ *
+ * @returns A frozen, no-op `DataAdapter` instance.
+ *
+ * @example
+ * ```ts
+ * import { createNoopDataAdapter } from '@enterstellar-ai/adapters';
+ *
+ * const data = createNoopDataAdapter();
+ * await data.query('patients.vitals'); // []
+ * await data.mutate('patients', 'create', { name: 'Test' }); // null
+ * const unsub = data.subscribe('patients', () => {}); // noop unsub
+ * unsub(); // no-op
+ * ```
+ */
+declare function createNoopDataAdapter(): DataAdapter;
+
+/**
+ * @module @enterstellar-ai/adapters/create-error-adapter
+ * @description Factory functions for creating validated `ErrorAdapter` instances.
+ *
+ * - `createErrorAdapter(config)` — wraps a consumer-provided implementation,
+ *   validates config via {@link validateAdapterConfig}, and wraps every method
+ *   in error handling per Design Choice AD5 (raw vendor errors never leak).
+ *
+ * - `createNoopErrorAdapter()` — returns a no-op adapter for testing and
+ *   development when no real error tracking service is connected.
+ *
+ * Both factories return a plain object with closures (R1 pattern — no classes).
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD2 — all methods async (I/O + future-proofing)
+ * @see Design Choice AD5 — wrap into EnterstellarError
+ */
+
+/**
+ * Creates a validated `ErrorAdapter` from consumer-provided config.
+ *
+ * The factory:
+ * 1. Validates the config (name + required methods) — throws `ENS-7001` on failure.
+ * 2. Wraps `report()` in async error handling → `ENS-7002` on throw.
+ * 3. Wraps `shouldRetry()` in async error handling → `ENS-7002` on throw.
+ * 4. Wraps `sanitize()` in async error handling → `ENS-7002` on throw.
+ *
+ * All three methods are async per AD2 — even `shouldRetry` and `sanitize`
+ * which may seem synchronous in simple implementations, but production
+ * adapters may require remote circuit breaker checks or external PII
+ * detection services.
+ *
+ * Consumers never see raw vendor errors — all failures are `EnterstellarError` (AD5).
+ *
+ * @param config - The adapter implementation with a `name` and all required methods.
+ * @returns A frozen `ErrorAdapter` instance.
+ * @throws `EnterstellarError` with code `ENS-7001` if config validation fails.
+ *
+ * @example
+ * ```ts
+ * import { createErrorAdapter } from '@enterstellar-ai/adapters';
+ *
+ * const errors = createErrorAdapter({
+ *   name: 'sentry-error',
+ *   report: async (error, context) => {
+ *     Sentry.captureException(error, { extra: context });
+ *   },
+ *   shouldRetry: async (error, attempt) => attempt < 3 && isTransient(error),
+ *   sanitize: async (error) => {
+ *     const sanitized = new Error(error.message.replace(/SSN-\d+/g, '[REDACTED]'));
+ *     sanitized.stack = error.stack;
+ *     return sanitized;
+ *   },
+ * });
+ * ```
+ */
+declare function createErrorAdapter(config: ErrorAdapterConfig): ErrorAdapter;
+/**
+ * Creates a no-op `ErrorAdapter` for testing and development.
+ *
+ * All methods resolve to safe defaults:
+ * - `report()` → void (errors silently consumed)
+ * - `shouldRetry()` → `false` (never retry)
+ * - `sanitize()` → returns error as-is (no transformation)
+ *
+ * @returns A frozen, no-op `ErrorAdapter` instance.
+ *
+ * @example
+ * ```ts
+ * import { createNoopErrorAdapter } from '@enterstellar-ai/adapters';
+ *
+ * const errors = createNoopErrorAdapter();
+ * await errors.report(new Error('test')); // no-op
+ * await errors.shouldRetry(new Error('test'), 1); // false
+ * await errors.sanitize(new Error('test')); // returns same error
+ * ```
+ */
+declare function createNoopErrorAdapter(): ErrorAdapter;
+
+/**
+ * @module @enterstellar-ai/adapters/create-analytics-adapter
+ * @description Factory functions for creating validated `AnalyticsAdapter` instances.
+ *
+ * - `createAnalyticsAdapter(config)` — wraps a consumer-provided implementation,
+ *   validates config via {@link validateAdapterConfig}, and wraps every method
+ *   in error handling per Design Choice AD5 (raw vendor errors never leak).
+ *
+ * - `createNoopAnalyticsAdapter()` — returns a no-op adapter for testing and
+ *   development when no real analytics service is connected.
+ *
+ * Both factories return a plain object with closures (R1 pattern — no classes).
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD1 — minimal but complete: track, identify
+ * @see Design Choice AD5 — wrap into EnterstellarError
+ */
+
+/**
+ * Creates a validated `AnalyticsAdapter` from consumer-provided config.
+ *
+ * The factory:
+ * 1. Validates the config (name + required methods) — throws `ENS-7001` on failure.
+ * 2. Wraps `track()` in sync error handling → `ENS-7002` on throw.
+ * 3. Wraps `identify()` in sync error handling → `ENS-7002` on throw.
+ *
+ * Both `track()` and `identify()` are fire-and-forget (void return).
+ * Consumers never see raw vendor errors — all failures are `EnterstellarError` (AD5).
+ *
+ * @param config - The adapter implementation with a `name` and all required methods.
+ * @returns A frozen `AnalyticsAdapter` instance.
+ * @throws `EnterstellarError` with code `ENS-7001` if config validation fails.
+ *
+ * @example
+ * ```ts
+ * import { createAnalyticsAdapter } from '@enterstellar-ai/adapters';
+ *
+ * const analytics = createAnalyticsAdapter({
+ *   name: 'mixpanel-analytics',
+ *   track: (event, properties) => {
+ *     mixpanel.track(event, properties);
+ *   },
+ *   identify: (userId, traits) => {
+ *     mixpanel.identify(userId);
+ *     if (traits) mixpanel.people.set(traits);
+ *   },
+ * });
+ * ```
+ */
+declare function createAnalyticsAdapter(config: AnalyticsAdapterConfig): AnalyticsAdapter;
+/**
+ * Creates a no-op `AnalyticsAdapter` for testing and development.
+ *
+ * All methods are silent no-ops:
+ * - `track()` → void (events silently consumed)
+ * - `identify()` → void (identity silently consumed)
+ *
+ * @returns A frozen, no-op `AnalyticsAdapter` instance.
+ *
+ * @example
+ * ```ts
+ * import { createNoopAnalyticsAdapter } from '@enterstellar-ai/adapters';
+ *
+ * const analytics = createNoopAnalyticsAdapter();
+ * analytics.track('zone_rendered', { zone: 'main' }); // no-op
+ * analytics.identify('user-123', { role: 'clinician' }); // no-op
+ * ```
+ */
+declare function createNoopAnalyticsAdapter(): AnalyticsAdapter;
+
+/**
+ * @module @enterstellar-ai/adapters/errors
+ * @description Error factory functions for the adapters module.
+ *
+ * Every error is an `EnterstellarError` with:
+ * - Machine-readable `code` (`ENS-7xxx`)
+ * - Module identifier `'adapters'`
+ * - `recoverable` flag per Enterstellar error taxonomy
+ *
+ * Error taxonomy:
+ * - `ENS-7001` — ADAPTER_VALIDATION_FAILED: config missing required methods or invalid name
+ *   (non-recoverable, developer misconfiguration)
+ * - `ENS-7002` — ADAPTER_METHOD_ERROR: adapter method threw during execution (recoverable)
+ * - `ENS-7003` — ADAPTER_QUERY_ERROR: DataAdapter query() failed (recoverable)
+ * - `ENS-7004` — ADAPTER_MUTATION_ERROR: DataAdapter mutate() failed (recoverable)
+ * - `ENS-7005` — ADAPTER_AUTH_ERROR: AuthAdapter session/role check failed (recoverable)
+ *
+ * @see Coding Rules — Error Taxonomy
+ * @see Design Choice AD5 — wrap into EnterstellarError
+ * @see Design Choice C14 — error code ranges
+ */
+
+/**
+ * Creates an error for when an adapter config fails validation.
+ *
+ * This is a **non-recoverable** error — it indicates developer misconfiguration
+ * (missing required methods, empty name, non-function fields). The consumer
+ * must fix their adapter config before proceeding.
+ *
+ * @param adapterType - The adapter category that failed validation (e.g., `'auth'`, `'data'`).
+ * @param reason - Human-readable explanation of what is invalid.
+ * @returns An `EnterstellarError` with code `ENS-7001`.
+ *
+ * @example
+ * ```ts
+ * throw adapterValidationError('auth', 'Missing required method: getSession');
+ * // EnterstellarError: Adapter validation failed for "auth": Missing required method: getSession
+ * //   code: 'ENS-7001', module: 'adapters', recoverable: false
+ * ```
+ */
+declare function adapterValidationError(adapterType: AdapterType, reason: string): EnterstellarError;
+/**
+ * Creates an error for when an adapter method throws during execution.
+ *
+ * This is a **recoverable** error — the underlying infrastructure may have
+ * experienced a transient failure. The operation can be retried. The original
+ * error is preserved in `cause` for debugging (AD5).
+ *
+ * @param adapterName - The adapter instance name (e.g., `'supabase-auth'`).
+ * @param methodName - The method that threw (e.g., `'getSession'`, `'track'`).
+ * @param cause - The original error thrown by the adapter implementation.
+ * @returns An `EnterstellarError` with code `ENS-7002`.
+ *
+ * @example
+ * ```ts
+ * throw adapterMethodError('supabase-auth', 'getSession', originalError);
+ * // EnterstellarError: Adapter "supabase-auth" method "getSession" threw.
+ * //   code: 'ENS-7002', module: 'adapters', recoverable: true, cause: originalError
+ * ```
+ */
+declare function adapterMethodError(adapterName: string, methodName: string, cause?: unknown): EnterstellarError;
+/**
+ * Creates an error for when a {@link DataAdapter}'s `query()` method fails.
+ *
+ * This is a **recoverable** error — the data source may be temporarily
+ * unavailable. Specialized variant of `ENS-7002` that includes the
+ * queried resource name for debugging.
+ *
+ * @param adapterName - The adapter instance name (e.g., `'supabase-data'`).
+ * @param resource - The resource that was being queried (e.g., `'patients.vitals'`).
+ * @param cause - The original error thrown by the query implementation.
+ * @returns An `EnterstellarError` with code `ENS-7003`.
+ *
+ * @example
+ * ```ts
+ * throw adapterQueryError('supabase-data', 'patients.vitals', pgError);
+ * // EnterstellarError: Adapter "supabase-data" query failed for resource "patients.vitals".
+ * //   code: 'ENS-7003', module: 'adapters', recoverable: true, cause: pgError
+ * ```
+ */
+declare function adapterQueryError(adapterName: string, resource: string, cause?: unknown): EnterstellarError;
+/**
+ * Creates an error for when a {@link DataAdapter}'s `mutate()` method fails.
+ *
+ * This is a **recoverable** error — the data source may be temporarily
+ * unavailable. Specialized variant of `ENS-7002` that includes the
+ * resource name and mutation action for debugging.
+ *
+ * @param adapterName - The adapter instance name (e.g., `'supabase-data'`).
+ * @param resource - The resource being mutated (e.g., `'patients'`).
+ * @param action - The mutation action that failed (`'create'`, `'update'`, or `'delete'`).
+ * @param cause - The original error thrown by the mutation implementation.
+ * @returns An `EnterstellarError` with code `ENS-7004`.
+ *
+ * @example
+ * ```ts
+ * throw adapterMutationError('supabase-data', 'patients', 'update', pgError);
+ * // EnterstellarError: Adapter "supabase-data" mutation "update" failed for resource "patients".
+ * //   code: 'ENS-7004', module: 'adapters', recoverable: true, cause: pgError
+ * ```
+ */
+declare function adapterMutationError(adapterName: string, resource: string, action: 'create' | 'update' | 'delete', cause?: unknown): EnterstellarError;
+/**
+ * Creates an error for when an {@link AuthAdapter}'s session or role check fails.
+ *
+ * This is a **recoverable** error — the auth provider may be temporarily
+ * unavailable, or the session may have expired. Specialized variant of
+ * `ENS-7002` for authentication operations.
+ *
+ * @param adapterName - The adapter instance name (e.g., `'clerk-auth'`).
+ * @param operation - The auth operation that failed (e.g., `'getSession'`, `'hasRole'`).
+ * @param cause - The original error thrown by the auth implementation.
+ * @returns An `EnterstellarError` with code `ENS-7005`.
+ *
+ * @example
+ * ```ts
+ * throw adapterAuthError('clerk-auth', 'getSession', sessionExpiredError);
+ * // EnterstellarError: Adapter "clerk-auth" auth operation "getSession" failed.
+ * //   code: 'ENS-7005', module: 'adapters', recoverable: true, cause: sessionExpiredError
+ * ```
+ */
+declare function adapterAuthError(adapterName: string, operation: string, cause?: unknown): EnterstellarError;
+
+/**
+ * @module @enterstellar-ai/adapters/validate-adapter
+ * @description Shared runtime validation for adapter configuration objects.
+ *
+ * Called by each `createXxxAdapter()` factory before wrapping the consumer's
+ * implementation. Validates that:
+ * - The config has a non-empty `name` string
+ * - All required methods for the adapter type are present and are functions
+ *
+ * Throws `ENS-7001` (`adapterValidationError`) on any violation — this is a
+ * non-recoverable developer error per Enterstellar error taxonomy.
+ *
+ * @see Coding Rules — Error Taxonomy (developer errors → fatal throw)
+ * @see Design Choice AD1 — minimal but complete interfaces
+ */
+
+/**
+ * Validates that an adapter config object has a valid name and all required methods.
+ *
+ * This function performs two checks:
+ * 1. **Name check:** `config.name` must be a non-empty string.
+ * 2. **Method check:** Every method listed in {@link REQUIRED_METHODS} for the
+ *    given `adapterType` must be present on the config and be `typeof === 'function'`.
+ *
+ * Throws `ENS-7001` on the first validation failure encountered.
+ *
+ * @param adapterType - The adapter category being validated (e.g., `'auth'`, `'data'`).
+ * @param config - The raw config object to validate.
+ * @throws `EnterstellarError` with code `ENS-7001` if validation fails.
+ *
+ * @example
+ * ```ts
+ * // Valid — passes silently
+ * validateAdapterConfig('auth', {
+ *   name: 'supabase-auth',
+ *   getSession: async () => null,
+ *   hasRole: async () => false,
+ *   onAuthChange: (cb) => () => {},
+ * });
+ *
+ * // Invalid — throws ENS-7001
+ * validateAdapterConfig('auth', { name: '', getSession: null });
+ * // EnterstellarError: Adapter validation failed for "auth": "name" must be a non-empty string.
+ * ```
+ */
+declare function validateAdapterConfig(adapterType: AdapterType, config: Readonly<Record<string, unknown>>): void;
+
+/**
+ * @module @enterstellar-ai/adapters/version
+ * @description Package version constant for `@enterstellar-ai/adapters`.
+ *
+ * Used by DevTools for version display and runtime compatibility checks.
+ * Must be kept in sync with the `version` field in `package.json`.
+ *
+ * @see Design Choice T14 — version exports
+ */
+/**
+ * Current version of the `@enterstellar-ai/adapters` package.
+ *
+ * @remarks
+ * This value MUST match the `version` field in `package.json`.
+ * Update this constant whenever a new version is released via Changesets.
+ */
+declare const ADAPTERS_VERSION: "0.0.0";
+
+export { ADAPTERS_VERSION, type AdapterType, type AnalyticsAdapterConfig, type AuthAdapterConfig, type DataAdapterConfig, type ErrorAdapterConfig, adapterAuthError, adapterMethodError, adapterMutationError, adapterQueryError, adapterValidationError, createAnalyticsAdapter, createAuthAdapter, createDataAdapter, createErrorAdapter, createNoopAnalyticsAdapter, createNoopAuthAdapter, createNoopDataAdapter, createNoopErrorAdapter, validateAdapterConfig };