@outfitter/contracts 0.2.0 → 0.4.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-zyanj0gf";
-import "./shared/@outfitter/contracts-amd2ykn8";
-import "./shared/@outfitter/contracts-5hr9pdcq";
+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-jbhbyhtt";
-import "../shared/@outfitter/contracts-5hr9pdcq";
+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-2f3khqcc.js";
-import"../shared/@outfitter/contracts-0cj49e1a.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-t68dwjbk";
-import "./shared/@outfitter/contracts-amd2ykn8";
-import "./shared/@outfitter/contracts-5hr9pdcq";
+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/envelope.d.ts

@@ -1,3 +1,3 @@
-import { Envelope, EnvelopeMeta, ErrorEnvelope, HttpResponse, PaginationMeta, SuccessEnvelope, toEnvelope, toHttpResponse } from "./shared/@outfitter/contracts-k0rhaye3";
-import "./shared/@outfitter/contracts-5hr9pdcq";
+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-rtsa2s0f.js";
-import"./shared/@outfitter/contracts-agvdgx9j.js";
-import"./shared/@outfitter/contracts-s15x2rs4.js";
+} from "./shared/@outfitter/contracts-btg89x4h.js";
+import"./shared/@outfitter/contracts-5k6q4n48.js";
 import"./shared/@outfitter/contracts-agmt8915.js";
-import"./shared/@outfitter/contracts-0cj49e1a.js";
+import"./shared/@outfitter/contracts-phjhz5q3.js";
+import"./shared/@outfitter/contracts-s15x2rs4.js";
 export {
   toHttpResponse,
   toEnvelope

package/dist/errors.d.ts

@@ -1,2 +1,2 @@
-import { 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-5hr9pdcq";
-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 };
+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,6 @@
 // @bun
 import {
+  AlreadyExistsError,
   AmbiguousError,
   AssertionError,
   AuthError,
@@ -17,7 +18,7 @@ import {
   getExitCode,
   getStatusCode,
   statusCodeMap
-} from "./shared/@outfitter/contracts-0cj49e1a.js";
+} from "./shared/@outfitter/contracts-phjhz5q3.js";
 export {
   statusCodeMap,
   getStatusCode,
@@ -35,5 +36,6 @@ export {
   CancelledError,
   AuthError,
   AssertionError,
-  AmbiguousError
+  AmbiguousError,
+  AlreadyExistsError
 };

package/dist/handler.d.ts

@@ -1,3 +1,4 @@
-import { Handler, HandlerContext, Logger, ResolvedConfig, SyncHandler } from "./shared/@outfitter/contracts-amd2ykn8";
-import "./shared/@outfitter/contracts-5hr9pdcq";
+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,20 @@
-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-md2mvvyt";
-import { ACTION_SURFACES, ActionApiSpec, ActionCliInputContext, ActionCliOption, ActionCliSpec, ActionMcpSpec, ActionRegistry, ActionSpec, ActionSurface, ActionTrpcSpec, AnyActionSpec, DEFAULT_REGISTRY_SURFACES, HttpMethod, createActionRegistry, defineAction } from "./shared/@outfitter/contracts-zyanj0gf";
-import { RetryOptions, TimeoutOptions, retry, withTimeout } from "./shared/@outfitter/contracts-r64j5rsm";
 import "./shared/@outfitter/contracts-qaccq0gf";
 import { combine2, combine3, expect, orElse, unwrapOrElse } from "./shared/@outfitter/contracts-ar0etwtx";
-import { NonEmptyArray, assertDefined, assertMatches, assertNonEmpty, isNonEmptyArray } from "./shared/@outfitter/contracts-jbhbyhtt";
+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 { SerializeErrorOptions, deserializeError, safeParse, safeStringify, serializeError } from "./shared/@outfitter/contracts-j08e95jw";
+import { JsonSchema, zodToJsonSchema } from "./shared/@outfitter/contracts-hbbxbwkt";
+import { CreateContextOptions, createContext, generateRequestId } from "./shared/@outfitter/contracts-25bkj17f";
+import { NonEmptyArray, assertDefined, assertMatches, assertNonEmpty, isNonEmptyArray } from "./shared/@outfitter/contracts-18vcxecr";
+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-k0rhaye3";
-import { SerializeErrorOptions, deserializeError, safeParse, safeStringify, serializeError } from "./shared/@outfitter/contracts-6atxbfag";
-import { CreateContextOptions, createContext, generateRequestId } from "./shared/@outfitter/contracts-t68dwjbk";
-import { Handler, HandlerContext, Logger, ResolvedConfig, SyncHandler } from "./shared/@outfitter/contracts-amd2ykn8";
-import { createValidator, validateInput } from "./shared/@outfitter/contracts-n9hb6hqt";
-import { 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-5hr9pdcq";
+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, expect, 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, AmbiguousError, AdapterAuthError, ActionTrpcSpec, ActionSurface, ActionSpec, ActionRegistry, ActionMcpSpec, ActionCliSpec, ActionCliOption, ActionCliInputContext, ActionCapability, ActionApiSpec, ACTION_SURFACES, ACTION_CAPABILITIES };
+export { zodToJsonSchema, 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, JsonSchema, 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,18 +1,12 @@
 // @bun
+import"./shared/@outfitter/contracts-37gpc56f.js";
 import {
-  ACTION_CAPABILITIES,
-  CAPABILITY_SURFACES,
-  DEFAULT_ACTION_SURFACES,
-  capability,
-  capabilityAll,
-  getActionsForSurface
-} from "./shared/@outfitter/contracts-d0tq2adf.js";
-import {
-  getBackoffDelay,
-  isRecoverable,
-  isRetryable,
-  shouldRetry
-} from "./shared/@outfitter/contracts-4zaj7ejb.js";
+  combine2,
+  combine3,
+  expect,
+  orElse,
+  unwrapOrElse
+} from "./shared/@outfitter/contracts-zx72gyh1.js";
 import {
   ACTION_SURFACES,
   DEFAULT_REGISTRY_SURFACES,
@@ -20,47 +14,52 @@ import {
   defineAction
 } from "./shared/@outfitter/contracts-q0v44kef.js";
 import {
-  retry,
-  withTimeout
-} from "./shared/@outfitter/contracts-pdk7s4t8.js";
-import"./shared/@outfitter/contracts-37gpc56f.js";
+  ACTION_CAPABILITIES,
+  CAPABILITY_SURFACES,
+  DEFAULT_ACTION_SURFACES,
+  capability,
+  capabilityAll,
+  getActionsForSurface
+} from "./shared/@outfitter/contracts-d0tq2adf.js";
 import {
-  combine2,
-  combine3,
-  expect,
-  orElse,
-  unwrapOrElse
-} from "./shared/@outfitter/contracts-zx72gyh1.js";
+  zodToJsonSchema
+} from "./shared/@outfitter/contracts-wfht4q2b.js";
 import {
   assertDefined,
   assertMatches,
   assertNonEmpty,
   isNonEmptyArray
-} from "./shared/@outfitter/contracts-2f3khqcc.js";
+} from "./shared/@outfitter/contracts-cp5c6dws.js";
 import {
   toEnvelope,
   toHttpResponse
-} from "./shared/@outfitter/contracts-rtsa2s0f.js";
+} from "./shared/@outfitter/contracts-btg89x4h.js";
 import {
   deserializeError,
   safeParse,
   safeStringify,
   serializeError
-} from "./shared/@outfitter/contracts-agvdgx9j.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-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-k2jdpbb6.js";
+} from "./shared/@outfitter/contracts-0snpmkdt.js";
 import {
+  AlreadyExistsError,
   AmbiguousError,
   AssertionError,
   AuthError,
@@ -78,11 +77,20 @@ import {
   getExitCode,
   getStatusCode,
   statusCodeMap
-} from "./shared/@outfitter/contracts-0cj49e1a.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";
 export {
+  zodToJsonSchema,
   withTimeout,
   validateInput,
   unwrapOrElse,
@@ -109,6 +117,7 @@ export {
   defineAction,
   createValidator,
   createRedactor,
+  createLoggerFactory,
   createContext,
   createActionRegistry,
   combine3,
@@ -138,6 +147,7 @@ export {
   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-md2mvvyt";
-import "./shared/@outfitter/contracts-5hr9pdcq";
+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-r64j5rsm";
-import "./shared/@outfitter/contracts-5hr9pdcq";
+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-pdk7s4t8.js";
-import"./shared/@outfitter/contracts-0cj49e1a.js";
+} from "./shared/@outfitter/contracts-r21yet6j.js";
+import"./shared/@outfitter/contracts-phjhz5q3.js";
 export {
   withTimeout,
   retry

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+import { JsonSchema, zodToJsonSchema } from "./shared/@outfitter/contracts-hbbxbwkt";
+export { zodToJsonSchema, JsonSchema };

package/dist/schema.js

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

package/dist/serialization.d.ts

@@ -1,3 +1,3 @@
-import { SerializeErrorOptions, deserializeError, safeParse, safeStringify, serializeError } from "./shared/@outfitter/contracts-6atxbfag";
-import "./shared/@outfitter/contracts-5hr9pdcq";
+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-agvdgx9j.js";
+} from "./shared/@outfitter/contracts-5k6q4n48.js";
+import"./shared/@outfitter/contracts-phjhz5q3.js";
 import"./shared/@outfitter/contracts-s15x2rs4.js";
-import"./shared/@outfitter/contracts-0cj49e1a.js";
 export {
   serializeError,
   safeStringify,

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

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

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

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

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

@@ -1,4 +1,5 @@
-import { HandlerContext, Logger, ResolvedConfig } from "./contracts-amd2ykn8";
+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 };

package/dist/shared/@outfitter/{contracts-agvdgx9j.js → contracts-5k6q4n48.js}

@@ -1,10 +1,6 @@
 // @bun
 import {
-  DEFAULT_PATTERNS,
-  DEFAULT_SENSITIVE_KEYS,
-  createRedactor
-} from "./contracts-s15x2rs4.js";
-import {
+  AlreadyExistsError,
   AmbiguousError,
   AssertionError,
   AuthError,
@@ -17,7 +13,12 @@ import {
   RateLimitError,
   TimeoutError,
   ValidationError
-} from "./contracts-0cj49e1a.js";
+} from "./contracts-phjhz5q3.js";
+import {
+  DEFAULT_PATTERNS,
+  DEFAULT_SENSITIVE_KEYS,
+  createRedactor
+} from "./contracts-s15x2rs4.js";
 
 // packages/contracts/src/serialization.ts
 import { Result } from "better-result";
@@ -26,6 +27,7 @@ var errorRegistry = {
   AmbiguousError,
   AssertionError,
   NotFoundError,
+  AlreadyExistsError,
   ConflictError,
   PermissionError,
   TimeoutError,
@@ -50,10 +52,22 @@ function extractContext(error) {
     }
     case "NotFoundError": {
       const nfe = error;
+      if (nfe.context !== undefined) {
+        Object.assign(context, nfe.context);
+      }
       context["resourceType"] = nfe.resourceType;
       context["resourceId"] = nfe.resourceId;
       break;
     }
+    case "AlreadyExistsError": {
+      const aee = error;
+      if (aee.context !== undefined) {
+        Object.assign(context, aee.context);
+      }
+      context["resourceType"] = aee.resourceType;
+      context["resourceId"] = aee.resourceId;
+      break;
+    }
     case "TimeoutError": {
       const te = error;
       context["operation"] = te.operation;
@@ -139,12 +153,30 @@ function deserializeError(data) {
       }
       return new ValidationError(props);
     }
-    case "NotFoundError":
-      return new NotFoundError({
+    case "NotFoundError": {
+      const props = {
         message: data.message,
         resourceType: context["resourceType"] ?? "unknown",
         resourceId: context["resourceId"] ?? "unknown"
-      });
+      };
+      const contextWithoutIdentity = Object.fromEntries(Object.entries(context).filter(([key]) => key !== "resourceType" && key !== "resourceId"));
+      if (Object.keys(contextWithoutIdentity).length > 0) {
+        props.context = contextWithoutIdentity;
+      }
+      return new NotFoundError(props);
+    }
+    case "AlreadyExistsError": {
+      const props = {
+        message: data.message,
+        resourceType: context["resourceType"] ?? "unknown",
+        resourceId: context["resourceId"] ?? "unknown"
+      };
+      const contextWithoutIdentity = Object.fromEntries(Object.entries(context).filter(([key]) => key !== "resourceType" && key !== "resourceId"));
+      if (Object.keys(contextWithoutIdentity).length > 0) {
+        props.context = contextWithoutIdentity;
+      }
+      return new AlreadyExistsError(props);
+    }
     case "ConflictError": {
       const props = {
         message: data.message

package/dist/shared/@outfitter/{contracts-n9hb6hqt.d.ts → contracts-6j6z9dsd.d.ts}

@@ -1,4 +1,4 @@
-import { ValidationError } from "./contracts-5hr9pdcq";
+import { ValidationError } from "./contracts-r35bn9p6";
 import { Result } from "better-result";
 import { z } from "zod";
 /**

package/dist/shared/@outfitter/{contracts-r64j5rsm.d.ts → contracts-bdwg55c5.d.ts}

@@ -1,4 +1,4 @@
-import { OutfitterError, TimeoutError } from "./contracts-5hr9pdcq";
+import { OutfitterError, TimeoutError } from "./contracts-r35bn9p6";
 import { Result } from "better-result";
 /**
 * Options for retry behavior.

package/dist/shared/@outfitter/{contracts-rtsa2s0f.js → contracts-btg89x4h.js}

@@ -1,13 +1,13 @@
 // @bun
 import {
   serializeError
-} from "./contracts-agvdgx9j.js";
+} from "./contracts-5k6q4n48.js";
 import {
   generateRequestId
 } from "./contracts-agmt8915.js";
 import {
   statusCodeMap
-} from "./contracts-0cj49e1a.js";
+} from "./contracts-phjhz5q3.js";
 
 // packages/contracts/src/envelope.ts
 function buildMeta(overrides) {