@smoothbricks/lmao 0.1.0

package/dist/lib/opContext/spanContextTypes.d.ts

@@ -0,0 +1,347 @@
+/**
+ * SpanContext Types for Op-Centric API
+ *
+ * Core types for span-level operations within the trace logging system.
+ * These types define the context passed to Op functions for:
+ * - Tag writing (row 0 attributes)
+ * - Structured logging (rows 2+)
+ * - Result handling (ok/err)
+ * - Child span creation
+ * - Feature flag access
+ * - Dependency access
+ *
+ * ## Dependency Layer
+ * This module is at Layer 2 in the type hierarchy:
+ * - Depends on: result (Layer 1), types (Layer 3), featureFlagTypes (Layer 1)
+ * - Depended on by: opTypes (Layer 3)
+ *
+ * SpanFn now uses Op<Ctx, Args, S, E> directly (no structural typing).
+ */
+import type { FluentLogEntry as FluentLogEntryFromGenerator } from '../codegen/spanLoggerGenerator.js';
+import type { Err, Ok, Result } from '../result.js';
+import type { FeatureFlagEvaluator, InferFeatureFlagsWithContext } from '../schema/evaluator.js';
+import type { LogSchema } from '../schema/LogSchema.js';
+import type { InferSchema } from '../schema/types.js';
+import type { SpanBuffer } from '../types.js';
+import type { Op } from './opTypes.js';
+import type { OpContext } from './types.js';
+/**
+ * DepsConfig - structural type to avoid importing from opGroupTypes.
+ * Represents a record of dependency groups.
+ */
+export type DepsConfig = Record<string, any>;
+/**
+ * ResolvedDeps - structural type to avoid importing from opGroupTypes.
+ * At runtime, deps are resolved OpGroups with their ops accessible.
+ */
+export type ResolvedDeps<_D extends DepsConfig> = Record<string, any>;
+/**
+ * Tag writer for setting span attributes (row 0)
+ * Generated at runtime with typed methods per schema field.
+ *
+ * Per specs/lmao/01h_entry_types_and_logging_primitives.md:
+ * - Writes to row 0 (fixed layout for span-start attributes)
+ * - All methods return TagWriter<T> for fluent chaining
+ * - Generated at runtime via createTagWriter()
+ */
+export type TagWriter<T extends LogSchema> = {
+    [K in keyof InferSchema<T>]: (value: InferSchema<T>[K]) => TagWriter<T>;
+} & {
+    /** Set multiple attributes at once */
+    with(attributes: Partial<InferSchema<T>>): TagWriter<T>;
+};
+/**
+ * SpanLogger - public API surface for structured logging.
+ *
+ * Includes core methods (info/debug/warn/error) from BaseSpanLogger
+ * and schema-specific methods from ColumnWriter.
+ * Internal methods (_setScope, _buffer, etc.) are hidden from this type.
+ *
+ * Per specs/lmao/01h_entry_types_and_logging_primitives.md:
+ * - Each level (info/debug/warn/error) creates a log entry
+ * - Returns FluentLogEntry for chaining field setters
+ * - Generated at runtime via createSpanLoggerFromGenerator()
+ */
+export interface SpanLogger<T extends LogSchema> {
+    /** Log at info level */
+    info(message: string): FluentLogEntry<T>;
+    /** Log at debug level */
+    debug(message: string): FluentLogEntry<T>;
+    /** Log at warn level */
+    warn(message: string): FluentLogEntry<T>;
+    /** Log at error level */
+    error(message: string): FluentLogEntry<T>;
+}
+/**
+ * Fluent log entry - chainable attribute setters after log level.
+ *
+ * Re-exported from spanLoggerGenerator.ts to avoid circular dependencies.
+ * The implementation in spanLoggerGenerator.ts is the source of truth.
+ *
+ * Allows setting attributes after choosing a log level:
+ * ctx.log.info('message').userId('u1').requestId('r1')
+ *
+ * All attributes are optional, chainable, and return FluentLogEntry for continuation.
+ *
+ * Includes system schema fields for direct access (no information hiding):
+ * - line(n) - Source line number (0-65535)
+ * - error_code(code) - Error code string
+ * - exception_stack(stack) - Exception stack trace
+ * - ff_value(value) - Feature flag value
+ * - uint64_value(value) - BigInt value
+ *
+ * Per specs/lmao/01c_context_flow_and_op_wrappers.md "Line Number System":
+ * - TypeScript transformer injects line() calls at compile time
+ * - No runtime overhead - just a method call with literal number
+ */
+export type FluentLogEntry<T extends LogSchema> = FluentLogEntryFromGenerator<T>;
+/**
+ * SpanFn - overloaded span creation function.
+ *
+ * Per specs/lmao/01l_op_context_pattern.md and 01o lines 34-72:
+ * Creates child spans with type-safe Op invocation or inline closures, with/without line numbers.
+ *
+ * The transformer injects line numbers at compile time, but runtime supports both patterns for fallback.
+ * Uses Op<Ctx, Args, S, E> and returns Result<S, E> (no generic R).
+ */
+export type SpanFn<Ctx extends OpContext> = {
+    /**
+     * Create child span with line number and Op invocation.
+     *
+     * Per spec 01o lines 46-49: Monomorphic span_op for transformer-injected line numbers.
+     *
+     * @param line - Source code line number (injected by transformer at compile time)
+     * @param name - Child span name (overrides Op's default name)
+     * @param op - Op to invoke (type-safe with Args, Success, Error types)
+     * @param args - Arguments to pass to Op function
+     * @returns Promise resolving to Result<S, E>
+     *
+     * @example
+     * const result = await ctx.span(42, 'fetch-user', fetchUserOp, userId);
+     */
+    <S, E, Args extends unknown[]>(line: number, name: string, op: Op<Ctx, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    /**
+     * Create child span with line number and inline closure.
+     *
+     * Per spec 01o lines 51-53: Monomorphic span_fn for transformer-injected line numbers.
+     *
+     * @param line - Source code line number (injected by transformer at compile time)
+     * @param name - Child span name
+     * @param fn - Async function to execute in child span (receives SpanContext<Ctx>)
+     * @returns Promise resolving to Result<S, E>
+     *
+     * @example
+     * const result = await ctx.span(42, 'validate', async (childCtx) => {
+     *   childCtx.tag.step('validation');
+     *   return childCtx.ok({ valid: true });
+     * });
+     */
+    <S, E>(line: number, name: string, fn: (ctx: SpanContext<Ctx>) => Result<S, E> | Promise<Result<S, E>>): Promise<Result<S, E>>;
+    /**
+     * Create child span with Op invocation (most common - no line number).
+     *
+     * Per spec 01o lines 55-71: Polymorphic span dispatcher for fallback when transformer didn't inject line number.
+     *
+     * @param name - Child span name (overrides Op's default name)
+     * @param op - Op to invoke (type-safe with Args, Success, Error types)
+     * @param args - Arguments to pass to Op function
+     * @returns Promise resolving to Result<S, E>
+     *
+     * @example
+     * const result = await ctx.span('fetch-user', fetchUserOp, userId);
+     */
+    <S, E, Args extends unknown[]>(name: string, op: Op<Ctx, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    /**
+     * Create child span with inline closure (most common - no line number).
+     *
+     * Per spec 01o lines 55-71: Polymorphic span dispatcher for fallback when transformer didn't inject line number.
+     *
+     * @param name - Child span name
+     * @param fn - Async function to execute in child span (receives SpanContext<Ctx>)
+     * @returns Promise resolving to Result<S, E>
+     *
+     * @example
+     * const result = await ctx.span('validate', async (childCtx) => {
+     *   childCtx.tag.step('validation');
+     *   return childCtx.ok({ valid: true });
+     * });
+     */
+    <S, E>(name: string, fn: (ctx: SpanContext<Ctx>) => Result<S, E> | Promise<Result<S, E>>): Promise<Result<S, E>>;
+};
+/**
+ * SpanSyncFn - synchronous child span creation.
+ *
+ * Use when the callback is guaranteed sync and should return immediately
+ * with a Result envelope.
+ */
+export type SpanSyncFn<Ctx extends OpContext> = <S, E>(name: string, fn: (ctx: SpanContext<Ctx>) => Result<S, E>) => Result<S, E>;
+/**
+ * SpanContext - what op functions receive.
+ *
+ * Per specs/lmao/01c_context_flow_and_op_wrappers.md and 01l:
+ * - Passed to Op functions as first argument
+ * - Combines built-in properties with user-extensible UserCtx via intersection
+ * - Child spans inherit scoped attributes from parent (frozen copy for safety)
+ * - User properties from Ctx['userCtx'] are spread via intersection at end
+ *
+ * @template Ctx - Bundled context (logSchema, flags, deps, userCtx)
+ *
+ * @example
+ * ```typescript
+ * const createUser = op('create-user', async (ctx, userData) => {
+ *   ctx.setScope({ userId: userData.id });
+ *   ctx.tag.operation('INSERT');
+ *   ctx.log.info('Creating user').line(42);
+ *   return ctx.ok(user);
+ * });
+ * ```
+ */
+export type SpanContext<Ctx extends OpContext> = {
+    /**
+     * The underlying SpanBuffer for this context.
+     *
+     * Useful for Arrow table conversion after task completion.
+     * The buffer contains all trace data written during this span's execution.
+     *
+     * @example
+     * ```typescript
+     * const result = await myTask(requestCtx, args);
+     * const table = convertToArrowTable(ctx.buffer);
+     * ```
+     */
+    buffer: SpanBuffer<Ctx['logSchema']>;
+    /**
+     * Tag writer for span attributes (row 0).
+     *
+     * Per specs/lmao/01h_entry_types_and_logging_primitives.md:
+     * - Writes to row 0 (fixed layout for span-start attributes)
+     * - All methods return TagWriter for fluent chaining
+     *
+     * @example
+     * ctx.tag.userId('u1').requestId('r1').operation('INSERT');
+     */
+    tag: TagWriter<Ctx['logSchema']>;
+    /**
+     * Structured logger (rows 2+).
+     *
+     * Per specs/lmao/01h_entry_types_and_logging_primitives.md:
+     * - info/debug/warn/error create log entries
+     * - Returns FluentLogEntry for chaining field setters
+     * - Entries are appended after row 1
+     *
+     * @example
+     * ctx.log.info('Processing request').userId('u1').line(42);
+     */
+    log: SpanLogger<Ctx['logSchema']>;
+    /**
+     * Feature flags (logs access to current span).
+     *
+     * Per specs/lmao/01p_feature_flags.md:
+     * - Sync access via ff.flagName / ff['flagName']
+     * - Async access via await ff.get('flagName')
+     * - Logs flag access to span automatically
+     * - Type-safe evaluation with context
+     */
+    ff: FeatureFlagEvaluator<Ctx> & InferFeatureFlagsWithContext<Ctx>;
+    /**
+     * Dependencies - can be destructured!
+     *
+     * Per spec 01l lines 757-758:
+     * - Plain object references to dependency modules/ops
+     * - Zero-allocation deps (not closures)
+     *
+     * @example
+     * const { retry, auth } = deps;
+     * await span('retry', retry, 1);
+     */
+    deps: ResolvedDeps<Ctx['deps']>;
+    /**
+     * Create a success result with optional attributes.
+     *
+     * Writes span-ok entry to row 1 (span-end).
+     * Supports fluent chaining with .with() and .message().
+     *
+     * @param value - The success value
+     * @returns Fluent result builder
+     *
+     * @example
+     * return ctx.ok(user).with({ userId: user.id });
+     */
+    ok<S>(value: S): Ok<S, Ctx['logSchema']>;
+    /**
+     * Create an error result with optional attributes.
+     *
+     * Writes span-err entry to row 1 (span-end).
+     * Supports fluent chaining with .with() and .message().
+     *
+     * @param code - Error code string
+     * @param details - Error details
+     * @returns Fluent result builder
+     *
+     * @example
+     * const NOT_FOUND = defineCodeError('NOT_FOUND')<{ userId: string }>();
+     * return ctx.err(NOT_FOUND({ userId })).message('User not found');
+     */
+    err<E>(error: E): Err<E, Ctx['logSchema']>;
+    /**
+     * Create a child span with its own buffer.
+     *
+     * Child spans inherit scoped attributes from the parent.
+     * The child function receives a new SpanContext.
+     *
+     * Per specs/lmao/01i_span_scope_attributes.md:
+     * - Child inherits parent's scope by reference (safe because immutable)
+     * - Child can override scope values with setScope()
+     * - Scope is frozen at each level to prevent race conditions
+     *
+     * @example
+     * const result = await ctx.span('validate', async (childCtx) => {
+     *   childCtx.tag.step('validation');
+     *   return childCtx.ok({ valid: true });
+     * });
+     */
+    span: SpanFn<Ctx>;
+    /**
+     * Create a synchronous child span.
+     *
+     * `spanSync` is for sync callbacks only and returns Result directly.
+     * It does not await or perform async retry/backoff behavior.
+     */
+    spanSync: SpanSyncFn<Ctx>;
+    /**
+     * Set scoped attributes that auto-propagate to all subsequent log entries.
+     *
+     * Scoped attributes are automatically included in all log entries
+     * and inherited by child spans. Uses merge semantics - pass null to clear a value.
+     *
+     * Per specs/lmao/01i_span_scope_attributes.md:
+     * - Creates a NEW frozen object (never mutates existing scope)
+     * - setScope({ x: null }) removes x from scope
+     * - Child spans get frozen snapshot at creation (async-safe)
+     *
+     * @param attributes - Attributes to scope to this span (null clears a value)
+     *
+     * @example
+     * ctx.setScope({ requestId: req.id, userId: req.user?.id });
+     * ctx.log.info('Processing'); // Includes requestId and userId
+     * ctx.setScope({ userId: null }); // Clear userId from scope
+     */
+    setScope(values: Partial<InferSchema<Ctx['logSchema']>> | null): void;
+    /**
+     * Read-only view of current scoped attributes.
+     *
+     * Returns the frozen scope object containing all currently scoped values.
+     * Use setScope() to modify scope values.
+     *
+     * Per specs/lmao/01i_span_scope_attributes.md:
+     * - Always a frozen object, never undefined
+     * - Initialized to EMPTY_SCOPE, only replaced with new frozen objects
+     * - Safe to read from async code without race conditions
+     *
+     * @example
+     * ctx.setScope({ requestId: 'r1' });
+     * console.log(ctx.scope.requestId); // 'r1'
+     */
+    scope: Readonly<Partial<InferSchema<Ctx['logSchema']>>>;
+} & Ctx['userCtx'];
+//# sourceMappingURL=spanContextTypes.d.ts.map

package/dist/lib/opContext/spanContextTypes.d.ts.map

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

package/dist/lib/opContext/spanContextTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/opContext/types.d.ts

@@ -0,0 +1,297 @@
+/**
+ * Op-Centric API Type Definitions Hub
+ *
+ * This is the central hub for all Op-centric API types. Consumers should import
+ * from this file rather than individual type files.
+ *
+ * Organized into logical groups:
+ * - Context utilities (reserved props, null/undefined key extraction, validation)
+ * - Feature flags (schema, evaluator, bound flags)
+ * - OpGroup (groups, mapping, deps, schema combination)
+ * - Op (metadata, function signature, instance)
+ * - SpanContext (tag writer, logger, span function, full context)
+ *
+ * @module opContext/types
+ */
+export type { FlagEvaluator, SpanContextWithoutFf } from '../schema/evaluator.js';
+export { type DefaultKeys, type NullKeys, type OptionalContextParams, RESERVED_CONTEXT_PROPS, type RequiredContextParams, type ReservedContextProp, type ResolvedContext, type TraceContextParams, type UndefinedKeys, type ValidateUserContext, } from './contextTypes.js';
+export type { BoundFeatureFlags, FeatureFlagSchema } from './featureFlagTypes.js';
+export type { AnyOpGroup, ColumnMapping, CombinedDepsSchema, ContributedSchemaOf, DepsConfig, EffectiveSchema, MappedOpGroup, MappedSchema, OpGroup, PrefixedSchema, ResolvedDeps, SchemaFieldsOf, UnionToIntersection, } from './opGroupTypes.js';
+export type { Op, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
+export type { FluentLogEntry, SpanContext, SpanFn, SpanLogger, SpanSyncFn, TagWriter } from './spanContextTypes.js';
+export { LogSchema } from '../schema/LogSchema.js';
+export type { FeatureFlagDefinition, InferSchema, SchemaFields } from '../schema/types.js';
+/**
+ * Unique symbol to carry OpContext type on OpContextFactory.
+ * Allows extracting the bundled type without passing 4 separate params.
+ * Must be a runtime value (not just `declare const`) so it can be used as property key.
+ */
+declare const opContextType: unique symbol;
+/**
+ * Helper to extract OpContext from a factory.
+ * @example
+ * const { defineOp } = defineOpContext({ ... });
+ * type MyCtx = OpContextOf<typeof factory>; // OpContext<T, FF, Deps, UserCtx>
+ */
+export type OpContextOf<F> = F extends {
+    readonly [opContextType]?: infer Ctx;
+} ? Ctx : never;
+export { opContextType };
+/**
+ * Bundled type parameters for Op context.
+ *
+ * Created by defineOpContext() and shared by all Ops from that factory.
+ * Reduces type parameter count: Op<Ctx, Args, S, E> instead of Op<T, FF, Deps, UserCtx, Args, R>
+ *
+ * @template T - LogSchema type
+ * @template FF - Feature flag schema
+ * @template Deps - Dependencies config
+ * @template UserCtx - User context properties
+ */
+export type OpContext<T extends LogSchema = LogSchema, FF extends FeatureFlagSchema = FeatureFlagSchema, Deps extends DepsConfig = DepsConfig, UserCtx extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly logSchema: T;
+    readonly flags: FF;
+    readonly deps: Deps;
+    readonly userCtx: UserCtx;
+};
+import type { LogSchema } from '../schema/LogSchema.js';
+import type { SchemaFields } from '../schema/types.js';
+import type { ValidateUserContext } from './contextTypes.js';
+import type { FeatureFlagSchema } from './featureFlagTypes.js';
+import type { DepsConfig, OpGroup } from './opGroupTypes.js';
+import type { Op, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
+/**
+ * Configuration for defineOpContext
+ *
+ * This is the main configuration interface for creating an Op context factory.
+ * It defines:
+ * - The app's own schema (logSchema)
+ * - Dependencies from other OpGroups (deps)
+ * - Feature flag schema (flags)
+ * - User-defined context properties (ctx)
+ *
+ * @template T - LogSchema fields (app's own schema)
+ * @template FF - Feature flag schema
+ * @template Deps - Dependency record (other OpGroups with mappings)
+ * @template UserCtx - User-defined context properties
+ *
+ * The effective schema for ops = `T & CombinedDepsSchema<Deps>`.
+ * This means ops can write to columns from both the app's schema AND
+ * all columns contributed by wired dependencies (after mapping/prefixing).
+ */
+export interface OpContextConfig<T extends SchemaFields, FF extends FeatureFlagSchema, Deps extends DepsConfig, UserCtx extends Record<string, unknown>> {
+    /**
+     * Log schema defining the app's own columns.
+     *
+     * The effective schema for ops is this PLUS columns from deps.
+     * E.g., if you wire `http: httpOps.prefix('http')`, ops can also
+     * write to `http_status`, `http_url`, etc.
+     */
+    readonly logSchema: LogSchema<T>;
+    /**
+     * Dependencies - other OpGroups that can be invoked via ctx.deps
+     *
+     * Each dep's columns are added to the effective schema based on its mapping:
+     * - `.prefix('http')` → columns become `http_status`, `http_url`, etc.
+     * - `.mapColumns({ query: 'query' })` → shares the `query` column
+     * - `.mapColumns({ _internal: null })` → drops the `_internal` column
+     *
+     * @example
+     * deps: {
+     *   pg: postgresOps.mapColumns({ query: 'query', rows: 'pg_rows' }),
+     *   mysql: mysqlOps.mapColumns({ query: 'query', duration: 'mysql_duration' }),
+     *   http: httpOps.prefix('http'),
+     * }
+     * // Effective schema includes: query, pg_rows, mysql_duration, http_status, http_url, ...
+     */
+    readonly deps?: Deps;
+    /**
+     * Feature flag schema - defines available flags and their types
+     *
+     * @example
+     * flags: defineFeatureFlags({
+     *   newCheckout: S.boolean().default(false).async(),
+     *   maxRetries: S.number().default(3).sync(),
+     * })
+     */
+    readonly flags?: FF;
+    /**
+     * User-defined context properties
+     *
+     * ALL properties must be declared here for V8 hidden class optimization.
+     * Properties set to `null` must be provided when calling createTrace().
+     * Properties with values have defaults and can be optionally overridden.
+     *
+     * @example
+     * ctx: {
+     *   env: null as CFWorkerEnv,       // Must provide at createTrace()
+     *   config: { retryCount: 3 },       // Has default, can override
+     *   requestId: null as string,       // Must provide at createTrace()
+     * }
+     */
+    readonly ctx?: ValidateUserContext<UserCtx>;
+}
+/**
+ * Runtime binding from defineOpContext for use with Tracer.
+ *
+ * Contains everything a Tracer needs to create traces:
+ * - logBinding: Schema and capacity stats for buffer creation
+ * - ctxDefaults: User context defaults (with null sentinels for required fields)
+ * - deps: Wired dependencies for ctx.deps
+ *
+ * Carries phantom type via [opContextType] for full OpContext inference.
+ * This allows `new TestTracer(ctx)` to infer T from ctx.logBinding without
+ * explicit type parameters.
+ *
+ * @template T - LogSchema type
+ * @template FF - Feature flag schema
+ * @template Deps - Dependencies config
+ * @template UserCtx - User context properties
+ *
+ * @example
+ * ```typescript
+ * const ctx = defineOpContext({
+ *   logSchema: defineLogSchema({ userId: S.category() }),
+ *   ctx: { env: null as Env },
+ * });
+ *
+ * // Tracer infers types from binding - no explicit type params needed
+ * const { trace } = new TestTracer(ctx);
+ * ```
+ */
+export interface OpContextBinding<T extends LogSchema = LogSchema, FF extends FeatureFlagSchema = FeatureFlagSchema, Deps extends DepsConfig = DepsConfig, UserCtx extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Phantom type - extract via OpContextOf<typeof binding>
+     *
+     * Carries the bundled OpContext type for type inference.
+     * Tracers use this to infer the full context type without explicit parameters.
+     *
+     * @internal
+     */
+    readonly [opContextType]?: OpContext<T, FF, Deps, UserCtx>;
+    /**
+     * LogBinding for this context (schema, capacity stats, optional prefix view).
+     * Used by Tracer to create SpanBuffers and SpanContexts.
+     * Typed with schema T for Op type safety.
+     */
+    readonly logBinding: import('../logBinding.js').LogBinding<T>;
+    /**
+     * Feature flag schema needed by tracers to bootstrap typed evaluators.
+     */
+    readonly flags: FF;
+    /**
+     * User context defaults from ctx config.
+     * Used by Tracer to merge with trace-level overrides.
+     * Properties with null values are required at trace creation.
+     */
+    readonly ctxDefaults: UserCtx;
+    /**
+     * Dependencies wired at defineOpContext time.
+     * Used by Tracer to populate ctx.deps on root spans.
+     */
+    readonly deps: Deps;
+}
+/**
+ * Return type of defineOpContext
+ *
+ * This is the factory returned by defineOpContext that provides:
+ * - `defineOp`: Define a single Op with explicit name
+ * - `defineOps`: Define multiple Ops and create an OpGroup
+ * - `logSchema`: The combined effective schema
+ * - `flags`: The feature flag schema
+ *
+ * Extends OpContextBinding to provide everything Tracer needs.
+ * Uses unique symbol [opContextType] to carry the bundled OpContext type
+ * for extraction via OpContextOf<typeof factory>.
+ *
+ * @template T - The app's LogSchema
+ * @template FF - Feature flag schema
+ * @template Deps - Wired dependencies
+ * @template UserCtx - User context properties
+ *
+ * The effective schema for ops is `T & CombinedDepsSchema<Deps>` - the app's
+ * schema combined with all columns contributed by wired dependencies.
+ */
+export interface OpContextFactory<T extends LogSchema, FF extends FeatureFlagSchema, Deps extends DepsConfig, UserCtx extends Record<string, unknown>> extends OpContextBinding<T, FF, Deps, UserCtx> {
+    /**
+     * The combined log schema (app schema + dep contributions).
+     *
+     * This is the effective schema that ops can write to. It includes:
+     * - All columns from the app's logSchema
+     * - All mapped/prefixed columns from dependencies
+     *
+     * External consumers can use this to see the full schema shape.
+     */
+    readonly logSchema: T;
+    /**
+     * The feature flag schema (for external consumers)
+     */
+    readonly flags: FF;
+    /**
+     * Define a single Op with explicit name.
+     *
+     * Creates an Op instance that wraps your function with metadata for tracing.
+     * The Op can be invoked via ctx.span() or exported for use by other modules.
+     *
+     * @param name - Op name (used for default span naming and metrics)
+     * @param fn - Op function receiving SpanContext and returning Result<S, E>
+     * @param metadata - Optional metadata override (package_name, package_file, etc.)
+     * @returns Op instance with type Op<OpContext<T, FF, Deps, UserCtx>, Args, S, E>
+     *
+     * @example
+     * ```typescript
+     * const fetchUser = defineOp('fetchUser', async (ctx, userId: string) => {
+     *   ctx.tag.userId(userId);
+     *   const user = await db.getUser(userId);
+     *   if (!user) return ctx.err('NOT_FOUND', { userId });
+     *   return ctx.ok(user);
+     * });
+     *
+     * // Invoke via span:
+     * const result = await ctx.span('get-user', fetchUser, 'user-123');
+     * ```
+     */
+    defineOp<Args extends unknown[], S, E>(name: string, fn: OpFn<OpContext<T, FF, Deps, UserCtx>, Args, S, E>, metadata?: Partial<OpMetadata>): Op<OpContext<T, FF, Deps, UserCtx>, Args, S, E>;
+    /**
+     * Define multiple Ops at once and create an OpGroup.
+     *
+     * Property keys become Op names. Supports `this` binding for calling
+     * sibling ops within the same batch. Returns an OpGroup that can be:
+     * - Prefixed with `.prefix('http')` for column namespacing
+     * - Column-mapped with `.mapColumns({ query: 'query' })` for sharing
+     * - Wired as a dependency in another module's `deps` config
+     *
+     * @param definitions - Record of Op functions or existing Op instances
+     * @returns OpGroup with all defined Ops accessible as properties
+     *
+     * @example
+     * ```typescript
+     * export const userOps = defineOps({
+     *   // Reuse existing Op
+     *   fetchUser,
+     *
+     *   // Define new op with method syntax
+     *   async createUser(ctx, data: UserData) {
+     *     ctx.tag.operation('INSERT');
+     *     const user = await db.createUser(data);
+     *     return ctx.ok(user);
+     *   },
+     *
+     *   // Call sibling op via this.opName
+     *   async createAndFetch(ctx, data: UserData) {
+     *     const created = await ctx.span('create', this.createUser, data);
+     *     if (!created.success) return created;
+     *     return ctx.span('fetch', this.fetchUser, created.value.id);
+     *   },
+     * });
+     *
+     * // Wire as dependency with prefix:
+     * deps: { users: userOps.prefix('user') }
+     *
+     * // Invoke from parent context:
+     * await ctx.span('create-user', userOps.createUser, userData);
+     * ```
+     */
+    defineOps<Defs extends Record<string, OpFn<OpContext<T, FF, Deps, UserCtx>, unknown[], unknown, unknown> | Op<OpContext<T, FF, Deps, UserCtx>, unknown[], unknown, unknown>>>(definitions: Defs): OpGroup<OpContext<T, FF, Deps, UserCtx>, OpsFromRecord<OpContext<T, FF, Deps, UserCtx>, Defs>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/opContext/types.d.ts.map

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

package/dist/lib/opContext/types.js

@@ -0,0 +1,16 @@
+// Context type utilities (reserved props, null/undefined key extraction, validation)
+export { RESERVED_CONTEXT_PROPS, } from './contextTypes.js';
+// =============================================================================
+// CONVENIENCE RE-EXPORTS
+// =============================================================================
+export { LogSchema } from '../schema/LogSchema.js';
+// =============================================================================
+// OP CONTEXT TYPE SYMBOL
+// =============================================================================
+/**
+ * Unique symbol to carry OpContext type on OpContextFactory.
+ * Allows extracting the bundled type without passing 4 separate params.
+ * Must be a runtime value (not just `declare const`) so it can be used as property key.
+ */
+const opContextType = Symbol('opContextType');
+export { opContextType };