@outfitter/contracts 0.1.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Result/Error patterns, error taxonomy, handler contracts, and shared interfaces
 
 ## Status
 
-**Scaffold** - Types and interfaces defined, implementations pending.
+**Active** - Stable core contracts with active feature development.
 
 ## Installation
 
@@ -36,7 +36,7 @@ import {
 // Define a handler
 const getNote: Handler<{ id: string }, Note, NotFoundError> = async (input, ctx) => {
   const note = await db.notes.find(input.id);
-  if (!note) return Result.err(new NotFoundError("note", input.id));
+  if (!note) return Result.err(NotFoundError.create("note", input.id));
   return Result.ok(note);
 };
 
@@ -45,6 +45,45 @@ const ctx = createContext({ logger, config });
 const result = await getNote({ id: "abc123" }, ctx);
 ```
 
+## Error Factory Reference
+
+All error classes provide a static `create()` factory method that generates a consistent message from structured parameters. Use `create()` for structured errors and the constructor for custom messages.
+
+| Error Class | `create()` Signature | Generated Message |
+|---|---|---|
+| `ValidationError` | `create(field, reason, context?)` | `"email: format invalid"` |
+| `ValidationError` | `fromMessage(message, context?)` | *(your message as-is)* |
+| `AmbiguousError` | `create(what, candidates, context?)` | `"Ambiguous heading: 2 matches found"` |
+| `NotFoundError` | `create(resourceType, resourceId, context?)` | `"note not found: abc123"` |
+| `AlreadyExistsError` | `create(resourceType, resourceId, context?)` | `"file already exists: notes/meeting.md"` |
+| `ConflictError` | `create(message, context?)` | *(your message as-is)* |
+| `PermissionError` | `create(message, context?)` | *(your message as-is)* |
+| `TimeoutError` | `create(operation, timeoutMs)` | `"database query timed out after 5000ms"` |
+| `RateLimitError` | `create(message, retryAfterSeconds?)` | *(your message as-is)* |
+| `NetworkError` | `create(message, context?)` | *(your message as-is)* |
+| `InternalError` | `create(message, context?)` | *(your message as-is)* |
+| `AuthError` | `create(message, reason?)` | *(your message as-is)* |
+| `CancelledError` | `create(message)` | *(your message as-is)* |
+
+### Message Casing
+
+`create()` factories that auto-generate messages use **lowercase** `resourceType`:
+
+```typescript
+NotFoundError.create("piece", "abc123");
+// → "piece not found: abc123" (not "Piece not found: abc123")
+```
+
+If you need a capitalized message, use the constructor directly:
+
+```typescript
+new NotFoundError({
+  message: "Piece not found: abc123",
+  resourceType: "piece",
+  resourceId: "abc123",
+});
+```
+
 ## License
 
 MIT

package/dist/actions.d.ts

@@ -1,4 +1,5 @@
-import { ACTION_SURFACES, ActionApiSpec, ActionCliInputContext, ActionCliOption, ActionCliSpec, ActionMcpSpec, ActionRegistry, ActionSpec, ActionSurface, ActionTrpcSpec, AnyActionSpec, DEFAULT_REGISTRY_SURFACES, HttpMethod, createActionRegistry, defineAction } from "./shared/@outfitter/contracts-vtrf6rbx";
-import "./shared/@outfitter/contracts-yp3derbe";
-import "./shared/@outfitter/contracts-ev4a68sg";
+import { ACTION_SURFACES, ActionApiSpec, ActionCliInputContext, ActionCliOption, ActionCliSpec, ActionMcpSpec, ActionRegistry, ActionSpec, ActionSurface, ActionTrpcSpec, AnyActionSpec, DEFAULT_REGISTRY_SURFACES, HttpMethod, createActionRegistry, defineAction } from "./shared/@outfitter/contracts-sf1z80yc";
+import "./shared/@outfitter/contracts-ss9vjjft";
+import "./shared/@outfitter/contracts-r35bn9p6";
+import "./shared/@outfitter/contracts-2g8r01zf";
 export { defineAction, createActionRegistry, HttpMethod, DEFAULT_REGISTRY_SURFACES, AnyActionSpec, ActionTrpcSpec, ActionSurface, ActionSpec, ActionRegistry, ActionMcpSpec, ActionCliSpec, ActionCliOption, ActionCliInputContext, ActionApiSpec, ACTION_SURFACES };

package/dist/assert/index.d.ts

@@ -1,3 +1,3 @@
-import { NonEmptyArray, assertDefined, assertMatches, assertNonEmpty, isNonEmptyArray } from "../shared/@outfitter/contracts-t3j7fba3";
-import "../shared/@outfitter/contracts-ev4a68sg";
+import { NonEmptyArray, assertDefined, assertMatches, assertNonEmpty, isNonEmptyArray } from "../shared/@outfitter/contracts-18vcxecr";
+import "../shared/@outfitter/contracts-r35bn9p6";
 export { isNonEmptyArray, assertNonEmpty, assertMatches, assertDefined, NonEmptyArray };

package/dist/assert/index.js

@@ -4,8 +4,8 @@ import {
   assertMatches,
   assertNonEmpty,
   isNonEmptyArray
-} from "../shared/@outfitter/contracts-d1thk8cv.js";
-import"../shared/@outfitter/contracts-jhsgc85s.js";
+} from "../shared/@outfitter/contracts-cp5c6dws.js";
+import"../shared/@outfitter/contracts-phjhz5q3.js";
 export {
   isNonEmptyArray,
   assertNonEmpty,

package/dist/context.d.ts

@@ -1,4 +1,5 @@
-import { CreateContextOptions, createContext, generateRequestId } from "./shared/@outfitter/contracts-wwkk3j4m";
-import "./shared/@outfitter/contracts-yp3derbe";
-import "./shared/@outfitter/contracts-ev4a68sg";
+import { CreateContextOptions, createContext, generateRequestId } from "./shared/@outfitter/contracts-25bkj17f";
+import "./shared/@outfitter/contracts-ss9vjjft";
+import "./shared/@outfitter/contracts-r35bn9p6";
+import "./shared/@outfitter/contracts-2g8r01zf";
 export { generateRequestId, createContext, CreateContextOptions };

package/dist/context.js

@@ -2,7 +2,7 @@
 import {
   createContext,
   generateRequestId
-} from "./shared/@outfitter/contracts-y8qg2nvz.js";
+} from "./shared/@outfitter/contracts-agmt8915.js";
 export {
   generateRequestId,
   createContext

package/dist/envelope.d.ts

@@ -1,3 +1,3 @@
-import { Envelope, EnvelopeMeta, ErrorEnvelope, HttpResponse, PaginationMeta, SuccessEnvelope, toEnvelope, toHttpResponse } from "./shared/@outfitter/contracts-q9tjk2zp";
-import "./shared/@outfitter/contracts-ev4a68sg";
+import { Envelope, EnvelopeMeta, ErrorEnvelope, HttpResponse, PaginationMeta, SuccessEnvelope, toEnvelope, toHttpResponse } from "./shared/@outfitter/contracts-jggbn5tn";
+import "./shared/@outfitter/contracts-r35bn9p6";
 export { toHttpResponse, toEnvelope, SuccessEnvelope, PaginationMeta, HttpResponse, ErrorEnvelope, EnvelopeMeta, Envelope };

package/dist/envelope.js

@@ -2,11 +2,11 @@
 import {
   toEnvelope,
   toHttpResponse
-} from "./shared/@outfitter/contracts-chnm7kvm.js";
-import"./shared/@outfitter/contracts-dbpj0b4k.js";
+} from "./shared/@outfitter/contracts-btg89x4h.js";
+import"./shared/@outfitter/contracts-5k6q4n48.js";
+import"./shared/@outfitter/contracts-agmt8915.js";
+import"./shared/@outfitter/contracts-phjhz5q3.js";
 import"./shared/@outfitter/contracts-s15x2rs4.js";
-import"./shared/@outfitter/contracts-y8qg2nvz.js";
-import"./shared/@outfitter/contracts-jhsgc85s.js";
 export {
   toHttpResponse,
   toEnvelope

package/dist/errors.d.ts

@@ -1,2 +1,2 @@
-import { AnyKitError, AssertionError, AuthError, CancelledError, ConflictError, ERROR_CODES, ErrorCategory, ErrorCode, InternalError, KitErrorProps, NetworkError, NotFoundError, OutfitterError, PermissionError, RateLimitError, SerializedError, TimeoutError, ValidationError, exitCodeMap, getExitCode, getStatusCode, statusCodeMap } from "./shared/@outfitter/contracts-ev4a68sg";
-export { statusCodeMap, getStatusCode, getExitCode, exitCodeMap, ValidationError, TimeoutError, SerializedError, RateLimitError, PermissionError, OutfitterError, NotFoundError, NetworkError, KitErrorProps, InternalError, ErrorCode, ErrorCategory, ERROR_CODES, ConflictError, CancelledError, AuthError, AssertionError, AnyKitError };
+import { AlreadyExistsError, AmbiguousError, AnyKitError, AssertionError, AuthError, CancelledError, ConflictError, ERROR_CODES, ErrorCategory, ErrorCode, InternalError, KitErrorProps, NetworkError, NotFoundError, OutfitterError, PermissionError, RateLimitError, SerializedError, TimeoutError, ValidationError, exitCodeMap, getExitCode, getStatusCode, statusCodeMap } from "./shared/@outfitter/contracts-r35bn9p6";
+export { statusCodeMap, getStatusCode, getExitCode, exitCodeMap, ValidationError, TimeoutError, SerializedError, RateLimitError, PermissionError, OutfitterError, NotFoundError, NetworkError, KitErrorProps, InternalError, ErrorCode, ErrorCategory, ERROR_CODES, ConflictError, CancelledError, AuthError, AssertionError, AnyKitError, AmbiguousError, AlreadyExistsError };

package/dist/errors.js

@@ -1,5 +1,7 @@
 // @bun
 import {
+  AlreadyExistsError,
+  AmbiguousError,
   AssertionError,
   AuthError,
   CancelledError,
@@ -16,7 +18,7 @@ import {
   getExitCode,
   getStatusCode,
   statusCodeMap
-} from "./shared/@outfitter/contracts-jhsgc85s.js";
+} from "./shared/@outfitter/contracts-phjhz5q3.js";
 export {
   statusCodeMap,
   getStatusCode,
@@ -33,5 +35,7 @@ export {
   ConflictError,
   CancelledError,
   AuthError,
-  AssertionError
+  AssertionError,
+  AmbiguousError,
+  AlreadyExistsError
 };

package/dist/handler.d.ts

@@ -1,3 +1,4 @@
-import { Handler, HandlerContext, Logger, ResolvedConfig, SyncHandler } from "./shared/@outfitter/contracts-yp3derbe";
-import "./shared/@outfitter/contracts-ev4a68sg";
+import { Handler, HandlerContext, ResolvedConfig, SyncHandler } from "./shared/@outfitter/contracts-ss9vjjft";
+import "./shared/@outfitter/contracts-r35bn9p6";
+import { Logger } from "./shared/@outfitter/contracts-2g8r01zf";
 export { SyncHandler, ResolvedConfig, Logger, HandlerContext, Handler };

package/dist/index.d.ts

@@ -1,18 +1,19 @@
+import { ACTION_SURFACES, ActionApiSpec, ActionCliInputContext, ActionCliOption, ActionCliSpec, ActionMcpSpec, ActionRegistry, ActionSpec, ActionSurface, ActionTrpcSpec, AnyActionSpec, DEFAULT_REGISTRY_SURFACES, HttpMethod, createActionRegistry, defineAction } from "./shared/@outfitter/contracts-sf1z80yc";
 import { ACTION_CAPABILITIES, ActionCapability, CAPABILITY_SURFACES, CapabilitySurface, DEFAULT_ACTION_SURFACES, capability, capabilityAll, getActionsForSurface } from "./shared/@outfitter/contracts-bb4hjt8g";
-import { DEFAULT_PATTERNS, DEFAULT_SENSITIVE_KEYS, RedactionCallback, RedactionEvent, Redactor, RedactorConfig, createRedactor } from "./shared/@outfitter/contracts-e70qdasg";
-import { BackoffOptions, getBackoffDelay, isRecoverable, isRetryable, shouldRetry } from "./shared/@outfitter/contracts-47aemgd3";
-import { ACTION_SURFACES, ActionApiSpec, ActionCliInputContext, ActionCliOption, ActionCliSpec, ActionMcpSpec, ActionRegistry, ActionSpec, ActionSurface, ActionTrpcSpec, AnyActionSpec, DEFAULT_REGISTRY_SURFACES, HttpMethod, createActionRegistry, defineAction } from "./shared/@outfitter/contracts-vtrf6rbx";
-import { RetryOptions, TimeoutOptions, retry, withTimeout } from "./shared/@outfitter/contracts-37891j7e";
+import { SerializeErrorOptions, deserializeError, safeParse, safeStringify, serializeError } from "./shared/@outfitter/contracts-j08e95jw";
+import { CreateContextOptions, createContext, generateRequestId } from "./shared/@outfitter/contracts-25bkj17f";
+import { NonEmptyArray, assertDefined, assertMatches, assertNonEmpty, isNonEmptyArray } from "./shared/@outfitter/contracts-18vcxecr";
 import "./shared/@outfitter/contracts-qaccq0gf";
-import { combine2, combine3, orElse, unwrapOrElse } from "./shared/@outfitter/contracts-109drsem";
-import { NonEmptyArray, assertDefined, assertMatches, assertNonEmpty, isNonEmptyArray } from "./shared/@outfitter/contracts-t3j7fba3";
+import { combine2, combine3, expect, orElse, unwrapOrElse } from "./shared/@outfitter/contracts-ar0etwtx";
+import { Envelope, EnvelopeMeta, ErrorEnvelope, HttpResponse, PaginationMeta, SuccessEnvelope, toEnvelope, toHttpResponse } from "./shared/@outfitter/contracts-jggbn5tn";
 import { AdapterAuthError, AuthAdapter, CacheAdapter, CacheError, IndexAdapter, IndexError, IndexStats, SearchOptions, SearchResult, StorageAdapter, StorageError } from "./shared/@outfitter/contracts-93dx53mt";
-import { Envelope, EnvelopeMeta, ErrorEnvelope, HttpResponse, PaginationMeta, SuccessEnvelope, toEnvelope, toHttpResponse } from "./shared/@outfitter/contracts-q9tjk2zp";
-import { SerializeErrorOptions, deserializeError, safeParse, safeStringify, serializeError } from "./shared/@outfitter/contracts-0taqjz0a";
-import { CreateContextOptions, createContext, generateRequestId } from "./shared/@outfitter/contracts-wwkk3j4m";
-import { Handler, HandlerContext, Logger, ResolvedConfig, SyncHandler } from "./shared/@outfitter/contracts-yp3derbe";
-import { createValidator, validateInput } from "./shared/@outfitter/contracts-g82822x1";
-import { AnyKitError, AssertionError, AuthError, CancelledError, ConflictError, ERROR_CODES, ErrorCategory, ErrorCode, InternalError, KitErrorProps, NetworkError, NotFoundError, OutfitterError, PermissionError, RateLimitError, SerializedError, TimeoutError, ValidationError, exitCodeMap, getExitCode, getStatusCode, statusCodeMap } from "./shared/@outfitter/contracts-ev4a68sg";
+import { BackoffOptions, getBackoffDelay, isRecoverable, isRetryable, shouldRetry } from "./shared/@outfitter/contracts-evxky148";
+import { RetryOptions, TimeoutOptions, retry, withTimeout } from "./shared/@outfitter/contracts-bdwg55c5";
+import { createValidator, validateInput } from "./shared/@outfitter/contracts-6j6z9dsd";
+import { Handler, HandlerContext, ResolvedConfig, SyncHandler } from "./shared/@outfitter/contracts-ss9vjjft";
+import { AlreadyExistsError, AmbiguousError, AnyKitError, AssertionError, AuthError, CancelledError, ConflictError, ERROR_CODES, ErrorCategory, ErrorCode, InternalError, KitErrorProps, NetworkError, NotFoundError, OutfitterError, PermissionError, RateLimitError, SerializedError, TimeoutError, ValidationError, exitCodeMap, getExitCode, getStatusCode, statusCodeMap } from "./shared/@outfitter/contracts-r35bn9p6";
+import { LogLevel, LogMetadata, LogMethod, Logger, LoggerAdapter, LoggerFactory, LoggerFactoryConfig, createLoggerFactory } from "./shared/@outfitter/contracts-2g8r01zf";
+import { DEFAULT_PATTERNS, DEFAULT_SENSITIVE_KEYS, RedactionCallback, RedactionEvent, Redactor, RedactorConfig, createRedactor } from "./shared/@outfitter/contracts-e70qdasg";
 import { TaggedErrorClass } from "better-result";
 import { Result, TaggedError } from "better-result";
-export { withTimeout, validateInput, unwrapOrElse, toHttpResponse, toEnvelope, statusCodeMap, shouldRetry, serializeError, safeStringify, safeParse, retry, orElse, 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, TaggedErrorClass, TaggedError, SyncHandler, SuccessEnvelope, StorageError, StorageAdapter, SerializedError, SerializeErrorOptions, SearchResult, SearchOptions, RetryOptions, Result, ResolvedConfig, RedactorConfig, Redactor, RedactionEvent, RedactionCallback, RateLimitError, PermissionError, PaginationMeta, OutfitterError, NotFoundError, NonEmptyArray, NetworkError, Logger, KitErrorProps, InternalError, IndexStats, IndexError, IndexAdapter, HttpResponse, HttpMethod, HandlerContext, Handler, ErrorEnvelope, ErrorCode, ErrorCategory, EnvelopeMeta, Envelope, ERROR_CODES, 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 };
+export { withTimeout, validateInput, unwrapOrElse, toHttpResponse, toEnvelope, statusCodeMap, shouldRetry, serializeError, safeStringify, safeParse, retry, orElse, isRetryable, isRecoverable, isNonEmptyArray, getStatusCode, getExitCode, getBackoffDelay, getActionsForSurface, generateRequestId, expect, exitCodeMap, deserializeError, defineAction, createValidator, createRedactor, createLoggerFactory, createContext, createActionRegistry, combine3, combine2, capabilityAll, capability, assertNonEmpty, assertMatches, assertDefined, ValidationError, TimeoutOptions, TimeoutError, TaggedErrorClass, TaggedError, SyncHandler, SuccessEnvelope, StorageError, StorageAdapter, SerializedError, SerializeErrorOptions, SearchResult, SearchOptions, RetryOptions, Result, ResolvedConfig, RedactorConfig, Redactor, RedactionEvent, RedactionCallback, RateLimitError, PermissionError, PaginationMeta, OutfitterError, NotFoundError, NonEmptyArray, NetworkError, LoggerFactoryConfig, LoggerFactory, LoggerAdapter, Logger, LogMethod, LogMetadata, LogLevel, KitErrorProps, InternalError, IndexStats, IndexError, IndexAdapter, HttpResponse, HttpMethod, HandlerContext, Handler, ErrorEnvelope, ErrorCode, ErrorCategory, EnvelopeMeta, Envelope, ERROR_CODES, 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, AmbiguousError, AlreadyExistsError, AdapterAuthError, ActionTrpcSpec, ActionSurface, ActionSpec, ActionRegistry, ActionMcpSpec, ActionCliSpec, ActionCliOption, ActionCliInputContext, ActionCapability, ActionApiSpec, ACTION_SURFACES, ACTION_CAPABILITIES };

package/dist/index.js

@@ -1,4 +1,10 @@
 // @bun
+import {
+  ACTION_SURFACES,
+  DEFAULT_REGISTRY_SURFACES,
+  createActionRegistry,
+  defineAction
+} from "./shared/@outfitter/contracts-q0v44kef.js";
 import {
   ACTION_CAPABILITIES,
   CAPABILITY_SURFACES,
@@ -8,58 +14,50 @@ import {
   getActionsForSurface
 } from "./shared/@outfitter/contracts-d0tq2adf.js";
 import {
-  getBackoffDelay,
-  isRecoverable,
-  isRetryable,
-  shouldRetry
-} from "./shared/@outfitter/contracts-4zaj7ejb.js";
-import {
-  ACTION_SURFACES,
-  DEFAULT_REGISTRY_SURFACES,
-  createActionRegistry,
-  defineAction
-} from "./shared/@outfitter/contracts-q0v44kef.js";
-import {
-  retry,
-  withTimeout
-} from "./shared/@outfitter/contracts-aq745b7n.js";
+  assertDefined,
+  assertMatches,
+  assertNonEmpty,
+  isNonEmptyArray
+} from "./shared/@outfitter/contracts-cp5c6dws.js";
 import"./shared/@outfitter/contracts-37gpc56f.js";
 import {
   combine2,
   combine3,
+  expect,
   orElse,
   unwrapOrElse
-} from "./shared/@outfitter/contracts-r06bafs8.js";
-import {
-  assertDefined,
-  assertMatches,
-  assertNonEmpty,
-  isNonEmptyArray
-} from "./shared/@outfitter/contracts-d1thk8cv.js";
+} from "./shared/@outfitter/contracts-zx72gyh1.js";
 import {
   toEnvelope,
   toHttpResponse
-} from "./shared/@outfitter/contracts-chnm7kvm.js";
+} from "./shared/@outfitter/contracts-btg89x4h.js";
 import {
   deserializeError,
   safeParse,
   safeStringify,
   serializeError
-} from "./shared/@outfitter/contracts-dbpj0b4k.js";
-import {
-  DEFAULT_PATTERNS,
-  DEFAULT_SENSITIVE_KEYS,
-  createRedactor
-} from "./shared/@outfitter/contracts-s15x2rs4.js";
+} from "./shared/@outfitter/contracts-5k6q4n48.js";
 import {
   createContext,
   generateRequestId
-} from "./shared/@outfitter/contracts-y8qg2nvz.js";
+} from "./shared/@outfitter/contracts-agmt8915.js";
+import {
+  getBackoffDelay,
+  isRecoverable,
+  isRetryable,
+  shouldRetry
+} from "./shared/@outfitter/contracts-4zaj7ejb.js";
+import {
+  retry,
+  withTimeout
+} from "./shared/@outfitter/contracts-r21yet6j.js";
 import {
   createValidator,
   validateInput
-} from "./shared/@outfitter/contracts-sf5p84cc.js";
+} from "./shared/@outfitter/contracts-0snpmkdt.js";
 import {
+  AlreadyExistsError,
+  AmbiguousError,
   AssertionError,
   AuthError,
   CancelledError,
@@ -76,7 +74,15 @@ import {
   getExitCode,
   getStatusCode,
   statusCodeMap
-} from "./shared/@outfitter/contracts-jhsgc85s.js";
+} from "./shared/@outfitter/contracts-phjhz5q3.js";
+import {
+  createLoggerFactory
+} from "./shared/@outfitter/contracts-sm6vak1a.js";
+import {
+  DEFAULT_PATTERNS,
+  DEFAULT_SENSITIVE_KEYS,
+  createRedactor
+} from "./shared/@outfitter/contracts-s15x2rs4.js";
 
 // packages/contracts/src/index.ts
 import { Result, TaggedError } from "better-result";
@@ -101,11 +107,13 @@ export {
   getBackoffDelay,
   getActionsForSurface,
   generateRequestId,
+  expect,
   exitCodeMap,
   deserializeError,
   defineAction,
   createValidator,
   createRedactor,
+  createLoggerFactory,
   createContext,
   createActionRegistry,
   combine3,
@@ -134,6 +142,8 @@ export {
   CAPABILITY_SURFACES,
   AuthError,
   AssertionError,
+  AmbiguousError,
+  AlreadyExistsError,
   ACTION_SURFACES,
   ACTION_CAPABILITIES
 };

package/dist/logging.d.ts

@@ -0,0 +1,2 @@
+import { LogLevel, LogMetadata, LogMethod, Logger, LoggerAdapter, LoggerFactory, LoggerFactoryConfig, createLoggerFactory } from "./shared/@outfitter/contracts-2g8r01zf";
+export { createLoggerFactory, LoggerFactoryConfig, LoggerFactory, LoggerAdapter, Logger, LogMethod, LogMetadata, LogLevel };

package/dist/logging.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  createLoggerFactory
+} from "./shared/@outfitter/contracts-sm6vak1a.js";
+export {
+  createLoggerFactory
+};

package/dist/recovery.d.ts

@@ -1,3 +1,3 @@
-import { BackoffOptions, getBackoffDelay, isRecoverable, isRetryable, shouldRetry } from "./shared/@outfitter/contracts-47aemgd3";
-import "./shared/@outfitter/contracts-ev4a68sg";
+import { BackoffOptions, getBackoffDelay, isRecoverable, isRetryable, shouldRetry } from "./shared/@outfitter/contracts-evxky148";
+import "./shared/@outfitter/contracts-r35bn9p6";
 export { shouldRetry, isRetryable, isRecoverable, getBackoffDelay, BackoffOptions };

package/dist/resilience.d.ts

@@ -1,3 +1,3 @@
-import { RetryOptions, TimeoutOptions, retry, withTimeout } from "./shared/@outfitter/contracts-37891j7e";
-import "./shared/@outfitter/contracts-ev4a68sg";
+import { RetryOptions, TimeoutOptions, retry, withTimeout } from "./shared/@outfitter/contracts-bdwg55c5";
+import "./shared/@outfitter/contracts-r35bn9p6";
 export { withTimeout, retry, TimeoutOptions, RetryOptions };

package/dist/resilience.js

@@ -2,8 +2,8 @@
 import {
   retry,
   withTimeout
-} from "./shared/@outfitter/contracts-aq745b7n.js";
-import"./shared/@outfitter/contracts-jhsgc85s.js";
+} from "./shared/@outfitter/contracts-r21yet6j.js";
+import"./shared/@outfitter/contracts-phjhz5q3.js";
 export {
   withTimeout,
   retry

package/dist/result/index.d.ts

@@ -1,3 +1,3 @@
 import "../shared/@outfitter/contracts-qaccq0gf";
-import { combine2, combine3, orElse, unwrapOrElse } from "../shared/@outfitter/contracts-109drsem";
-export { unwrapOrElse, orElse, combine3, combine2 };
+import { combine2, combine3, expect, orElse, unwrapOrElse } from "../shared/@outfitter/contracts-ar0etwtx";
+export { unwrapOrElse, orElse, expect, combine3, combine2 };

package/dist/result/index.js

@@ -3,12 +3,14 @@ import"../shared/@outfitter/contracts-37gpc56f.js";
 import {
   combine2,
   combine3,
+  expect,
   orElse,
   unwrapOrElse
-} from "../shared/@outfitter/contracts-r06bafs8.js";
+} from "../shared/@outfitter/contracts-zx72gyh1.js";
 export {
   unwrapOrElse,
   orElse,
+  expect,
   combine3,
   combine2
 };

package/dist/result/utilities.d.ts

@@ -1,2 +1,2 @@
-import { combine2, combine3, orElse, unwrapOrElse } from "../shared/@outfitter/contracts-109drsem";
-export { unwrapOrElse, orElse, combine3, combine2 };
+import { combine2, combine3, expect, orElse, unwrapOrElse } from "../shared/@outfitter/contracts-ar0etwtx";
+export { unwrapOrElse, orElse, expect, combine3, combine2 };

package/dist/result/utilities.js

@@ -2,12 +2,14 @@
 import {
   combine2,
   combine3,
+  expect,
   orElse,
   unwrapOrElse
-} from "../shared/@outfitter/contracts-r06bafs8.js";
+} from "../shared/@outfitter/contracts-zx72gyh1.js";
 export {
   unwrapOrElse,
   orElse,
+  expect,
   combine3,
   combine2
 };

package/dist/serialization.d.ts

@@ -1,3 +1,3 @@
-import { SerializeErrorOptions, deserializeError, safeParse, safeStringify, serializeError } from "./shared/@outfitter/contracts-0taqjz0a";
-import "./shared/@outfitter/contracts-ev4a68sg";
+import { SerializeErrorOptions, deserializeError, safeParse, safeStringify, serializeError } from "./shared/@outfitter/contracts-j08e95jw";
+import "./shared/@outfitter/contracts-r35bn9p6";
 export { serializeError, safeStringify, safeParse, deserializeError, SerializeErrorOptions };

package/dist/serialization.js

@@ -4,9 +4,9 @@ import {
   safeParse,
   safeStringify,
   serializeError
-} from "./shared/@outfitter/contracts-dbpj0b4k.js";
+} from "./shared/@outfitter/contracts-5k6q4n48.js";
+import"./shared/@outfitter/contracts-phjhz5q3.js";
 import"./shared/@outfitter/contracts-s15x2rs4.js";
-import"./shared/@outfitter/contracts-jhsgc85s.js";
 export {
   serializeError,
   safeStringify,

package/dist/shared/@outfitter/{contracts-sf5p84cc.js → contracts-0snpmkdt.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   ValidationError
-} from "./contracts-jhsgc85s.js";
+} from "./contracts-phjhz5q3.js";
 
 // packages/contracts/src/validation.ts
 import { Result } from "better-result";

package/dist/shared/@outfitter/{contracts-t3j7fba3.d.ts → contracts-18vcxecr.d.ts}

@@ -1,4 +1,4 @@
-import { AssertionError } from "./contracts-ev4a68sg";
+import { AssertionError } from "./contracts-r35bn9p6";
 import { Result } from "better-result";
 /**
 * Array type guaranteed to have at least one element.

package/dist/shared/@outfitter/{contracts-wwkk3j4m.d.ts → contracts-25bkj17f.d.ts}

@@ -1,4 +1,5 @@
-import { HandlerContext, Logger, ResolvedConfig } from "./contracts-yp3derbe";
+import { HandlerContext, ResolvedConfig } from "./contracts-ss9vjjft";
+import { Logger } from "./contracts-2g8r01zf";
 /**
 * Options for creating a handler context.
 */

package/dist/shared/@outfitter/contracts-2g8r01zf.d.ts

@@ -0,0 +1,73 @@
+/**
+* Shared logging contracts for backend-agnostic logger integration.
+*
+* The `Logger` interface is the minimal surface required by handler contexts.
+* `LoggerAdapter` and `createLoggerFactory` allow runtime packages to plug in
+* backend-specific implementations while keeping transports backend-agnostic.
+*/
+/**
+* Log levels ordered from least to most severe.
+*
+* The special `silent` level disables logging output.
+*/
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
+/** Structured metadata attached to log messages. */
+type LogMetadata = Record<string, unknown>;
+/**
+* Message-first logger method with metadata-first overload for strict misuse
+* detection in TypeScript. Calling with metadata first intentionally resolves to
+* `never` for compile-time feedback.
+*/
+interface LogMethod {
+	(message: string, metadata?: LogMetadata): void;
+	(metadata: LogMetadata, message: string): never;
+}
+/**
+* Logger interface for handler contexts and cross-package contracts.
+*/
+interface Logger {
+	trace: LogMethod;
+	debug: LogMethod;
+	info: LogMethod;
+	warn: LogMethod;
+	error: LogMethod;
+	fatal: LogMethod;
+	child(context: LogMetadata): Logger;
+}
+/**
+* Configuration passed through the logger factory to backend adapters.
+*
+* `backend` carries adapter-specific configuration in a strongly typed way.
+*/
+interface LoggerFactoryConfig<TBackendOptions = unknown> {
+	/** Logger category/name identifying the source (e.g., "cli", "mcp") */
+	name: string;
+	/** Minimum level to emit */
+	level?: LogLevel;
+	/** Static context attached to every emitted record */
+	context?: LogMetadata;
+	/** Adapter-specific backend options */
+	backend?: TBackendOptions;
+}
+/**
+* Backend adapter contract used by the logger factory.
+*
+* Runtime packages provide concrete adapters (for example logtape or custom
+* implementations) behind this contract.
+*/
+interface LoggerAdapter<TBackendOptions = unknown> {
+	createLogger(config: LoggerFactoryConfig<TBackendOptions>): Logger;
+	flush?(): Promise<void>;
+}
+/**
+* Backend-agnostic logger factory surface consumed by CLI/MCP runtime code.
+*/
+interface LoggerFactory<TBackendOptions = unknown> {
+	createLogger(config: LoggerFactoryConfig<TBackendOptions>): Logger;
+	flush(): Promise<void>;
+}
+/**
+* Create a logger factory from a backend adapter implementation.
+*/
+declare function createLoggerFactory<TBackendOptions = unknown>(adapter: LoggerAdapter<TBackendOptions>): LoggerFactory<TBackendOptions>;
+export { LogLevel, LogMetadata, LogMethod, Logger, LoggerFactoryConfig, LoggerAdapter, LoggerFactory, createLoggerFactory };