@smoothbricks/lmao 0.1.0

package/src/lib/defineOpContext.ts

@@ -0,0 +1,398 @@
+/**
+ * Op-Centric API for LMAO - Main Entry Point
+ *
+ * This is the factory function that creates the Op-centric API.
+ * All types are exported from './opContext/index.js'
+ *
+ * @example
+ * ```typescript
+ * import { defineOpContext, S, defineLogSchema } from '@smoothbricks/lmao';
+ *
+ * const { defineOp, defineOps } = defineOpContext({
+ *   logSchema: defineLogSchema({ userId: S.category() }),
+ *   ctx: { env: null as Env },
+ * });
+ *
+ * export const myHandler = defineOp('handler', async (ctx, req: Request) => {
+ *   ctx.tag.userId('user-123');
+ *   return ctx.ok({ status: 'ok' });
+ * });
+ * ```
+ */
+
+import {
+  type AnyOpGroup,
+  type AnyOpGroupPublic,
+  createDefineOp,
+  createDefineOps,
+  createOpGroup,
+  type DepsConfig,
+  type EffectiveSchema,
+  type FeatureFlagSchema,
+  isMappedOpGroup,
+  type OpContext,
+  type OpContextConfig,
+  type OpContextFactory,
+  RESERVED_CONTEXT_PROPS,
+  type ValidateUserContext,
+} from './opContext/index.js';
+import { LogSchema } from './schema/LogSchema.js';
+import { mergeWithSystemSchema, SYSTEM_SCHEMA_FIELD_NAMES } from './schema/systemSchema.js';
+import type { SchemaFields } from './schema/types.js';
+
+const EMPTY_FLAGS = Object.freeze({}) satisfies Record<string, never>;
+const EMPTY_DEPS = Object.freeze({}) satisfies Record<string, never>;
+const EMPTY_USER_CTX = Object.freeze({}) satisfies Record<string, never>;
+
+// =============================================================================
+// EFFECTIVE SCHEMA COMPUTATION
+// =============================================================================
+
+// isMappedOpGroup is imported from opContext/index.js
+
+/**
+ * Check if a field name is a system field (original or prefixed).
+ *
+ * System fields can appear as:
+ * - Original names: 'message', 'line', 'error_code', etc.
+ * - Prefixed names: 'http_message', 'db_line', 'auth_error_code', etc.
+ *
+ * @param fieldName - The field name to check
+ * @returns True if the field is a system field
+ */
+function isSystemField(fieldName: string): boolean {
+  // Check direct match first
+  if (SYSTEM_SCHEMA_FIELD_NAMES.has(fieldName)) {
+    return true;
+  }
+  // Check if it's a prefixed system field (e.g., 'http_message' -> 'message')
+  const underscoreIdx = fieldName.indexOf('_');
+  if (underscoreIdx !== -1) {
+    const suffix = fieldName.slice(underscoreIdx + 1);
+    if (SYSTEM_SCHEMA_FIELD_NAMES.has(suffix)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Filter out system schema fields from a schema.
+ *
+ * System fields (message, line, error_code, etc.) are merged into every logSchema
+ * by defineOpContext, but they should NOT be contributed when a dep is wired.
+ * Each app gets its own system fields via mergeWithSystemSchema.
+ *
+ * This function handles both original and prefixed system field names.
+ *
+ * @param fields - Schema fields to filter
+ * @returns Schema fields without system fields
+ */
+function filterOutSystemFields(fields: SchemaFields): SchemaFields {
+  const result: SchemaFields = {};
+  for (const key of Object.keys(fields)) {
+    if (!isSystemField(key)) {
+      result[key] = fields[key];
+    }
+  }
+  return result;
+}
+
+function isInternalOpGroup(dep: AnyOpGroupPublic): dep is AnyOpGroupPublic & AnyOpGroup {
+  return '_logSchema' in dep;
+}
+
+/**
+ * Get the schema fields contributed by a dep (OpGroup or MappedOpGroup).
+ *
+ * - For OpGroup: returns original schema fields (no transformation), excluding system fields
+ * - For MappedOpGroup: returns contributedSchema (after prefix/mapping)
+ *
+ * System fields (message, line, error_code, etc.) are always filtered out because
+ * each app gets its own system fields via mergeWithSystemSchema - deps should NOT
+ * contribute system fields.
+ *
+ * The returned object maps field names to their schema definitions.
+ *
+ * @param dep - An OpGroup or MappedOpGroup (with internal properties _logSchema, _contributedSchema)
+ * @returns The schema fields this dep contributes (user fields only, no system fields)
+ */
+function getContributedSchemaFromDep(dep: AnyOpGroupPublic): SchemaFields {
+  if (!isInternalOpGroup(dep)) {
+    throw new Error('Invalid op dependency: expected an OpGroup created by defineOps()');
+  }
+
+  if (isMappedOpGroup(dep)) {
+    // MappedOpGroup has _contributedSchema with mapped field names
+    // This already excludes null-mapped columns (they were dropped in buildContributedSchema)
+    // Filter out system fields in case the original schema included them
+    return filterOutSystemFields(dep._contributedSchema);
+  }
+  // OpGroup contributes its original schema fields, excluding system fields
+  return filterOutSystemFields(dep._logSchema.fields);
+}
+
+/**
+ * Compute the effective schema by merging app schema with all dep contributions.
+ *
+ * The effective schema is the union of:
+ * 1. App's own schema fields
+ * 2. All dep contributed fields (after prefix/mapping)
+ *
+ * Throws if multiple deps contribute the same field name (conflict detection).
+ *
+ * @param appFields - The app's own schema fields
+ * @param deps - The deps config (name -> OpGroup | MappedOpGroup)
+ * @returns Combined schema fields for the effective schema
+ * @throws Error if deps contribute conflicting field names
+ */
+function computeEffectiveSchema<T extends SchemaFields>(appFields: T): T;
+function computeEffectiveSchema<T extends SchemaFields, Deps extends DepsConfig>(
+  appFields: T,
+  deps: Deps,
+): EffectiveSchema<T, Deps>;
+function computeEffectiveSchema(appFields: SchemaFields, deps?: DepsConfig): SchemaFields {
+  if (!deps || Object.keys(deps).length === 0) {
+    return appFields;
+  }
+
+  // Start with app fields
+  const effective: SchemaFields = { ...appFields };
+
+  // Track which dep contributed each field for conflict detection
+  const fieldSource: Record<string, string> = {};
+  for (const fieldName of Object.keys(appFields)) {
+    fieldSource[fieldName] = 'app';
+  }
+
+  // Add each dep's contributed fields
+  for (const [depName, dep] of Object.entries(deps)) {
+    // Cast to AnyOpGroup to access internal properties (_logSchema, _contributedSchema)
+    // These exist at runtime but are hidden from public TypeScript interfaces
+    const contributed = getContributedSchemaFromDep(dep);
+
+    for (const [fieldName, fieldDef] of Object.entries(contributed)) {
+      // Check for conflict
+      if (fieldName in effective) {
+        const existingSource = fieldSource[fieldName];
+        throw new Error(
+          `Schema conflict: field '${fieldName}' contributed by dep '${depName}' ` +
+            `conflicts with field from '${existingSource}'. ` +
+            'Use .prefix() or .mapColumns() to resolve the conflict.',
+        );
+      }
+
+      effective[fieldName] = fieldDef;
+      fieldSource[fieldName] = depName;
+    }
+  }
+
+  return effective;
+}
+
+function buildOpContextFactory<
+  EffectiveFields extends SchemaFields,
+  FF extends FeatureFlagSchema,
+  Deps extends DepsConfig,
+  UserCtx extends Record<string, unknown>,
+>(
+  effectiveFields: EffectiveFields,
+  flags: FF,
+  deps: Deps,
+  ctxDefaults: UserCtx,
+): OpContextFactory<LogSchema<EffectiveFields>, FF, Deps, UserCtx> {
+  // Merge effective schema with system schema (message, line, error_code, etc.)
+  // System columns are always available on SpanBuffer regardless of user schema.
+  // Type parameter stays on the effective user/dependency schema because callers should infer
+  // only the public columns, while the runtime object still carries the merged system fields.
+  const mergedSchema = new LogSchema<EffectiveFields>(mergeWithSystemSchema(effectiveFields));
+
+  // Create a LogBinding for ops to use.
+  // NOTE: Stats are NO LONGER on LogBinding - they are on SpanBufferClass.stats (static property).
+  // This avoids sync bugs from having two stat objects and reduces per-instance memory.
+  // See agent-todo/opgroup-refactor.md lines 58-70, 525-547 for rationale.
+  const logBinding = {
+    logSchema: mergedSchema,
+    remappedViewClass: undefined,
+  };
+
+  // WHY: build the binding first so Ops created by defineOp carry it via _opContextBinding.
+  // This enables downstream consumers (defineAgentOps, OpRegistry) to extract the LMAO schema.
+  const opContextBinding = { logBinding, flags, ctxDefaults, deps };
+
+  // Create the defineOp and defineOps functions bound to this config.
+  // CRITICAL: Use mergedSchema (with system columns), not just the app schema, because
+  // runtime SpanBuffer generation needs the full row shape even though public factory.logSchema
+  // intentionally exposes only user/dependency columns.
+  const defineOp = createDefineOp<OpContext<typeof mergedSchema, FF, Deps, UserCtx>>({
+    logSchema: mergedSchema,
+    flags,
+    opContextBinding,
+  });
+
+  const defineOps = createDefineOps<OpContext<typeof mergedSchema, FF, Deps, UserCtx>>(
+    { logSchema: mergedSchema, flags, opContextBinding },
+    createOpGroup,
+  );
+
+  // Create effective schema LogSchema instance for factory.logSchema.
+  // This contains app fields + all dep contributed fields (user fields only, no system).
+  const effectiveLogSchema = new LogSchema(effectiveFields);
+
+  return {
+    logSchema: effectiveLogSchema,
+    flags,
+    logBinding,
+    ctxDefaults,
+    deps,
+    defineOp,
+    defineOps,
+  };
+}
+
+/**
+ * Define an Op context factory
+ *
+ * Creates a factory for defining Ops that share the same schema, deps, and context.
+ * This is the main entry point for the Op-centric API.
+ *
+ * @param config - Context configuration
+ * @returns OpContextFactory with defineOp, defineOps
+ *
+ * @example
+ * ```typescript
+ * import { defineOpContext } from '@smoothbricks/lmao';
+ *
+ * const { defineOp, defineOps } = defineOpContext({
+ *   logSchema: myLogSchema,
+ *   deps: {
+ *     http: httpOps.prefix('http'),
+ *     auth: authOps.prefix('auth'),
+ *   },
+ *   flags: myFeatureFlags,
+ *   ctx: {
+ *     env: null as CFWorkerEnv,     // Must provide at createTrace()
+ *     config: { retryCount: 3 },     // Has default
+ *   },
+ * });
+ *
+ * // Define ops
+ * export const myHandler = defineOp('handler', async (ctx, req: Request) => {
+ *   ctx.tag.method(req.method);
+ *   return ctx.ok({ status: 'ok' });
+ * });
+ *
+ * // Or batch define and export as OpGroup
+ * export const myOps = defineOps({
+ *   myHandler,
+ *   healthCheck: async (ctx) => ctx.ok({ healthy: true }),
+ * });
+ * ```
+ */
+export function defineOpContext<T extends SchemaFields>(
+  config: OpContextConfig<T, Record<string, never>, Record<string, never>, Record<string, never>>,
+): OpContextFactory<LogSchema<T>, Record<string, never>, Record<string, never>, Record<string, never>>;
+export function defineOpContext<T extends SchemaFields, const FF extends FeatureFlagSchema>(
+  config: OpContextConfig<T, FF, Record<string, never>, Record<string, never>> & { flags: FF },
+): OpContextFactory<LogSchema<T>, FF, Record<string, never>, Record<string, never>>;
+export function defineOpContext<T extends SchemaFields, UserCtx extends Record<string, unknown>>(
+  config: OpContextConfig<T, Record<string, never>, Record<string, never>, UserCtx> & {
+    ctx: ValidateUserContext<UserCtx>;
+  },
+): OpContextFactory<LogSchema<T>, Record<string, never>, Record<string, never>, UserCtx>;
+export function defineOpContext<
+  T extends SchemaFields,
+  const FF extends FeatureFlagSchema,
+  UserCtx extends Record<string, unknown>,
+>(
+  config: OpContextConfig<T, FF, Record<string, never>, UserCtx> & { flags: FF; ctx: ValidateUserContext<UserCtx> },
+): OpContextFactory<LogSchema<T>, FF, Record<string, never>, UserCtx>;
+export function defineOpContext<T extends SchemaFields, Deps extends DepsConfig>(
+  config: OpContextConfig<T, Record<string, never>, Deps, Record<string, never>> & { deps: Deps },
+): OpContextFactory<LogSchema<EffectiveSchema<T, Deps>>, Record<string, never>, Deps, Record<string, never>>;
+export function defineOpContext<T extends SchemaFields, const FF extends FeatureFlagSchema, Deps extends DepsConfig>(
+  config: OpContextConfig<T, FF, Deps, Record<string, never>> & { flags: FF; deps: Deps },
+): OpContextFactory<LogSchema<EffectiveSchema<T, Deps>>, FF, Deps, Record<string, never>>;
+export function defineOpContext<
+  T extends SchemaFields,
+  Deps extends DepsConfig,
+  UserCtx extends Record<string, unknown>,
+>(
+  config: OpContextConfig<T, Record<string, never>, Deps, UserCtx> & { deps: Deps; ctx: ValidateUserContext<UserCtx> },
+): OpContextFactory<LogSchema<EffectiveSchema<T, Deps>>, Record<string, never>, Deps, UserCtx>;
+export function defineOpContext<
+  T extends SchemaFields,
+  const FF extends FeatureFlagSchema,
+  Deps extends DepsConfig,
+  UserCtx extends Record<string, unknown>,
+>(
+  config: OpContextConfig<T, FF, Deps, UserCtx> & { flags: FF; deps: Deps; ctx: ValidateUserContext<UserCtx> },
+): OpContextFactory<LogSchema<EffectiveSchema<T, Deps>>, FF, Deps, UserCtx>;
+export function defineOpContext<
+  T extends SchemaFields,
+  const FF extends FeatureFlagSchema = Record<string, never>,
+  Deps extends DepsConfig = Record<string, never>,
+  UserCtx extends Record<string, unknown> = Record<string, never>,
+>(config: OpContextConfig<T, FF, Deps, UserCtx>) {
+  // Runtime validation: check for reserved property names in user context
+  if (config.ctx) {
+    const userKeys = Object.keys(config.ctx);
+    for (const key of userKeys) {
+      if (RESERVED_CONTEXT_PROPS.some((reservedProp) => reservedProp === key)) {
+        throw new Error(
+          `Cannot use '${key}' in ctx - it is a reserved SpanContext property. ` +
+            `Reserved: ${RESERVED_CONTEXT_PROPS.join(', ')}`,
+        );
+      }
+      // Check for underscore prefix (reserved for internal use)
+      if (key.startsWith('_')) {
+        throw new Error(`Cannot use '${key}' in ctx - properties starting with '_' are reserved for internal use.`);
+      }
+    }
+  }
+
+  // Compute effective schema by combining app schema with dep contributions.
+  // This merges app fields + all dep contributed fields (after prefix/mapping).
+  if (config.deps === undefined) {
+    const effectiveFields = computeEffectiveSchema(config.logSchema.fields);
+
+    if (config.flags === undefined) {
+      if (config.ctx === undefined) {
+        return buildOpContextFactory(effectiveFields, EMPTY_FLAGS, EMPTY_DEPS, EMPTY_USER_CTX);
+      }
+
+      return buildOpContextFactory(effectiveFields, EMPTY_FLAGS, EMPTY_DEPS, config.ctx);
+    }
+
+    if (config.ctx === undefined) {
+      return buildOpContextFactory(effectiveFields, config.flags, EMPTY_DEPS, EMPTY_USER_CTX);
+    }
+
+    return buildOpContextFactory(effectiveFields, config.flags, EMPTY_DEPS, config.ctx);
+  }
+
+  const effectiveFields = computeEffectiveSchema(config.logSchema.fields, config.deps);
+
+  if (config.flags === undefined) {
+    if (config.ctx === undefined) {
+      return buildOpContextFactory(effectiveFields, EMPTY_FLAGS, config.deps, EMPTY_USER_CTX);
+    }
+
+    return buildOpContextFactory(effectiveFields, EMPTY_FLAGS, config.deps, config.ctx);
+  }
+
+  if (config.ctx === undefined) {
+    return buildOpContextFactory(effectiveFields, config.flags, config.deps, EMPTY_USER_CTX);
+  }
+
+  return buildOpContextFactory(effectiveFields, config.flags, config.deps, config.ctx);
+}
+
+// Re-export everything from opContext for convenience
+export * from './opContext/index.js';
+
+// Re-export schema utilities
+export { S } from './schema/builder.js';
+export { defineFeatureFlags } from './schema/defineFeatureFlags.js';
+export { defineLogSchema } from './schema/defineLogSchema.js';
+export { LogSchema } from './schema/LogSchema.js';

package/src/lib/errors/Blocked.ts

@@ -0,0 +1,165 @@
+/**
+ * Blocked error - indicates an Op cannot proceed due to a temporary condition.
+ *
+ * A tagged error type for use with `result.isErr(Blocked)` to discriminate
+ * blocked states from other errors. Useful for retry logic and dependency waiting.
+ *
+ * Uses BlockedConfig for retry configuration (closure-based nextRetry).
+ *
+ * @example
+ * ```typescript
+ * import { defineOpContext, S, Err } from '@smoothbricks/lmao';
+ * import { Blocked } from '@smoothbricks/lmao/errors/Blocked';
+ *
+ * const { defineOp } = defineOpContext({
+ *   logSchema: { service: S.category() },
+ *   ctx: { env: null as Env },
+ * });
+ *
+ * const fetchData = defineOp('fetchData', async (ctx, service: string) => {
+ *   const health = await checkHealth(service);
+ *   if (!health.available) {
+ *     // Return Err with Blocked - can chain .with() for tags
+ *     return new Err(Blocked.service(service)).with({ service });
+ *   }
+ *   ctx.tag.service(service);
+ *   return ctx.ok(await doFetch(service));
+ * });
+ *
+ * // With closure-based retry (captures HTTP response context)
+ * const callApi = defineOp('callApi', async (ctx, url: string) => {
+ *   const response = await fetch(url);
+ *   if (response.status === 503) {
+ *     const retryAfterSec = parseInt(response.headers.get('Retry-After') ?? '5');
+ *     return new Err(Blocked.service('payment-api', {
+ *       maxAttempts: 5,
+ *       nextRetry: (attempt) => {
+ *         if (attempt === 1) return retryAfterSec * 1000;
+ *         return 5000 * Math.pow(2, attempt - 1);
+ *       },
+ *     }));
+ *   }
+ *   return ctx.ok(await response.json());
+ * });
+ *
+ * // Caller can discriminate blocked from other errors
+ * const result = await trace('fetch', fetchData, 'payment-api');
+ * if (result.isErr(Blocked)) {
+ *   // Handle temporary unavailability - retry, queue, etc.
+ *   console.log(`Blocked on ${result.error.reason.name}`);
+ * }
+ * ```
+ */
+
+import type { TaggedError } from '../result.js';
+
+/**
+ * Reason why an Op is blocked.
+ */
+export type BlockedReason =
+  | { readonly type: 'service'; readonly name: string }
+  | { readonly type: 'ended'; readonly target: string }
+  | { readonly type: 'index'; readonly indexName: string };
+
+/**
+ * Convert a blocked reason union into its display name.
+ */
+export function getBlockedReasonName(reason: BlockedReason): string {
+  switch (reason.type) {
+    case 'service':
+      return reason.name;
+    case 'ended':
+      return reason.target;
+    case 'index':
+      return reason.indexName;
+  }
+}
+
+/**
+ * Engine-level retry configuration for blocked operations.
+ *
+ * The nextRetry closure is powerful because it captures the Op's execution context.
+ * Each time the Op re-executes, it produces a new Blocked error with a new closure
+ * that may reference updated information (e.g., fresh Retry-After headers).
+ */
+export interface BlockedConfig {
+  /** Max canary retries before RetriesExhausted (default: 5) */
+  readonly maxAttempts?: number;
+  /** Closure returning delay in ms before next retry. Captures Op context. */
+  readonly nextRetry?: (attempt: number) => number;
+}
+
+type BlockedInspectView = {
+  _tag: 'Blocked';
+  reason: BlockedReason;
+  blockedConfig?: BlockedConfig;
+};
+
+type BlockedJsonView = {
+  _tag: 'Blocked';
+  reason: BlockedReason;
+  blockedConfig?: Omit<BlockedConfig, 'nextRetry'> & { nextRetry?: string };
+};
+
+export class Blocked extends Error implements TaggedError<'Blocked'> {
+  static readonly _tag = 'Blocked' as const;
+
+  get _tag(): 'Blocked' {
+    return 'Blocked';
+  }
+
+  /** Retry configuration */
+  readonly blockedConfig: BlockedConfig | undefined;
+
+  constructor(
+    /** The reason this Op is blocked */
+    readonly reason: BlockedReason,
+    /** Optional retry configuration */
+    config?: BlockedConfig,
+  ) {
+    super(`Blocked: ${getBlockedReasonName(reason)}`);
+    this.name = 'Blocked';
+    this.blockedConfig = config;
+  }
+
+  /** Create a Blocked error for a service being unavailable */
+  static service(name: string, config?: BlockedConfig): Blocked {
+    return new Blocked({ type: 'service', name }, config);
+  }
+
+  /** Create a Blocked error waiting for another execution to end */
+  static ended(target: string, config?: BlockedConfig): Blocked {
+    return new Blocked({ type: 'ended', target }, config);
+  }
+
+  /** Create a Blocked error for an index being rebuilt */
+  static index(indexName: string, config?: BlockedConfig): Blocked {
+    return new Blocked({ type: 'index', indexName }, config);
+  }
+
+  /** Clean output for console.log in Node.js */
+  [Symbol.for('nodejs.util.inspect.custom')](): BlockedInspectView {
+    return {
+      _tag: this._tag,
+      reason: this.reason,
+      ...(this.blockedConfig ? { blockedConfig: this.blockedConfig } : {}),
+    };
+  }
+
+  /** Clean output for JSON.stringify */
+  toJSON(): BlockedJsonView {
+    const config = this.blockedConfig;
+    return {
+      _tag: this._tag,
+      reason: this.reason,
+      ...(config
+        ? {
+            blockedConfig: {
+              ...(config.maxAttempts != null ? { maxAttempts: config.maxAttempts } : {}),
+              ...(config.nextRetry ? { nextRetry: '[closure]' } : {}),
+            },
+          }
+        : {}),
+    };
+  }
+}

package/src/lib/errors/CodeError.ts

@@ -0,0 +1,132 @@
+/**
+ * CodeError - typed error codes with data payloads.
+ *
+ * Use the `Code()` helper to define typed error codes, then use them with `ctx.err()`.
+ * The error code becomes the `_tag` for discrimination with `result.isErr(CODE)`.
+ *
+ * @example
+ * ```typescript
+ * import { Code } from '@smoothbricks/lmao/errors/CodeError';
+ *
+ * // Define typed error codes
+ * const NOT_FOUND = Code<{ id: string }>('NOT_FOUND');
+ * const VALIDATION_ERROR = Code<{ field: string; reason: string }>('VALIDATION_ERROR');
+ * const TIMEOUT = Code('TIMEOUT'); // No data payload
+ *
+ * // Use in Ops
+ * const fetchUser = defineOp('fetchUser', async (ctx, id: string) => {
+ *   const user = await db.find(id);
+ *   if (!user) {
+ *     return ctx.err(NOT_FOUND({ id }));
+ *   }
+ *   return ctx.ok(user);
+ * });
+ *
+ * // Discriminate errors
+ * const result = await trace('fetch', fetchUser, 'abc');
+ * if (result.isErr(NOT_FOUND)) {
+ *   console.log(`User ${result.error.data.id} not found`);
+ * }
+ * ```
+ */
+
+import type { TaggedError, TaggedErrorConstructor } from '../result.js';
+
+type CodeErrorJson<C extends string, D> = { code: C; data: D };
+
+/**
+ * Error instance created by a Code constructor.
+ *
+ * @typeParam C - The error code string literal type (also serves as _tag)
+ * @typeParam D - The data payload type
+ */
+export class CodeError<C extends string, D = void> extends Error implements TaggedError<C> {
+  /**
+   * The error code - also serves as the tag for discrimination.
+   */
+  readonly code: C;
+
+  /**
+   * The typed data payload.
+   */
+  readonly data: D;
+
+  constructor(code: C, data: D) {
+    super(code);
+    this.name = 'CodeError';
+    this.code = code;
+    this.data = data;
+  }
+
+  /**
+   * Tag for discrimination with isErr(Tag).
+   * Returns the error code.
+   */
+  get _tag(): C {
+    return this.code;
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](): CodeErrorJson<C, D> {
+    return { code: this.code, data: this.data };
+  }
+
+  toJSON(): CodeErrorJson<C, D> {
+    return { code: this.code, data: this.data };
+  }
+}
+
+/**
+ * Constructor function for a specific error code.
+ * Has static `_tag` for use with `isErr(CODE)`.
+ */
+export interface CodeConstructor<C extends string, D = void> extends TaggedErrorConstructor<CodeError<C, D>> {
+  (data: D): CodeError<C, D>;
+  readonly _tag: C;
+}
+
+/**
+ * Constructor function for error codes with no data.
+ */
+export interface CodeConstructorVoid<C extends string> extends TaggedErrorConstructor<CodeError<C, void>> {
+  (): CodeError<C, void>;
+  readonly _tag: C;
+}
+
+type CodeFactoryReturn<C extends string, D> = [unknown] extends [D]
+  ? CodeConstructor<C, D>
+  : undefined extends D
+    ? CodeConstructorVoid<C>
+    : CodeConstructor<C, D>;
+
+/**
+ * Define a typed error code.
+ *
+ * @param code - The error code string (becomes _tag for discrimination)
+ * @returns A constructor function that creates CodeError instances
+ *
+ * @example
+ * ```typescript
+ * // With typed data
+ * const NOT_FOUND = Code<{ id: string }>('NOT_FOUND');
+ * ctx.err(NOT_FOUND({ id: 'abc' }));
+ *
+ * // Without data
+ * const TIMEOUT = Code('TIMEOUT');
+ * ctx.err(TIMEOUT());
+ *
+ * // Discrimination
+ * if (result.isErr(NOT_FOUND)) {
+ *   console.log(result.error.data.id); // TypeScript knows the type
+ * }
+ * ```
+ */
+export function Code<C extends string>(code: C): CodeConstructorVoid<C>;
+export function Code<D, C extends string = string>(code: C): CodeFactoryReturn<C, D>;
+export function Code(code: string) {
+  function createCodeError(data?: unknown) {
+    return new CodeError(code, data);
+  }
+
+  Object.defineProperty(createCodeError, '_tag', { value: code, writable: false, enumerable: true });
+  return createCodeError;
+}