@outfitter/contracts 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,1354 @@
+import { TaggedErrorClass } from "better-result";
+/**
+* Error categories for classification, exit codes, and HTTP status mapping.
+*
+* Used for:
+* - CLI exit code determination
+* - HTTP status code mapping
+* - Error grouping in logs and metrics
+* - Client retry decisions (transient vs permanent)
+*/
+type ErrorCategory = "validation" | "not_found" | "conflict" | "permission" | "timeout" | "rate_limit" | "network" | "internal" | "auth" | "cancelled";
+/**
+* Maps error category to CLI exit code.
+* Non-zero exit indicates error; specific values for script automation.
+*/
+declare const exitCodeMap: Record<ErrorCategory, number>;
+/**
+* Maps error category to HTTP status code.
+* Used by MCP servers and API responses.
+*/
+declare const statusCodeMap: Record<ErrorCategory, number>;
+/**
+* Serialized error format for JSON transport.
+*/
+interface SerializedError {
+	_tag: string;
+	category: ErrorCategory;
+	message: string;
+	context?: Record<string, unknown>;
+}
+/**
+* Base interface for OutfitterError properties.
+* All concrete error classes must include these fields.
+*/
+interface KitErrorProps {
+	message: string;
+	category: ErrorCategory;
+	context?: Record<string, unknown>;
+}
+/**
+* Get CLI exit code for an error category.
+*/
+declare function getExitCode(category: ErrorCategory): number;
+/**
+* Get HTTP status code for an error category.
+*/
+declare function getStatusCode(category: ErrorCategory): number;
+declare const ValidationErrorBase: TaggedErrorClass<"ValidationError", {
+	message: string;
+	field?: string;
+}>;
+declare const AssertionErrorBase: TaggedErrorClass<"AssertionError", {
+	message: string;
+}>;
+declare const NotFoundErrorBase: TaggedErrorClass<"NotFoundError", {
+	message: string;
+	resourceType: string;
+	resourceId: string;
+}>;
+declare const ConflictErrorBase: TaggedErrorClass<"ConflictError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const PermissionErrorBase: TaggedErrorClass<"PermissionError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const TimeoutErrorBase: TaggedErrorClass<"TimeoutError", {
+	message: string;
+	operation: string;
+	timeoutMs: number;
+}>;
+declare const RateLimitErrorBase: TaggedErrorClass<"RateLimitError", {
+	message: string;
+	retryAfterSeconds?: number;
+}>;
+declare const NetworkErrorBase: TaggedErrorClass<"NetworkError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const InternalErrorBase: TaggedErrorClass<"InternalError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const AuthErrorBase: TaggedErrorClass<"AuthError", {
+	message: string;
+	reason?: "missing" | "invalid" | "expired";
+}>;
+declare const CancelledErrorBase: TaggedErrorClass<"CancelledError", {
+	message: string;
+}>;
+/**
+* Input validation failed.
+*
+* @example
+* ```typescript
+* new ValidationError({ message: "Email format invalid", field: "email" });
+* ```
+*/
+declare class ValidationError extends ValidationErrorBase {
+	readonly category: "validation";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Assertion failed (invariant violation).
+*
+* Used by assertion utilities that return Result types instead of throwing.
+* AssertionError indicates a programming bug — an invariant that should
+* never be violated was broken. These are internal errors, not user input
+* validation failures.
+*
+* **Category rationale**: Uses `internal` (not `validation`) because:
+* - Assertions check **invariants** (programmer assumptions), not user input
+* - A failed assertion means "this should be impossible if the code is correct"
+* - User-facing validation uses {@link ValidationError} with helpful field info
+* - HTTP 500 is correct: this is a server bug, not a client mistake
+*
+* @example
+* ```typescript
+* // In domain logic after validation has passed
+* const result = assertDefined(cachedValue, "Cache should always have value after init");
+* if (result.isErr()) {
+*   return result; // Propagate as internal error
+* }
+* ```
+*
+* @see ValidationError - For user input validation failures (HTTP 400)
+*/
+declare class AssertionError extends AssertionErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Requested resource not found.
+*
+* @example
+* ```typescript
+* new NotFoundError({ message: "note not found: abc123", resourceType: "note", resourceId: "abc123" });
+* ```
+*/
+declare class NotFoundError extends NotFoundErrorBase {
+	readonly category: "not_found";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* State conflict (optimistic locking, concurrent modification).
+*
+* @example
+* ```typescript
+* new ConflictError({ message: "Resource was modified by another process" });
+* ```
+*/
+declare class ConflictError extends ConflictErrorBase {
+	readonly category: "conflict";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authorization denied.
+*
+* @example
+* ```typescript
+* new PermissionError({ message: "Cannot delete read-only resource" });
+* ```
+*/
+declare class PermissionError extends PermissionErrorBase {
+	readonly category: "permission";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation timed out.
+*
+* @example
+* ```typescript
+* new TimeoutError({ message: "Database query timed out after 5000ms", operation: "Database query", timeoutMs: 5000 });
+* ```
+*/
+declare class TimeoutError extends TimeoutErrorBase {
+	readonly category: "timeout";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Rate limit exceeded.
+*
+* @example
+* ```typescript
+* new RateLimitError({ message: "Rate limit exceeded, retry after 60s", retryAfterSeconds: 60 });
+* ```
+*/
+declare class RateLimitError extends RateLimitErrorBase {
+	readonly category: "rate_limit";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Network/transport failure.
+*
+* @example
+* ```typescript
+* new NetworkError({ message: "Connection refused to api.example.com" });
+* ```
+*/
+declare class NetworkError extends NetworkErrorBase {
+	readonly category: "network";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Unexpected internal error.
+*
+* @example
+* ```typescript
+* new InternalError({ message: "Unexpected state in processor" });
+* ```
+*/
+declare class InternalError extends InternalErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authentication failed (missing or invalid credentials).
+*
+* @example
+* ```typescript
+* new AuthError({ message: "Invalid API key", reason: "invalid" });
+* ```
+*/
+declare class AuthError extends AuthErrorBase {
+	readonly category: "auth";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation cancelled by user or signal.
+*
+* @example
+* ```typescript
+* new CancelledError({ message: "Operation cancelled by user" });
+* ```
+*/
+declare class CancelledError extends CancelledErrorBase {
+	readonly category: "cancelled";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Union type of all concrete error class instances.
+*/
+type AnyKitError = InstanceType<typeof ValidationError> | InstanceType<typeof AssertionError> | InstanceType<typeof NotFoundError> | InstanceType<typeof ConflictError> | InstanceType<typeof PermissionError> | InstanceType<typeof TimeoutError> | InstanceType<typeof RateLimitError> | InstanceType<typeof NetworkError> | InstanceType<typeof InternalError> | InstanceType<typeof AuthError> | InstanceType<typeof CancelledError>;
+/**
+* Type alias for backwards compatibility with handler signatures.
+* Use AnyKitError for the union type.
+*/
+type OutfitterError = AnyKitError;
+import { Result } from "better-result";
+import { z } from "zod";
+/**
+* Create a validator function from a Zod schema.
+*
+* @typeParam T - The validated output type
+* @param schema - Zod schema to validate against
+* @returns A function that validates input and returns Result
+*
+* @example
+* ```typescript
+* const NoteSchema = z.object({
+*   id: z.string().uuid(),
+*   title: z.string().min(1),
+* });
+*
+* const validateNote = createValidator(NoteSchema);
+* const result = validateNote(input); // Result<Note, ValidationError>
+* ```
+*/
+declare function createValidator<T>(schema: z.ZodType<T>): (input: unknown) => Result<T, ValidationError>;
+/**
+* Validate input against a Zod schema.
+*
+* Standardized wrapper for Zod schemas that returns Result instead of throwing.
+*
+* @typeParam T - The validated output type
+* @param schema - Zod schema to validate against
+* @param input - Unknown input to validate
+* @returns Result with validated data or ValidationError
+*
+* @example
+* ```typescript
+* const result = validateInput(NoteSchema, userInput);
+* if (result.isErr()) {
+*   console.error(result.unwrapErr().message);
+* }
+* ```
+*/
+declare function validateInput<T>(schema: z.ZodType<T>, input: unknown): Result<T, ValidationError>;
+import { Result as Result2 } from "better-result";
+/**
+* Error types for adapter operations.
+* These extend the base error taxonomy for adapter-specific failures.
+*/
+/** Error during indexing operations */
+interface IndexError {
+	readonly _tag: "IndexError";
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/** Error during cache operations */
+interface CacheError {
+	readonly _tag: "CacheError";
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/** Error during auth/credential operations */
+interface AdapterAuthError {
+	readonly _tag: "AdapterAuthError";
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/** Error during storage operations */
+interface StorageError {
+	readonly _tag: "StorageError";
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/**
+* Search options for index adapter.
+*/
+interface SearchOptions {
+	/** Maximum results to return */
+	limit?: number;
+	/** Offset for pagination */
+	offset?: number;
+	/** Field-specific filters */
+	filters?: Record<string, unknown>;
+	/** Fields to boost in relevance scoring */
+	boostFields?: string[];
+}
+/**
+* Search result from index adapter.
+*/
+interface SearchResult<T> {
+	/** Matched items with relevance scores */
+	hits: Array<{
+		item: T;
+		score: number;
+		highlights?: Record<string, string[]>;
+	}>;
+	/** Total number of matches (for pagination) */
+	total: number;
+	/** Search execution time in milliseconds */
+	took: number;
+}
+/**
+* Index statistics.
+*/
+interface IndexStats {
+	/** Total documents indexed */
+	documentCount: number;
+	/** Index size in bytes (if available) */
+	sizeBytes?: number;
+	/** Last update timestamp */
+	lastUpdated: Date | null;
+}
+/**
+* Index adapter - pluggable full-text search backends.
+*
+* Implementations: SQLite FTS5, future: Tantivy, Meilisearch
+*
+* @typeParam T - The indexed document type
+*
+* @example
+* ```typescript
+* const sqliteIndex = new SqliteFts5Adapter<Note>({
+*   db: database,
+*   table: "notes_fts",
+*   fields: ["title", "content", "tags"],
+* });
+*
+* await sqliteIndex.index(notes);
+* const results = await sqliteIndex.search("authentication patterns");
+* ```
+*/
+interface IndexAdapter<T> {
+	/** Add or update documents in the index */
+	index(items: T[]): Promise<Result2<void, IndexError>>;
+	/** Full-text search with optional filters */
+	search(query: string, options?: SearchOptions): Promise<Result2<SearchResult<T>, IndexError>>;
+	/** Remove documents by ID */
+	remove(ids: string[]): Promise<Result2<void, IndexError>>;
+	/** Clear all indexed documents */
+	clear(): Promise<Result2<void, IndexError>>;
+	/** Get index statistics */
+	stats(): Promise<Result2<IndexStats, IndexError>>;
+}
+/**
+* Cache adapter - pluggable caching backends.
+*
+* Implementations: SQLite, in-memory LRU, future: Redis via Bun.RedisClient
+*
+* @typeParam T - The cached value type
+*
+* @example
+* ```typescript
+* const cache = new SqliteCacheAdapter<User>({ db, table: "user_cache" });
+*
+* await cache.set("user:123", user, 3600); // 1 hour TTL
+* const cached = await cache.get("user:123");
+* ```
+*/
+interface CacheAdapter<T> {
+	/** Get cached value, null if not found or expired */
+	get(key: string): Promise<Result2<T | null, CacheError>>;
+	/** Set value with optional TTL in seconds */
+	set(key: string, value: T, ttlSeconds?: number): Promise<Result2<void, CacheError>>;
+	/** Delete cached value, returns true if existed */
+	delete(key: string): Promise<Result2<boolean, CacheError>>;
+	/** Clear all cached values */
+	clear(): Promise<Result2<void, CacheError>>;
+	/** Check if key exists (without retrieving value) */
+	has(key: string): Promise<Result2<boolean, CacheError>>;
+	/** Get multiple values at once */
+	getMany(keys: string[]): Promise<Result2<Map<string, T>, CacheError>>;
+}
+/**
+* Auth adapter - pluggable credential storage.
+*
+* Implementations: Environment, OS Keychain (via Bun.secrets), file-based
+*
+* @example
+* ```typescript
+* const auth = new KeychainAuthAdapter({ service: "outfitter" });
+*
+* await auth.set("github_token", token);
+* const stored = await auth.get("github_token");
+* ```
+*/
+interface AuthAdapter {
+	/** Retrieve credential by key */
+	get(key: string): Promise<Result2<string | null, AdapterAuthError>>;
+	/** Store credential */
+	set(key: string, value: string): Promise<Result2<void, AdapterAuthError>>;
+	/** Remove credential */
+	delete(key: string): Promise<Result2<boolean, AdapterAuthError>>;
+	/** List available credential keys (not values) */
+	list(): Promise<Result2<string[], AdapterAuthError>>;
+}
+/**
+* Storage adapter - pluggable blob/file storage.
+*
+* Implementations: Local filesystem, S3 via Bun.S3Client, R2
+*
+* @example
+* ```typescript
+* const storage = new LocalStorageAdapter({ basePath: "/data" });
+*
+* await storage.write("notes/abc.md", content);
+* const data = await storage.read("notes/abc.md");
+* ```
+*/
+interface StorageAdapter {
+	/** Read file contents */
+	read(path: string): Promise<Result2<Uint8Array, StorageError>>;
+	/** Write file contents */
+	write(path: string, data: Uint8Array): Promise<Result2<void, StorageError>>;
+	/** Delete file */
+	delete(path: string): Promise<Result2<boolean, StorageError>>;
+	/** Check if file exists */
+	exists(path: string): Promise<Result2<boolean, StorageError>>;
+	/** List files in directory */
+	list(prefix: string): Promise<Result2<string[], StorageError>>;
+	/** Get file metadata (size, modified time) */
+	stat(path: string): Promise<Result2<{
+		size: number;
+		modifiedAt: Date;
+	} | null, StorageError>>;
+}
+import { Result as Result3 } from "better-result";
+/**
+* Metadata attached to every response envelope.
+*/
+interface EnvelopeMeta {
+	/** Unique request identifier for tracing */
+	requestId: string;
+	/** ISO timestamp of response generation */
+	timestamp: string;
+	/** Operation duration in milliseconds */
+	durationMs?: number;
+}
+/**
+* Pagination metadata for list responses.
+*/
+interface PaginationMeta {
+	/** Total number of items (if known) */
+	total?: number;
+	/** Number of items returned */
+	count: number;
+	/** Cursor for next page (null if no more pages) */
+	nextCursor: string | null;
+	/** Whether more pages exist */
+	hasMore: boolean;
+}
+/**
+* Success envelope structure.
+*/
+interface SuccessEnvelope<T> {
+	ok: true;
+	data: T;
+	meta: EnvelopeMeta;
+	pagination?: PaginationMeta;
+}
+/**
+* Error envelope structure.
+*/
+interface ErrorEnvelope {
+	ok: false;
+	error: SerializedError;
+	meta: EnvelopeMeta;
+}
+/**
+* Response envelope - consistent wrapper for all handler responses.
+*/
+type Envelope<T> = SuccessEnvelope<T> | ErrorEnvelope;
+/**
+* HTTP-style response with status code.
+*/
+interface HttpResponse<T> {
+	status: number;
+	body: Envelope<T>;
+}
+/**
+* Convert a Result to a response envelope.
+*
+* @typeParam T - Success data type
+* @typeParam E - Error type (extends OutfitterError)
+* @param result - Handler result to wrap
+* @param meta - Optional metadata overrides
+* @returns Envelope with success data or serialized error
+*
+* @example
+* ```typescript
+* const result = await getNote({ id: "abc123" }, ctx);
+* const envelope = toEnvelope(result, { requestId: ctx.requestId });
+* ```
+*/
+declare function toEnvelope<
+	T,
+	E extends OutfitterError
+>(result: Result3<T, E>, meta?: Partial<EnvelopeMeta>): Envelope<T>;
+/**
+* Convert a Result to HTTP-style response (for MCP over HTTP).
+*
+* Maps error category to appropriate HTTP status code.
+*
+* @typeParam T - Success data type
+* @typeParam E - Error type (extends OutfitterError)
+* @param result - Handler result to convert
+* @returns HTTP response with status code and envelope body
+*
+* @example
+* ```typescript
+* const result = await getNote({ id: "abc123" }, ctx);
+* const response = toHttpResponse(result);
+* // { status: 200, body: { ok: true, data: note, meta: {...} } }
+* // or { status: 404, body: { ok: false, error: {...}, meta: {...} } }
+* ```
+*/
+declare function toHttpResponse<
+	T,
+	E extends OutfitterError
+>(result: Result3<T, E>): HttpResponse<T>;
+import { Result as Result4 } from "better-result";
+/**
+* Options for retry behavior.
+*/
+interface RetryOptions {
+	/** Maximum number of retry attempts (default: 3) */
+	maxAttempts?: number;
+	/** Initial delay in milliseconds (default: 1000) */
+	initialDelayMs?: number;
+	/** Maximum delay in milliseconds (default: 30000) */
+	maxDelayMs?: number;
+	/** Exponential backoff multiplier (default: 2) */
+	backoffMultiplier?: number;
+	/** Whether to add jitter to delays (default: true) */
+	jitter?: boolean;
+	/** Predicate to determine if error is retryable */
+	isRetryable?: (error: OutfitterError) => boolean;
+	/** Abort signal for cancellation */
+	signal?: AbortSignal;
+	/** Callback invoked before each retry */
+	onRetry?: (attempt: number, error: OutfitterError, delayMs: number) => void;
+}
+/**
+* Options for timeout behavior.
+*/
+interface TimeoutOptions {
+	/** Timeout duration in milliseconds */
+	timeoutMs: number;
+	/** Operation name for error context */
+	operation?: string;
+}
+/**
+* Retry an async operation with exponential backoff.
+*
+* Automatically retries transient errors (network, timeout, rate_limit)
+* unless overridden with `isRetryable`.
+*
+* @typeParam T - Success type
+* @param fn - Async function returning Result
+* @param options - Retry configuration
+* @returns Result from final attempt
+*
+* @example
+* ```typescript
+* const result = await retry(
+*   () => fetchData(url),
+*   {
+*     maxAttempts: 5,
+*     initialDelayMs: 500,
+*     onRetry: (attempt, error) => {
+*       logger.warn(`Retry ${attempt}`, { error: error._tag });
+*     },
+*   }
+* );
+* ```
+*/
+declare function retry<T>(fn: () => Promise<Result4<T, OutfitterError>>, options?: RetryOptions): Promise<Result4<T, OutfitterError>>;
+/**
+* Wrap an async operation with a timeout.
+*
+* Returns TimeoutError if operation doesn't complete within the specified duration.
+*
+* @typeParam T - Success type
+* @typeParam E - Error type
+* @param fn - Async function returning Result
+* @param options - Timeout configuration
+* @returns Result from operation or TimeoutError
+*
+* @example
+* ```typescript
+* const result = await withTimeout(
+*   () => slowOperation(),
+*   { timeoutMs: 5000, operation: "database query" }
+* );
+*
+* if (result.isErr() && result.error._tag === "TimeoutError") {
+*   // Handle timeout
+* }
+* ```
+*/
+declare function withTimeout<
+	T,
+	E extends OutfitterError
+>(fn: () => Promise<Result4<T, E>>, options: TimeoutOptions): Promise<Result4<T, E | TimeoutError>>;
+import { Result as Result5 } from "better-result";
+import { z as z2 } from "zod";
+/**
+* Options for error serialization.
+*/
+interface SerializeErrorOptions {
+	/** Include stack trace (default: false in production, true in development) */
+	includeStack?: boolean;
+}
+/**
+* Serialize a OutfitterError to JSON-safe format.
+*
+* Strips stack traces in production, preserves in development.
+* Automatically redacts sensitive values from context.
+*
+* @param error - The error to serialize
+* @param options - Serialization options
+* @returns JSON-safe serialized error
+*
+* @example
+* ```typescript
+* const serialized = serializeError(new NotFoundError("note", "abc123"));
+* // { _tag: "NotFoundError", category: "not_found", message: "note not found: abc123", context: { resourceType: "note", resourceId: "abc123" } }
+* ```
+*/
+declare function serializeError(error: OutfitterError, options?: SerializeErrorOptions): SerializedError;
+/**
+* Deserialize error from JSON (e.g., from MCP response).
+*
+* Returns a typed OutfitterError subclass based on _tag.
+*
+* @param data - Serialized error data
+* @returns Reconstructed OutfitterError instance
+*
+* @example
+* ```typescript
+* const error = deserializeError(jsonData);
+* if (error._tag === "NotFoundError") {
+*   // TypeScript knows error.resourceType exists
+* }
+* ```
+*/
+declare function deserializeError(data: SerializedError): OutfitterError;
+/**
+* Safely stringify any value to JSON.
+*
+* Handles circular references, BigInt, and other non-JSON-safe values.
+* Applies redaction to sensitive values.
+*
+* @param value - Value to stringify
+* @param space - Indentation (default: undefined for compact)
+* @returns JSON string
+*
+* @example
+* ```typescript
+* const json = safeStringify({ apiKey: "sk-secret", data: "safe" });
+* // '{"apiKey":"[REDACTED]","data":"safe"}'
+* ```
+*/
+declare function safeStringify(value: unknown, space?: number): string;
+/**
+* Safely parse JSON string with optional schema validation.
+*
+* Returns Result instead of throwing on invalid JSON.
+*
+* @typeParam T - Expected parsed type (or unknown if no schema)
+* @param json - JSON string to parse
+* @param schema - Optional Zod schema for validation
+* @returns Result with parsed value or ValidationError
+*
+* @example
+* ```typescript
+* const result = safeParse<Config>('{"port": 3000}', ConfigSchema);
+* if (result.isOk()) {
+*   const config = result.unwrap();
+* }
+* ```
+*/
+declare function safeParse<T = unknown>(json: string, schema?: z2.ZodType<T>): Result5<T, ValidationError>;
+import { Result as Result6 } from "better-result";
+/**
+* Logger interface for handler context.
+* Implementations provided by @outfitter/logging.
+*
+* All log methods accept an optional context object that will be merged
+* with any context inherited from parent loggers created via `child()`.
+*/
+interface Logger {
+	trace(message: string, metadata?: Record<string, unknown>): void;
+	debug(message: string, metadata?: Record<string, unknown>): void;
+	info(message: string, metadata?: Record<string, unknown>): void;
+	warn(message: string, metadata?: Record<string, unknown>): void;
+	error(message: string, metadata?: Record<string, unknown>): void;
+	fatal(message: string, metadata?: Record<string, unknown>): void;
+	/**
+	* Creates a child logger with additional context.
+	*
+	* Context from the child is merged with the parent's context,
+	* with child context taking precedence for duplicate keys.
+	* Child loggers are composable (can create nested children).
+	*
+	* @param context - Additional context to include in all log messages
+	* @returns A new Logger instance with the merged context
+	*
+	* @example
+	* ```typescript
+	* const requestLogger = ctx.logger.child({ requestId: ctx.requestId });
+	* requestLogger.info("Processing request"); // includes requestId
+	*
+	* const opLogger = requestLogger.child({ operation: "create" });
+	* opLogger.debug("Starting"); // includes requestId + operation
+	* ```
+	*/
+	child(context: Record<string, unknown>): Logger;
+}
+/**
+* Resolved configuration interface.
+* Implementations provided by @outfitter/config.
+*/
+interface ResolvedConfig {
+	get<T>(key: string): T | undefined;
+	getRequired<T>(key: string): T;
+}
+/**
+* Handler context - provides cross-cutting concerns without polluting handler signatures.
+*
+* @example
+* ```typescript
+* const handler: Handler<Input, Output, NotFoundError> = async (input, ctx) => {
+*   ctx.logger.debug("Processing request", { requestId: ctx.requestId });
+*   // ... handler logic
+* };
+* ```
+*/
+interface HandlerContext {
+	/** Abort signal for cancellation propagation */
+	signal?: AbortSignal;
+	/** Unique request identifier for tracing (UUIDv7) */
+	requestId: string;
+	/** Structured logger with automatic redaction */
+	logger: Logger;
+	/** Resolved configuration values */
+	config?: ResolvedConfig;
+	/** Workspace root path, if detected */
+	workspaceRoot?: string;
+	/** Current working directory */
+	cwd: string;
+	/** Environment variables (filtered, redacted) */
+	env: Record<string, string | undefined>;
+}
+/**
+* Handler - transport-agnostic domain logic unit.
+*
+* Handlers receive typed input, return Results, and know nothing about
+* transport or output format. CLI and MCP are thin adapters over handlers.
+*
+* @typeParam TInput - Validated input parameters
+* @typeParam TOutput - Success return type
+* @typeParam TError - Error type (must extend OutfitterError)
+*
+* @example
+* ```typescript
+* const getNote: Handler<{ id: string }, Note, NotFoundError> = async (input, ctx) => {
+*   const note = await ctx.db.notes.find(input.id);
+*   if (!note) return Result.err(new NotFoundError("note", input.id));
+*   return Result.ok(note);
+* };
+* ```
+*/
+type Handler<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> = (input: TInput, ctx: HandlerContext) => Promise<Result6<TOutput, TError>>;
+/**
+* Synchronous handler variant for operations that don't need async.
+*/
+type SyncHandler<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> = (input: TInput, ctx: HandlerContext) => Result6<TOutput, TError>;
+/**
+* Options for creating a handler context.
+*/
+interface CreateContextOptions {
+	/** Logger instance (uses no-op logger if not provided) */
+	logger?: Logger;
+	/** Resolved configuration */
+	config?: ResolvedConfig;
+	/** Abort signal for cancellation */
+	signal?: AbortSignal;
+	/** Explicit request ID (generates UUIDv7 if not provided) */
+	requestId?: string;
+	/** Workspace root path */
+	workspaceRoot?: string;
+	/** Current working directory (defaults to process.cwd()) */
+	cwd?: string;
+	/** Environment variables to include */
+	env?: Record<string, string | undefined>;
+}
+/**
+* Create a HandlerContext for a new request.
+*
+* Auto-generates requestId using Bun.randomUUIDv7() if not provided.
+*
+* @param options - Context configuration options
+* @returns Fully populated HandlerContext
+*
+* @example
+* ```typescript
+* const ctx = createContext({
+*   logger: createLogger(),
+*   config: resolvedConfig,
+*   signal: controller.signal,
+* });
+*
+* const result = await handler(input, ctx);
+* ```
+*/
+declare function createContext(options: CreateContextOptions): HandlerContext;
+/**
+* Generate a sortable request ID (UUIDv7).
+*
+* UUIDv7 is time-ordered, making it ideal for request tracing
+* as IDs sort chronologically.
+*
+* @returns UUIDv7 string
+*
+* @example
+* ```typescript
+* const requestId = generateRequestId();
+* // "018e4f3c-1a2b-7000-8000-000000000001"
+* ```
+*/
+declare function generateRequestId(): string;
+/**
+* @outfitter/contracts - Capability manifest
+*
+* Shared action capability manifest for CLI/MCP/API/server parity.
+*
+* @packageDocumentation
+*/
+declare const CAPABILITY_SURFACES: readonly ["cli", "mcp", "api", "server"];
+type CapabilitySurface = (typeof CAPABILITY_SURFACES)[number];
+interface ActionCapability {
+	surfaces: readonly CapabilitySurface[];
+	notes?: string;
+}
+declare const DEFAULT_ACTION_SURFACES: readonly ["cli", "mcp"];
+declare function capability(surfaces?: readonly CapabilitySurface[], notes?: string): ActionCapability;
+declare function capabilityAll(notes?: string): ActionCapability;
+declare const ACTION_CAPABILITIES: Record<string, ActionCapability>;
+declare function getActionsForSurface(surface: CapabilitySurface): string[];
+import { z as z3 } from "zod";
+declare const ACTION_SURFACES: readonly ["cli", "mcp", "api", "server"];
+type ActionSurface = (typeof ACTION_SURFACES)[number];
+declare const DEFAULT_REGISTRY_SURFACES: readonly ActionSurface[];
+interface ActionCliOption {
+	readonly flags: string;
+	readonly description: string;
+	readonly defaultValue?: string | boolean | string[];
+	readonly required?: boolean;
+}
+interface ActionCliInputContext {
+	readonly args: readonly string[];
+	readonly flags: Record<string, unknown>;
+}
+interface ActionCliSpec<TInput = unknown> {
+	readonly group?: string;
+	readonly command?: string;
+	readonly description?: string;
+	readonly aliases?: readonly string[];
+	readonly options?: readonly ActionCliOption[];
+	readonly mapInput?: (context: ActionCliInputContext) => TInput;
+}
+interface ActionMcpSpec<TInput = unknown> {
+	readonly tool?: string;
+	readonly description?: string;
+	readonly deferLoading?: boolean;
+	readonly mapInput?: (input: unknown) => TInput;
+}
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface ActionApiSpec {
+	readonly method?: HttpMethod;
+	readonly path?: string;
+	readonly tags?: readonly string[];
+}
+interface ActionTrpcSpec {
+	readonly path?: string;
+}
+interface ActionSpec<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> {
+	readonly id: string;
+	readonly description?: string;
+	readonly surfaces?: readonly ActionSurface[];
+	readonly input: z3.ZodType<TInput>;
+	readonly output?: z3.ZodType<TOutput>;
+	readonly handler: Handler<TInput, TOutput, TError> | SyncHandler<TInput, TOutput, TError>;
+	readonly cli?: ActionCliSpec<TInput>;
+	readonly mcp?: ActionMcpSpec<TInput>;
+	readonly api?: ActionApiSpec;
+	readonly trpc?: ActionTrpcSpec;
+}
+type AnyActionSpec = ActionSpec<unknown, unknown, OutfitterError>;
+interface ActionRegistry {
+	add<
+		TInput,
+		TOutput,
+		TError extends OutfitterError = OutfitterError
+	>(action: ActionSpec<TInput, TOutput, TError>): ActionRegistry;
+	list(): AnyActionSpec[];
+	get(id: string): AnyActionSpec | undefined;
+	forSurface(surface: ActionSurface): AnyActionSpec[];
+}
+declare function defineAction<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+>(action: ActionSpec<TInput, TOutput, TError>): ActionSpec<TInput, TOutput, TError>;
+declare function createActionRegistry(): ActionRegistry;
+/**
+* Configuration for creating a redactor.
+*/
+interface RedactorConfig {
+	/** Regex patterns to match and redact */
+	patterns: RegExp[];
+	/** Object keys whose values should always be redacted */
+	keys: string[];
+	/** Replacement string (default: "[REDACTED]") */
+	replacement?: string;
+	/** Whether to redact recursively in nested objects (default: true) */
+	deep?: boolean;
+}
+/**
+* Redaction event for audit logging.
+*/
+interface RedactionEvent {
+	/** Type of redaction applied */
+	redactedBy: "pattern" | "key";
+	/** Identifier of the pattern/key that matched */
+	matcher: string;
+	/** Location in the object path (e.g., "config.auth.apiKey") */
+	path: string;
+}
+/**
+* Callback for redaction events.
+*/
+type RedactionCallback = (event: RedactionEvent) => void;
+/**
+* Redactor - sensitive data scrubbing for logs, errors, and output.
+*
+* Applied automatically by @outfitter/logging. Manual application
+* required when building custom output or error context.
+*
+* @example
+* ```typescript
+* const redactor = createRedactor({
+*   patterns: [
+*     /Bearer [A-Za-z0-9-_]+/g,           // Auth headers
+*     /sk-[A-Za-z0-9]{48}/g,              // OpenAI keys
+*     /ghp_[A-Za-z0-9]{36}/g,             // GitHub PATs
+*     /password[:=]\s*["']?[^"'\s]+/gi,   // Password fields
+*   ],
+*   keys: ["apiKey", "secret", "token", "password", "credential"],
+*   replacement: "[REDACTED]",
+* });
+*
+* const safeLog = redactor.redact(sensitiveObject);
+* ```
+*/
+interface Redactor {
+	/** Redact sensitive values from an object (deep) */
+	redact<T>(value: T): T;
+	/** Redact sensitive values from a string */
+	redactString(value: string): string;
+	/** Check if a key name is sensitive */
+	isSensitiveKey(key: string): boolean;
+	/** Add a pattern at runtime */
+	addPattern(pattern: RegExp): void;
+	/** Add a sensitive key at runtime */
+	addSensitiveKey(key: string): void;
+}
+/**
+* Default patterns for common secrets.
+*
+* Covers:
+* - API keys (OpenAI, Anthropic, GitHub, etc.)
+* - Auth headers (Bearer tokens)
+* - Connection strings (database URLs)
+* - Password fields in various formats
+*/
+declare const DEFAULT_PATTERNS: RegExp[];
+/**
+* Default sensitive key names.
+*
+* Object keys matching these (case-insensitive) will have their values redacted.
+*/
+declare const DEFAULT_SENSITIVE_KEYS: string[];
+/**
+* Create a redactor instance with the given configuration.
+*
+* @param config - Redactor configuration
+* @returns Configured Redactor instance
+*
+* @example
+* ```typescript
+* const redactor = createRedactor({
+*   patterns: [...DEFAULT_PATTERNS],
+*   keys: [...DEFAULT_SENSITIVE_KEYS],
+* });
+*
+* const safe = redactor.redact({
+*   user: "alice",
+*   apiKey: "sk-abc123...",
+* });
+* // { user: "alice", apiKey: "[REDACTED]" }
+* ```
+*/
+declare function createRedactor(config: RedactorConfig): Redactor;
+import { Result as Result7 } from "better-result";
+/**
+* Array type guaranteed to have at least one element.
+*/
+type NonEmptyArray<T> = [T, ...T[]];
+/**
+* Type guard for NonEmptyArray.
+*/
+declare const isNonEmptyArray: <T>(arr: readonly T[]) => arr is NonEmptyArray<T>;
+/**
+* Assert a value is defined (not null or undefined).
+* Returns Result instead of throwing.
+*/
+declare const assertDefined: <T>(value: T | null | undefined, message?: string) => Result7<T, InstanceType<typeof AssertionError>>;
+/**
+* Assert array has at least one element.
+* Returns NonEmptyArray on success.
+*/
+declare const assertNonEmpty: <T>(arr: readonly T[], message?: string) => Result7<NonEmptyArray<T>, InstanceType<typeof AssertionError>>;
+/**
+* Assert value matches a predicate.
+* Supports type guard predicates for narrowing.
+*/
+declare function assertMatches<
+	T,
+	U extends T
+>(value: T, predicate: (v: T) => v is U, message?: string): Result7<U, InstanceType<typeof AssertionError>>;
+declare function assertMatches<T>(value: T, predicate: (v: T) => boolean, message?: string): Result7<T, InstanceType<typeof AssertionError>>;
+/**
+* Backoff strategy configuration options
+*/
+interface BackoffOptions {
+	/** Base delay in milliseconds (default: 100) */
+	baseDelayMs?: number;
+	/** Maximum delay cap in milliseconds (default: 30000) */
+	maxDelayMs?: number;
+	/** Backoff strategy (default: "exponential") */
+	strategy?: "linear" | "exponential" | "constant";
+	/** Whether to add jitter to prevent thundering herd (default: true) */
+	useJitter?: boolean;
+}
+/**
+* Determines if an error is potentially recoverable.
+*
+* Recoverable errors might succeed on retry or with user intervention.
+* This includes transient failures (network, timeout), rate limiting,
+* and optimistic lock conflicts.
+*
+* @param error - Error object with category property
+* @returns True if the error might be recoverable
+*
+* @example
+* ```typescript
+* import { isRecoverable, NetworkError } from '@outfitter/contracts';
+*
+* const networkError = new NetworkError({ message: "Connection refused" });
+* console.log(isRecoverable(networkError)); // true
+*
+* const validationError = new ValidationError({ message: "Invalid input" });
+* console.log(isRecoverable(validationError)); // false
+* ```
+*/
+declare const isRecoverable: (error: {
+	readonly category: ErrorCategory;
+}) => boolean;
+/**
+* Determines if an error should trigger automatic retry.
+*
+* More restrictive than isRecoverable - only transient failures that
+* are good candidates for immediate retry without user intervention.
+*
+* Retryable categories:
+* - network: Connection issues may be temporary
+* - timeout: May succeed with another attempt
+*
+* NOT retryable (even though recoverable):
+* - rate_limit: Should respect retryAfterSeconds header
+* - conflict: May need user to resolve the conflict
+*
+* @param error - Error object with category property
+* @returns True if the operation should be automatically retried
+*
+* @example
+* ```typescript
+* import { isRetryable, TimeoutError } from '@outfitter/contracts';
+*
+* const timeout = new TimeoutError({
+*   message: "Operation timed out",
+*   operation: "fetch",
+*   timeoutMs: 5000,
+* });
+* console.log(isRetryable(timeout)); // true
+*
+* const rateLimitError = new RateLimitError({ message: "Rate limit exceeded" });
+* console.log(isRetryable(rateLimitError)); // false (use retryAfterSeconds)
+* ```
+*/
+declare const isRetryable2: (error: {
+	readonly category: ErrorCategory;
+}) => boolean;
+/**
+* Calculate appropriate backoff delay for retry.
+*
+* Supports three strategies:
+* - exponential (default): delay = baseDelayMs * 2^attempt
+* - linear: delay = baseDelayMs * (attempt + 1)
+* - constant: delay = baseDelayMs
+*
+* By default, adds jitter (+/-10%) to prevent thundering herd problems
+* when multiple clients retry simultaneously.
+*
+* @param attempt - The attempt number (0-indexed)
+* @param options - Backoff configuration options
+* @returns Delay in milliseconds before next retry
+*
+* @example
+* ```typescript
+* import { getBackoffDelay } from '@outfitter/contracts';
+*
+* // Exponential backoff (default): 100ms, 200ms, 400ms, 800ms...
+* const delay = getBackoffDelay(2); // ~400ms (with jitter)
+*
+* // Linear backoff: 100ms, 200ms, 300ms...
+* const linearDelay = getBackoffDelay(2, { strategy: "linear" }); // ~300ms
+*
+* // Constant delay: 500ms, 500ms, 500ms...
+* const constantDelay = getBackoffDelay(2, {
+*   strategy: "constant",
+*   baseDelayMs: 500,
+* }); // ~500ms
+*
+* // No jitter for deterministic timing
+* const exactDelay = getBackoffDelay(2, { useJitter: false }); // exactly 400ms
+* ```
+*/
+declare const getBackoffDelay: (attempt: number, options?: BackoffOptions) => number;
+/**
+* Convenience function combining retryability check with attempt limit.
+*
+* Returns true only if:
+* 1. The error is retryable (network or timeout)
+* 2. We haven't exceeded maxAttempts
+*
+* @param error - Error object with category property
+* @param attempt - Current attempt number (0-indexed)
+* @param maxAttempts - Maximum number of retry attempts (default: 3)
+* @returns True if the operation should be retried
+*
+* @example
+* ```typescript
+* import { shouldRetry, NetworkError } from '@outfitter/contracts';
+*
+* const error = new NetworkError({ message: "Connection timeout" });
+*
+* // First attempt failed
+* console.log(shouldRetry(error, 0)); // true (will retry)
+*
+* // Fourth attempt failed (exceeded default max of 3)
+* console.log(shouldRetry(error, 3)); // false (no more retries)
+*
+* // Custom max attempts
+* console.log(shouldRetry(error, 4, 5)); // true (under custom limit)
+* ```
+*/
+declare const shouldRetry: (error: {
+	readonly category: ErrorCategory;
+}, attempt: number, maxAttempts?: number) => boolean;
+import { Result as Result8 } from "better-result";
+/**
+* Extract value from Ok, or compute default from error.
+*
+* Unlike `unwrapOr`, the default is computed lazily only on Err.
+* This is useful when the default value is expensive to compute
+* and should only be evaluated when needed.
+*
+* @param result - The Result to unwrap
+* @param defaultFn - Function to compute default value from error
+* @returns The success value or computed default
+*
+* @example
+* ```typescript
+* const result = Result.err("not found");
+* const value = unwrapOrElse(result, (error) => {
+*   console.log("Computing expensive default due to:", error);
+*   return expensiveComputation();
+* });
+* ```
+*/
+declare const unwrapOrElse: <
+	T,
+	E
+>(result: Result8<T, E>, defaultFn: (error: E) => T) => T;
+/**
+* Return first Ok, or fallback if first is Err.
+*
+* Useful for trying alternative operations - if the first fails,
+* fall back to an alternative Result.
+*
+* @param result - The primary Result to try
+* @param fallback - The fallback Result if primary is Err
+* @returns First Ok result, or fallback
+*
+* @example
+* ```typescript
+* const primary = parseFromCache(key);
+* const fallback = parseFromNetwork(key);
+* const result = orElse(primary, fallback);
+* ```
+*/
+declare const orElse: <
+	T,
+	E,
+	F
+>(result: Result8<T, E>, fallback: Result8<T, F>) => Result8<T, F>;
+/**
+* Combine two Results into a tuple Result.
+*
+* Returns first error if either fails, evaluated left-to-right.
+* Useful for combining independent operations that must all succeed.
+*
+* @param r1 - First Result
+* @param r2 - Second Result
+* @returns Result containing tuple of both values, or first error
+*
+* @example
+* ```typescript
+* const user = fetchUser(id);
+* const settings = fetchSettings(id);
+* const combined = combine2(user, settings);
+*
+* if (combined.isOk()) {
+*   const [userData, userSettings] = combined.value;
+* }
+* ```
+*/
+declare const combine2: <
+	T1,
+	T2,
+	E
+>(r1: Result8<T1, E>, r2: Result8<T2, E>) => Result8<[T1, T2], E>;
+/**
+* Combine three Results into a tuple Result.
+*
+* Returns first error if any fails, evaluated left-to-right.
+* Useful for combining independent operations that must all succeed.
+*
+* @param r1 - First Result
+* @param r2 - Second Result
+* @param r3 - Third Result
+* @returns Result containing tuple of all values, or first error
+*
+* @example
+* ```typescript
+* const user = fetchUser(id);
+* const settings = fetchSettings(id);
+* const permissions = fetchPermissions(id);
+* const combined = combine3(user, settings, permissions);
+*
+* if (combined.isOk()) {
+*   const [userData, userSettings, userPermissions] = combined.value;
+* }
+* ```
+*/
+declare const combine3: <
+	T1,
+	T2,
+	T3,
+	E
+>(r1: Result8<T1, E>, r2: Result8<T2, E>, r3: Result8<T3, E>) => Result8<[T1, T2, T3], E>;
+import { TaggedErrorClass as TaggedErrorClass2 } from "better-result";
+import { Result as Result9, TaggedError } from "better-result";
+export { withTimeout, validateInput, unwrapOrElse, toHttpResponse, toEnvelope, statusCodeMap, shouldRetry, serializeError, safeStringify, safeParse, retry, orElse, isRetryable2 as isRetryable, isRecoverable, isNonEmptyArray, getStatusCode, getExitCode, getBackoffDelay, getActionsForSurface, generateRequestId, exitCodeMap, deserializeError, defineAction, createValidator, createRedactor, createContext, createActionRegistry, combine3, combine2, capabilityAll, capability, assertNonEmpty, assertMatches, assertDefined, ValidationError, TimeoutOptions, TimeoutError, TaggedErrorClass2 as TaggedErrorClass, TaggedError, SyncHandler, SuccessEnvelope, StorageError, StorageAdapter, SerializedError, SerializeErrorOptions, SearchResult, SearchOptions, RetryOptions, Result9 as Result, ResolvedConfig, RedactorConfig, Redactor, RedactionEvent, RedactionCallback, RateLimitError, PermissionError, PaginationMeta, OutfitterError, NotFoundError, NonEmptyArray, NetworkError, Logger, KitErrorProps, InternalError, IndexStats, IndexError, IndexAdapter, HttpResponse, HttpMethod, HandlerContext, Handler, ErrorEnvelope, ErrorCategory, EnvelopeMeta, Envelope, DEFAULT_SENSITIVE_KEYS, DEFAULT_REGISTRY_SURFACES, DEFAULT_PATTERNS, DEFAULT_ACTION_SURFACES, CreateContextOptions, ConflictError, CapabilitySurface, CancelledError, CacheError, CacheAdapter, CAPABILITY_SURFACES, BackoffOptions, AuthError, AuthAdapter, AssertionError, AnyKitError, AnyActionSpec, AdapterAuthError, ActionTrpcSpec, ActionSurface, ActionSpec, ActionRegistry, ActionMcpSpec, ActionCliSpec, ActionCliOption, ActionCliInputContext, ActionCapability, ActionApiSpec, ACTION_SURFACES, ACTION_CAPABILITIES };