@smoothbricks/lmao 0.1.0

package/dist/lib/defineOpContext.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 DepsConfig, type EffectiveSchema, type FeatureFlagSchema, type OpContextConfig, type OpContextFactory, type ValidateUserContext } from './opContext/index.js';
+import { LogSchema } from './schema/LogSchema.js';
+import type { SchemaFields } from './schema/types.js';
+/**
+ * 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 * from './opContext/index.js';
+export { S } from './schema/builder.js';
+export { defineFeatureFlags } from './schema/defineFeatureFlags.js';
+export { defineLogSchema } from './schema/defineLogSchema.js';
+export { LogSchema } from './schema/LogSchema.js';
+//# sourceMappingURL=defineOpContext.d.ts.map

package/dist/lib/defineOpContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineOpContext.d.ts","sourceRoot":"","sources":["../../src/lib/defineOpContext.ts"],"names":[],"mappings":"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"}

package/dist/lib/defineOpContext.js

@@ -0,0 +1,227 @@
+/**
+ * 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 { createDefineOp, createDefineOps, createOpGroup, isMappedOpGroup, RESERVED_CONTEXT_PROPS, } from './opContext/index.js';
+import { LogSchema } from './schema/LogSchema.js';
+import { mergeWithSystemSchema, SYSTEM_SCHEMA_FIELD_NAMES } from './schema/systemSchema.js';
+const EMPTY_FLAGS = Object.freeze({});
+const EMPTY_DEPS = Object.freeze({});
+const EMPTY_USER_CTX = Object.freeze({});
+// =============================================================================
+// 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) {
+    // 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) {
+    const result = {};
+    for (const key of Object.keys(fields)) {
+        if (!isSystemField(key)) {
+            result[key] = fields[key];
+        }
+    }
+    return result;
+}
+function isInternalOpGroup(dep) {
+    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) {
+    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);
+}
+function computeEffectiveSchema(appFields, deps) {
+    if (!deps || Object.keys(deps).length === 0) {
+        return appFields;
+    }
+    // Start with app fields
+    const effective = { ...appFields };
+    // Track which dep contributed each field for conflict detection
+    const fieldSource = {};
+    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, flags, deps, ctxDefaults) {
+    // 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(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({
+        logSchema: mergedSchema,
+        flags,
+        opContextBinding,
+    });
+    const defineOps = createDefineOps({ 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,
+    };
+}
+export function defineOpContext(config) {
+    // 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/dist/lib/errors/Blocked.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 declare function getBlockedReasonName(reason: BlockedReason): string;
+/**
+ * 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 BlockedJsonView = {
+    _tag: 'Blocked';
+    reason: BlockedReason;
+    blockedConfig?: Omit<BlockedConfig, 'nextRetry'> & {
+        nextRetry?: string;
+    };
+};
+export declare class Blocked extends Error implements TaggedError<'Blocked'> {
+    /** The reason this Op is blocked */
+    readonly reason: BlockedReason;
+    static readonly _tag: "Blocked";
+    get _tag(): 'Blocked';
+    /** Retry configuration */
+    readonly blockedConfig: BlockedConfig | undefined;
+    constructor(
+    /** The reason this Op is blocked */
+    reason: BlockedReason, 
+    /** Optional retry configuration */
+    config?: BlockedConfig);
+    /** Create a Blocked error for a service being unavailable */
+    static service(name: string, config?: BlockedConfig): Blocked;
+    /** Create a Blocked error waiting for another execution to end */
+    static ended(target: string, config?: BlockedConfig): Blocked;
+    /** Create a Blocked error for an index being rebuilt */
+    static index(indexName: string, config?: BlockedConfig): Blocked;
+    /** Clean output for JSON.stringify */
+    toJSON(): BlockedJsonView;
+}
+export {};
+//# sourceMappingURL=Blocked.d.ts.map

package/dist/lib/errors/Blocked.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Blocked.d.ts","sourceRoot":"","sources":["../../../src/lib/errors/Blocked.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CASlE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CAClD;AAQD,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,aAAa,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E,CAAC;AAEF,qBAAa,OAAQ,SAAQ,KAAM,YAAW,WAAW,CAAC,SAAS,CAAC;IAWhE,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,aAAa;IAXhC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAU;IAE1C,IAAI,IAAI,IAAI,SAAS,CAEpB;IAED,0BAA0B;IAC1B,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,SAAS,CAAC;;IAGhD,oCAAoC;IAC3B,MAAM,EAAE,aAAa;IAC9B,mCAAmC;IACnC,MAAM,CAAC,EAAE,aAAa;IAOxB,6DAA6D;IAC7D,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO;IAI7D,kEAAkE;IAClE,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO;IAI7D,wDAAwD;IACxD,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO;IAahE,sCAAsC;IACtC,MAAM,IAAI,eAAe;CAe1B"}

package/dist/lib/errors/Blocked.js

@@ -0,0 +1,68 @@
+/**
+ * Convert a blocked reason union into its display name.
+ */
+export function getBlockedReasonName(reason) {
+    switch (reason.type) {
+        case 'service':
+            return reason.name;
+        case 'ended':
+            return reason.target;
+        case 'index':
+            return reason.indexName;
+    }
+}
+export class Blocked extends Error {
+    reason;
+    static _tag = 'Blocked';
+    get _tag() {
+        return 'Blocked';
+    }
+    /** Retry configuration */
+    blockedConfig;
+    constructor(
+    /** The reason this Op is blocked */
+    reason, 
+    /** Optional retry configuration */
+    config) {
+        super(`Blocked: ${getBlockedReasonName(reason)}`);
+        this.reason = reason;
+        this.name = 'Blocked';
+        this.blockedConfig = config;
+    }
+    /** Create a Blocked error for a service being unavailable */
+    static service(name, config) {
+        return new Blocked({ type: 'service', name }, config);
+    }
+    /** Create a Blocked error waiting for another execution to end */
+    static ended(target, config) {
+        return new Blocked({ type: 'ended', target }, config);
+    }
+    /** Create a Blocked error for an index being rebuilt */
+    static index(indexName, config) {
+        return new Blocked({ type: 'index', indexName }, config);
+    }
+    /** Clean output for console.log in Node.js */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return {
+            _tag: this._tag,
+            reason: this.reason,
+            ...(this.blockedConfig ? { blockedConfig: this.blockedConfig } : {}),
+        };
+    }
+    /** Clean output for JSON.stringify */
+    toJSON() {
+        const config = this.blockedConfig;
+        return {
+            _tag: this._tag,
+            reason: this.reason,
+            ...(config
+                ? {
+                    blockedConfig: {
+                        ...(config.maxAttempts != null ? { maxAttempts: config.maxAttempts } : {}),
+                        ...(config.nextRetry ? { nextRetry: '[closure]' } : {}),
+                    },
+                }
+                : {}),
+        };
+    }
+}

package/dist/lib/errors/CodeError.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 declare 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);
+    /**
+     * Tag for discrimination with isErr(Tag).
+     * Returns the error code.
+     */
+    get _tag(): C;
+    toJSON(): CodeErrorJson<C, D>;
+}
+/**
+ * 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 declare function Code<C extends string>(code: C): CodeConstructorVoid<C>;
+export declare function Code<D, C extends string = string>(code: C): CodeFactoryReturn<C, D>;
+export {};
+//# sourceMappingURL=CodeError.d.ts.map

package/dist/lib/errors/CodeError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeError.d.ts","sourceRoot":"","sources":["../../../src/lib/errors/CodeError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAExE,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC;AAE/D;;;;;GAKG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,IAAI,CAAE,SAAQ,KAAM,YAAW,WAAW,CAAC,CAAC,CAAC;IACxF;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;gBAEL,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IAO5B;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC,CAEZ;IAMD,MAAM,IAAI,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC;CAG9B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,IAAI,CAAE,SAAQ,sBAAsB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1G,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAE,SAAQ,sBAAsB,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACvG,IAAI,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;CAClB;AAED,KAAK,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAC/D,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GACrB,SAAS,SAAS,CAAC,GACjB,mBAAmB,CAAC,CAAC,CAAC,GACtB,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;AACxE,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/lib/errors/CodeError.js

@@ -0,0 +1,42 @@
+/**
+ * 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 extends Error {
+    /**
+     * The error code - also serves as the tag for discrimination.
+     */
+    code;
+    /**
+     * The typed data payload.
+     */
+    data;
+    constructor(code, data) {
+        super(code);
+        this.name = 'CodeError';
+        this.code = code;
+        this.data = data;
+    }
+    /**
+     * Tag for discrimination with isErr(Tag).
+     * Returns the error code.
+     */
+    get _tag() {
+        return this.code;
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return { code: this.code, data: this.data };
+    }
+    toJSON() {
+        return { code: this.code, data: this.data };
+    }
+}
+export function Code(code) {
+    function createCodeError(data) {
+        return new CodeError(code, data);
+    }
+    Object.defineProperty(createCodeError, '_tag', { value: code, writable: false, enumerable: true });
+    return createCodeError;
+}