@smoothbricks/lmao 0.1.0

package/dist/lib/opContext/createOpGroup.js

@@ -0,0 +1,341 @@
+/**
+ * OpGroup Creation - Class-based architecture for Phase 2
+ *
+ * Creates OpGroups as class instances with ops as own properties.
+ * Enables V8 hidden class optimization and cleaner API (`.opName` not `.ops.opName`).
+ *
+ * Why class-based:
+ * - Private fields (#columnMapping) don't affect hidden class (truly hidden, no enumeration)
+ * - Ops as own properties enable direct access and predictable object shape
+ * - prefix()/mapColumns() create new instances with same SpanBufferClass (shared stats)
+ * - Only remappedViewClass differs between original and prefixed op instances
+ *
+ * Internal properties (_logSchema, _flags, etc.) are prefixed with underscore to avoid
+ * collision with user-defined op names. Public interfaces hide these from intellisense.
+ *
+ * @module opContext/createOpGroup
+ */
+import { generateRemappedBufferViewClass } from '../library.js';
+import { Op } from '../op.js';
+import { SYSTEM_SCHEMA_FIELD_NAMES } from '../schema/systemSchema.js';
+import { validateOpName } from './opGroupTypes.js';
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+function getSchemaFields(fieldsSchema) {
+    return fieldsSchema.fields;
+}
+/**
+ * Create reverse mapping for RemappedBufferView.
+ * Input: clean -> prefixed mapping (e.g., { status: 'http_status' })
+ * Output: prefixed -> clean mapping (e.g., { http_status: 'status' })
+ *
+ * Why reverse: RemappedBufferView wraps child buffer at registration time.
+ * Arrow conversion asks for 'http_status', view needs to find 'status' in raw buffer.
+ */
+function createReverseMapping(mapping) {
+    const reverse = {};
+    for (const [cleanName, prefixedName] of Object.entries(mapping)) {
+        if (typeof prefixedName === 'string') {
+            reverse[prefixedName] = cleanName;
+        }
+    }
+    return reverse;
+}
+function isOpInstance(value) {
+    return value instanceof Op;
+}
+function copyOpsWithView(source, target, remappedViewClass) {
+    for (const [key, value] of Object.entries(source)) {
+        if (isOpInstance(value)) {
+            target[key] = new Op(value.metadata, value.SpanBufferClass, value.fn, remappedViewClass, value._opContextBinding);
+        }
+    }
+}
+function assertGroupCarriesOps(group, ops) {
+    for (const name of Object.keys(ops)) {
+        if (!isOpInstance(group[name])) {
+            throw new TypeError(`Expected OpGroup to expose op '${name}' as an Op instance`);
+        }
+    }
+}
+function cloneOpsWithView(source, remappedViewClass) {
+    const cloned = {};
+    copyOpsWithView(source, cloned, remappedViewClass);
+    assertGroupCarriesOps(cloned, source);
+    return cloned;
+}
+function prefixContributedSchema(fields, prefix) {
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        result[`${prefix}_${key}`] = value;
+    }
+    assertMappedSchema(result);
+    return result;
+}
+function assertMappedSchema(value) {
+    for (const schema of Object.values(value)) {
+        if (typeof schema !== 'object' || schema === null) {
+            throw new TypeError('Mapped schema must contain schema metadata objects');
+        }
+    }
+}
+/**
+ * Build a prefix mapping for all schema fields
+ *
+ * Why prefix all fields: Ensures no column name collisions when wiring multiple libraries.
+ * Each library's columns become `${prefix}_${field}` in app schema.
+ *
+ * @param fieldNames - The field names from the schema
+ * @param prefix - The prefix to apply
+ * @returns Column mapping where each field becomes `${prefix}_${field}`
+ */
+function buildPrefixMapping(fieldNames, prefix) {
+    const mapping = {};
+    for (const name of fieldNames) {
+        // Skip system columns - they should NOT be prefixed
+        if (SYSTEM_SCHEMA_FIELD_NAMES.has(name))
+            continue;
+        mapping[name] = `${prefix}_${name}`;
+    }
+    return mapping;
+}
+/**
+ * Apply a prefix to an existing mapping
+ *
+ * For each entry in the mapping:
+ * - If mapped to a string, prefix that string: 'status' -> 'http_status'
+ * - If mapped to null (dropped), keep as null
+ *
+ * Why: Enables chaining `.prefix('http').prefix('api')` to build composite prefixes.
+ *
+ * @param mapping - Existing column mapping
+ * @param prefix - Prefix to apply
+ * @returns New mapping with prefixed target names
+ */
+function prefixMapping(mapping, prefix) {
+    const result = {};
+    for (const [key, value] of Object.entries(mapping)) {
+        if (value === null) {
+            result[key] = null;
+        }
+        else if (typeof value === 'string') {
+            result[key] = `${prefix}_${value}`;
+        }
+    }
+    return result;
+}
+/**
+ * Build the contributed schema object from the original schema and mapping
+ *
+ * The contributed schema reflects what columns this group adds to the app's schema
+ * after mapping is applied.
+ *
+ * Why track contributed schema: Type system needs to know what columns are available
+ * after prefix/mapping transformations for compile-time safety.
+ *
+ * @param fields - Original schema fields
+ * @param mapping - Column mapping
+ * @returns The contributed schema with renamed keys
+ */
+function buildContributedSchema(fields, mapping) {
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        const mappedName = mapping[key];
+        if (mappedName === null) {
+            // Dropped column - not included in contributed schema
+        }
+        else if (typeof mappedName === 'string') {
+            // Explicitly mapped - use the mapped name
+            result[mappedName] = value;
+        }
+        else {
+            // Not in mapping - keep original name
+            result[key] = value;
+        }
+    }
+    assertMappedSchema(result);
+    return result;
+}
+/**
+ * Validate all op names in a record.
+ * Throws if any name starts with underscore or is a reserved name.
+ */
+function validateAllOpNames(ops) {
+    for (const name of Object.keys(ops)) {
+        validateOpName(name);
+    }
+}
+// =============================================================================
+// OP GROUP CLASS - Phase 2 Architecture
+// =============================================================================
+/**
+ * OpGroup class - Holds ops as own properties with private field for mapping state.
+ *
+ * Why class-based:
+ * 1. Private fields don't pollute object shape (no hidden class impact)
+ * 2. Ops spread as own properties for direct access (`.request` not `.ops.request`)
+ * 3. Prototype methods (prefix/mapColumns) shared across instances
+ * 4. Same SpanBufferClass preserved across prefix() calls (shared schema + stats)
+ * 5. Only remappedViewClass differs between original and prefixed ops
+ *
+ * Structure enables V8 optimization:
+ * - All OpGroup instances with same ops have same hidden class
+ * - Private fields invisible to property enumeration
+ * - Method dispatch via prototype (no per-instance copies)
+ *
+ * Internal properties use underscore prefix (_logSchema, _flags) to avoid
+ * collision with user-defined op names.
+ */
+class OpGroupImpl {
+    _logSchema;
+    _flags;
+    // Private field - truly hidden, doesn't affect hidden class or enumeration
+    #columnMapping;
+    #ops;
+    constructor(_logSchema, _flags, ops, columnMapping) {
+        this._logSchema = _logSchema;
+        this._flags = _flags;
+        this.#columnMapping = columnMapping ?? {};
+        this.#ops = ops;
+        // Validate op names before spreading
+        validateAllOpNames(ops);
+        // Spread ops onto this instance as own properties
+        // Why spread: Enables direct access (ctx.deps.http.request)
+        for (const [name, op] of Object.entries(ops)) {
+            this[name] = op;
+        }
+    }
+    prefix(p) {
+        // Apply prefix to the current mapping
+        // Check if mapping is non-empty (empty object {} is truthy but has no entries)
+        const hasMapping = this.#columnMapping && Object.keys(this.#columnMapping).length > 0;
+        const newMapping = hasMapping
+            ? prefixMapping(this.#columnMapping, p)
+            : buildPrefixMapping(this._logSchema._columnNames, p);
+        // Generate RemappedBufferView for this prefix
+        // Why reverse mapping: Arrow conversion asks for 'http_status', needs to find 'status'
+        const reverseMapping = createReverseMapping(newMapping);
+        const remappedViewClass = generateRemappedBufferViewClass(reverseMapping);
+        // Create new OpGroup with prefixed ops
+        const newGroup = new MappedOpGroupImpl(this._logSchema, this._flags, cloneOpsWithView(this.#ops, remappedViewClass), newMapping, prefixContributedSchema(getSchemaFields(this._logSchema), p));
+        assertGroupCarriesOps(newGroup, this.#ops);
+        return newGroup;
+    }
+    mapColumns(mapping) {
+        // Override/extend the existing mapping with new mapping
+        const newMapping = { ...this.#columnMapping, ...mapping };
+        // Generate RemappedBufferView for this mapping
+        const reverseMapping = createReverseMapping(newMapping);
+        const remappedViewClass = generateRemappedBufferViewClass(reverseMapping);
+        // Build contributed schema from original fields with new mapping
+        const newContributed = buildContributedSchema(getSchemaFields(this._logSchema), newMapping);
+        // Create new OpGroup with mapped ops
+        const newGroup = new MappedOpGroupImpl(this._logSchema, this._flags, cloneOpsWithView(this.#ops, remappedViewClass), newMapping, newContributed);
+        assertGroupCarriesOps(newGroup, this.#ops);
+        return newGroup;
+    }
+}
+// =============================================================================
+// MAPPED OP GROUP CLASS
+// =============================================================================
+/**
+ * MappedOpGroup class - OpGroup with column mapping applied.
+ *
+ * Why separate class: TypeScript needs distinct type for mapped groups
+ * to track contributedSchema type parameter.
+ *
+ * Internal properties use underscore prefix to avoid collision with op names.
+ */
+class MappedOpGroupImpl {
+    _logSchema;
+    _flags;
+    _columnMapping;
+    _contributedSchema;
+    #columnMapping;
+    #ops;
+    constructor(_logSchema, _flags, ops, _columnMapping, _contributedSchema) {
+        this._logSchema = _logSchema;
+        this._flags = _flags;
+        this._columnMapping = _columnMapping;
+        this._contributedSchema = _contributedSchema;
+        this.#columnMapping = _columnMapping;
+        this.#ops = ops;
+        // Validate op names before spreading
+        validateAllOpNames(ops);
+        // Spread ops onto this instance
+        for (const [name, op] of Object.entries(ops)) {
+            this[name] = op;
+        }
+    }
+    prefix(p) {
+        // Apply prefix to the current mapping's target names
+        const newMapping = prefixMapping(this.#columnMapping, p);
+        // Generate RemappedBufferView
+        const reverseMapping = createReverseMapping(newMapping);
+        const remappedViewClass = generateRemappedBufferViewClass(reverseMapping);
+        // Build new contributed schema by prefixing current contributed schema
+        const newContributed = prefixContributedSchema(this._contributedSchema, p);
+        // Create new MappedOpGroup
+        const newGroup = new MappedOpGroupImpl(this._logSchema, this._flags, cloneOpsWithView(this.#ops, remappedViewClass), newMapping, newContributed);
+        assertGroupCarriesOps(newGroup, this.#ops);
+        return newGroup;
+    }
+    mapColumns(mapping) {
+        // Override/extend the existing mapping
+        const newMapping = { ...this.#columnMapping, ...mapping };
+        // Generate RemappedBufferView
+        const reverseMapping = createReverseMapping(newMapping);
+        const remappedViewClass = generateRemappedBufferViewClass(reverseMapping);
+        // Build contributed schema from current contributed fields so chained maps stay typed to the public surface.
+        const newContributed = buildContributedSchema(this._contributedSchema, mapping);
+        // Create new MappedOpGroup
+        const newGroup = new MappedOpGroupImpl(this._logSchema, this._flags, cloneOpsWithView(this.#ops, remappedViewClass), newMapping, newContributed);
+        assertGroupCarriesOps(newGroup, this.#ops);
+        return newGroup;
+    }
+}
+// =============================================================================
+// OP GROUP CREATION
+// =============================================================================
+/**
+ * Create an OpGroup from a schema, flags, and ops
+ *
+ * Why class-based: V8 hidden class optimization - all OpGroups with same ops
+ * have same object shape (private fields don't affect hidden class).
+ *
+ * The ops passed to this function already have a SpanBufferClass attached.
+ * All ops in the same context share the SAME SpanBufferClass instance, which carries:
+ * - Static schema property (shared by all instances)
+ * - Static stats property (shared mutable stats for self-tuning)
+ *
+ * The returned OpGroup can be:
+ * - Used directly as a dependency (ops accessible via ctx.deps.name.opName)
+ * - Prefixed with `.prefix('http')` to namespace all columns
+ * - Mapped with `.mapColumns({ query: 'query', _internal: null })` for fine control
+ *
+ * @param logSchema - The LogSchema defining columns for this group's ops
+ * @param flags - Feature flag schema
+ * @param ops - Record of Op instances belonging to this group
+ * @returns OpGroup with prefix() and mapColumns() methods, ops as own properties
+ *
+ * @example
+ * ```typescript
+ * const httpOps = createOpGroup(httpLogSchema, httpFlags, {
+ *   fetch: fetchOp,
+ *   post: postOp,
+ * });
+ *
+ * // Direct access (Phase 2):
+ * await ctx.deps.http.fetch(url);
+ *
+ * // Wire with prefix:
+ * deps: { http: httpOps.prefix('http') }
+ * // Columns become: http_status, http_url, http_duration, etc.
+ * ```
+ */
+export function createOpGroup(logSchema, flags, ops) {
+    const group = new OpGroupImpl(logSchema, flags, ops);
+    assertGroupCarriesOps(group, ops);
+    return group;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Op Definition Functions
+ *
+ * Factory functions for defining Ops and OpGroups. These are used internally
+ * by OpContextFactory to create type-safe Op definitions.
+ *
+ * @module opContext/defineOp
+ */
+import type { OpGroup, OpGroupOps } from './opGroupTypes.js';
+import type { Op, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
+import type { OpContext } from './types.js';
+/**
+ * Create OpMetadata with pre-encoded entries for Arrow dictionary building.
+ * Uses global interner to deduplicate UTF-8 bytes across all Ops with same strings.
+ */
+export declare function createOpMetadata(name: string, package_name: string, package_file: string, git_sha: string, line: number): OpMetadata;
+/**
+ * Default metadata values for Ops when not injected by transformer.
+ * These are placeholder values that will be replaced at compile time.
+ */
+export declare const DEFAULT_METADATA: OpMetadata;
+/**
+ * Extracts metadata from stack trace when transformer is not installed.
+ * Provides useful debugging info (file path, line number) even without build-time injection.
+ *
+ * Stack frame format varies by runtime:
+ * - V8 (Node/Chrome): "    at functionName (file:///path/to/file.ts:10:5)"
+ * - V8 anonymous:     "    at file:///path/to/file.ts:10:5"
+ * - JSC (Safari):     "functionName@file:///path/to/file.ts:10:5"
+ *
+ * @param skipFrames - Number of stack frames to skip (to get caller's location)
+ * @returns OpMetadata with extracted file path and line number
+ */
+export declare function extractMetadataFromStack(skipFrames?: number): OpMetadata;
+/**
+ * Configuration using OpContext bundle.
+ * Simplifies factory config by carrying all context types in one parameter.
+ */
+interface DefineOpFactoryConfig<Ctx extends OpContext> {
+    readonly logSchema: Ctx['logSchema'];
+    readonly flags: Ctx['flags'];
+    /** WHY: threaded to Op._opContextBinding so downstream can extract schema */
+    readonly opContextBinding?: import('./types.js').OpContextBinding;
+}
+/**
+ * Factory function type for creating OpGroups.
+ * Used by createDefineOps to delegate OpGroup creation.
+ */
+type CreateOpGroupFn<Ctx extends OpContext> = <Ops extends OpGroupOps<Ctx>>(logSchema: Ctx['logSchema'], flags: Ctx['flags'], ops: Ops) => OpGroup<Ctx, Ops>;
+/**
+ * Creates a defineOp function bound to a specific factory config.
+ *
+ * The returned function creates Op objects with:
+ * - metadata: includes name + merged with defaults
+ * - SpanBufferClass: from getSpanBufferClass(logSchema) - has static schema + stats
+ * - fn(ctx, ...args): the user function to execute
+ * - remappedViewClass: undefined for original ops (set by .prefix() method)
+ *
+ * @template Ctx - Bundled OpContext (logSchema, flags, deps, userCtx)
+ * @param factoryConfig - Configuration containing logSchema and flags
+ * @returns A defineOp function for creating Op instances
+ */
+export declare function createDefineOp<Ctx extends OpContext>(factoryConfig: DefineOpFactoryConfig<Ctx>): <Args extends unknown[], S, E>(name: string, fn: OpFn<Ctx, Args, S, E>, metadata?: Partial<OpMetadata>) => Op<Ctx, Args, S, E>;
+/**
+ * Creates a defineOps function bound to a specific factory config.
+ *
+ * The returned function:
+ * - Iterates over Object.entries(definitions)
+ * - For each [name, def]:
+ *   - If def is an Op instance, use it as-is
+ *   - Else wrap with defineOpImpl(name, def)
+ * - Stores all ops in a record
+ * - Creates OpGroup using createOpGroup(logSchema, flags, ops)
+ * - Returns Object.assign(opGroup, ops) to get both OpGroup methods and individual ops
+ *
+ * @template Ctx - Bundled OpContext (logSchema, flags, deps, userCtx)
+ * @param factoryConfig - Configuration containing logSchema and flags
+ * @param createOpGroup - Factory function for creating OpGroups
+ * @returns A defineOps function for creating OpGroups
+ */
+export declare function createDefineOps<Ctx extends OpContext>(factoryConfig: DefineOpFactoryConfig<Ctx>, createOpGroup: CreateOpGroupFn<Ctx>): <Defs extends Record<string, Op<Ctx, unknown[], unknown, unknown> | OpFn<Ctx, unknown[], unknown, unknown>>>(definitions: Defs & ThisType<OpsFromRecord<Ctx, Defs>>) => OpGroup<Ctx, OpsFromRecord<Ctx, Defs>>;
+export {};
+//# sourceMappingURL=defineOp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defineOp.d.ts","sourceRoot":"","sources":["../../../src/lib/opContext/defineOp.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,UAAU,CAYZ;AAMD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAA4E,CAAC;AAM5G;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,SAAI,GAAG,UAAU,CA6DnE;AAMD;;;GAGG;AACH,UAAU,qBAAqB,CAAC,GAAG,SAAS,SAAS;IACnD,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,YAAY,EAAE,gBAAgB,CAAC;CACnE;AAED;;;GAGG;AACH,KAAK,eAAe,CAAC,GAAG,SAAS,SAAS,IAAI,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EACxE,SAAS,EAAE,GAAG,CAAC,WAAW,CAAC,EAC3B,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,EACnB,GAAG,EAAE,GAAG,KACL,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAMvB;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,SAAS,SAAS,EAClD,aAAa,EAAE,qBAAqB,CAAC,GAAG,CAAC,GACxC,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,QAAQ,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,KAC3B,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CA0BvB;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,GAAG,SAAS,SAAS,EACnD,aAAa,EAAE,qBAAqB,CAAC,GAAG,CAAC,EACzC,aAAa,EAAE,eAAe,CAAC,GAAG,CAAC,GAClC,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,EAC5G,WAAW,EAAE,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,KACnD,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CA0B1C"}

package/dist/lib/opContext/defineOp.js

@@ -0,0 +1,197 @@
+/**
+ * Op Definition Functions
+ *
+ * Factory functions for defining Ops and OpGroups. These are used internally
+ * by OpContextFactory to create type-safe Op definitions.
+ *
+ * @module opContext/defineOp
+ */
+import { intern, PreEncodedEntry } from '@smoothbricks/arrow-builder';
+import { Op as OpClass } from '../op.js';
+import { getSpanBufferClass } from '../spanBuffer.js';
+// =============================================================================
+// METADATA HELPERS
+// =============================================================================
+/**
+ * Create OpMetadata with pre-encoded entries for Arrow dictionary building.
+ * Uses global interner to deduplicate UTF-8 bytes across all Ops with same strings.
+ */
+export function createOpMetadata(name, package_name, package_file, git_sha, line) {
+    return {
+        name,
+        package_name,
+        package_file,
+        git_sha,
+        line,
+        // Use global interner for deduplication - same package_name across Ops shares UTF-8 bytes
+        package_name_entry: new PreEncodedEntry(package_name, intern(package_name)),
+        package_file_entry: new PreEncodedEntry(package_file, intern(package_file)),
+        git_sha_entry: new PreEncodedEntry(git_sha, intern(git_sha)),
+    };
+}
+// =============================================================================
+// DEFAULT METADATA
+// =============================================================================
+/**
+ * Default metadata values for Ops when not injected by transformer.
+ * These are placeholder values that will be replaced at compile time.
+ */
+export const DEFAULT_METADATA = createOpMetadata('unknown', 'unknown', 'unknown', 'unknown', 0);
+// =============================================================================
+// STACK TRACE METADATA EXTRACTION
+// =============================================================================
+/**
+ * Extracts metadata from stack trace when transformer is not installed.
+ * Provides useful debugging info (file path, line number) even without build-time injection.
+ *
+ * Stack frame format varies by runtime:
+ * - V8 (Node/Chrome): "    at functionName (file:///path/to/file.ts:10:5)"
+ * - V8 anonymous:     "    at file:///path/to/file.ts:10:5"
+ * - JSC (Safari):     "functionName@file:///path/to/file.ts:10:5"
+ *
+ * @param skipFrames - Number of stack frames to skip (to get caller's location)
+ * @returns OpMetadata with extracted file path and line number
+ */
+export function extractMetadataFromStack(skipFrames = 2) {
+    const err = new Error();
+    const stack = err.stack;
+    if (!stack) {
+        return DEFAULT_METADATA;
+    }
+    const lines = stack.split('\n');
+    // Skip "Error" line + specified frames to get to caller
+    // Frame 0: Error
+    // Frame 1: extractMetadataFromStack
+    // Frame 2: defineOpImpl (or caller)
+    // Frame 3: actual defineOp call site
+    const targetFrame = lines[skipFrames + 1];
+    if (!targetFrame) {
+        return DEFAULT_METADATA;
+    }
+    // Try V8 format: "    at functionName (file:///path/to/file.ts:10:5)"
+    // or anonymous: "    at file:///path/to/file.ts:10:5"
+    let match = targetFrame.match(/at\s+(?:.*?\s+\()?(.+?):(\d+):\d+\)?$/);
+    // Try JSC format: "functionName@file:///path/to/file.ts:10:5"
+    if (!match) {
+        match = targetFrame.match(/@(.+?):(\d+):\d+$/);
+    }
+    if (!match) {
+        return DEFAULT_METADATA;
+    }
+    let filePath = match[1];
+    const lineNumber = Number.parseInt(match[2], 10);
+    // Clean up file:// protocol if present
+    if (filePath.startsWith('file://')) {
+        filePath = filePath.slice(7);
+    }
+    // Extract package name from path (last directory component before src/)
+    // e.g., "/path/to/my-package/src/ops.ts" -> "my-package"
+    let packageName = 'unknown';
+    const srcIndex = filePath.lastIndexOf('/src/');
+    if (srcIndex > 0) {
+        const beforeSrc = filePath.slice(0, srcIndex);
+        const lastSlash = beforeSrc.lastIndexOf('/');
+        if (lastSlash >= 0) {
+            packageName = beforeSrc.slice(lastSlash + 1);
+        }
+    }
+    else {
+        // Fallback: use filename without extension
+        const lastSlash = filePath.lastIndexOf('/');
+        const fileName = lastSlash >= 0 ? filePath.slice(lastSlash + 1) : filePath;
+        const dotIndex = fileName.lastIndexOf('.');
+        packageName = dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
+    }
+    return createOpMetadata('unknown', packageName, filePath, 'runtime', lineNumber);
+}
+// =============================================================================
+// CREATE DEFINE OP
+// =============================================================================
+/**
+ * Creates a defineOp function bound to a specific factory config.
+ *
+ * The returned function creates Op objects with:
+ * - metadata: includes name + merged with defaults
+ * - SpanBufferClass: from getSpanBufferClass(logSchema) - has static schema + stats
+ * - fn(ctx, ...args): the user function to execute
+ * - remappedViewClass: undefined for original ops (set by .prefix() method)
+ *
+ * @template Ctx - Bundled OpContext (logSchema, flags, deps, userCtx)
+ * @param factoryConfig - Configuration containing logSchema and flags
+ * @returns A defineOp function for creating Op instances
+ */
+export function createDefineOp(factoryConfig) {
+    // Why get class from schema: Class has static schema + stats shared by all instances
+    const SpanBufferClass = getSpanBufferClass(factoryConfig.logSchema);
+    return function defineOpImpl(name, fn, metadata) {
+        // When transformer is not installed, extract metadata from stack trace
+        // This provides useful file/line info for debugging even without build-time injection
+        // skipFrames=3: Error -> extractMetadataFromStack -> defineOpImpl -> caller
+        const baseMetadata = metadata?.package_file ? DEFAULT_METADATA : extractMetadataFromStack(3);
+        // Use name from: 1) explicit metadata.name (transformer), 2) defineOp('name', fn), 3) baseMetadata
+        const finalMetadata = { ...baseMetadata, ...metadata, name: metadata?.name ?? name };
+        // Use the Op class which handles all span/buffer management:
+        // - Creates SpanBuffer for the op
+        // - Registers child buffers with parent
+        // - Sets _opMetadata and _callsiteMetadata
+        // - Writes span-start/span-ok/span-err entries
+        // - Handles exceptions with span-exception
+        // Why SpanBufferClass: All ops from same defineOpContext share this class for stats coordination
+        // Why undefined for remappedViewClass: Only prefixed ops need remapping - set by .prefix() method
+        return new OpClass(finalMetadata, SpanBufferClass, fn, undefined, factoryConfig.opContextBinding);
+    };
+}
+// =============================================================================
+// CREATE DEFINE OPS
+// =============================================================================
+/**
+ * Type guard to check if a definition is an existing Op instance.
+ */
+function isOp(def) {
+    return def instanceof OpClass;
+}
+function hasAllDefinedOps(definitions, ops) {
+    for (const name in definitions) {
+        if (!(name in ops)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Creates a defineOps function bound to a specific factory config.
+ *
+ * The returned function:
+ * - Iterates over Object.entries(definitions)
+ * - For each [name, def]:
+ *   - If def is an Op instance, use it as-is
+ *   - Else wrap with defineOpImpl(name, def)
+ * - Stores all ops in a record
+ * - Creates OpGroup using createOpGroup(logSchema, flags, ops)
+ * - Returns Object.assign(opGroup, ops) to get both OpGroup methods and individual ops
+ *
+ * @template Ctx - Bundled OpContext (logSchema, flags, deps, userCtx)
+ * @param factoryConfig - Configuration containing logSchema and flags
+ * @param createOpGroup - Factory function for creating OpGroups
+ * @returns A defineOps function for creating OpGroups
+ */
+export function createDefineOps(factoryConfig, createOpGroup) {
+    // Get the defineOp function for wrapping raw functions
+    const defineOp = createDefineOp(factoryConfig);
+    return function defineOpsImpl(definitions) {
+        // Build the ops record by processing each definition.
+        // Keep the runtime container broad, then narrow once we've populated every key.
+        const ops = {};
+        for (const name in definitions) {
+            const def = definitions[name];
+            ops[name] = isOp(def) ? def : defineOp(name, def);
+        }
+        if (!hasAllDefinedOps(definitions, ops)) {
+            throw new Error('defineOps failed to normalize all op definitions');
+        }
+        // Create the OpGroup
+        const opGroup = createOpGroup(factoryConfig.logSchema, factoryConfig.flags, ops);
+        // Return OpGroup merged with individual ops for direct access
+        return Object.assign(opGroup, ops);
+    };
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Feature Flag Types for Op-Centric API
+ *
+ * This module contains type definitions for feature flags used in the Op-centric API.
+ * Feature flags allow for runtime toggling of functionality with type-safe evaluation.
+ *
+ * Key concepts:
+ * - FeatureFlagSchema: Defines what flags exist and their types
+ * - BoundFeatureFlags: Typed accessor for flag values bound to a span context
+ *
+ * For the FlagEvaluator interface (getSync/getAsync/forContext), see:
+ * - packages/lmao/src/lib/schema/evaluator.ts
+ */
+import type { FluentLogEntry } from '../codegen/spanLoggerGenerator.js';
+import type { LogSchema } from '../schema/LogSchema.js';
+import type { FeatureFlagDefinition } from '../schema/types.js';
+/**
+ * Feature flag schema - defines what flags are available and their types
+ */
+export interface FeatureFlagSchema {
+    [key: string]: FeatureFlagDefinition<string | number | boolean>;
+}
+/**
+ * Feature flag accessor bound to a span context
+ * Provides typed getters for each defined flag
+ *
+ * Access patterns:
+ * - Sync flags: `ctx.ff.myFlag` returns `{ value: T, track(context?): FluentLogEntry } | undefined`
+ * - Async flags: `await ctx.ff.get('myFlag')` returns `{ value: T, track(context?): FluentLogEntry } | undefined`
+ *
+ * Returns `undefined` when flag is false/disabled.
+ * Returns wrapper object when flag is truthy/enabled, with `.track()` for usage analytics.
+ */
+export type BoundFeatureFlags<FF extends FeatureFlagSchema> = {
+    readonly [K in keyof FF]: FF[K] extends FeatureFlagDefinition<infer V, 'sync'> ? {
+        value: V;
+        track(context?: {
+            action?: string;
+            outcome?: string;
+        }): FluentLogEntry<LogSchema>;
+    } | undefined : FF[K] extends FeatureFlagDefinition<infer V, 'async'> ? {
+        value: V;
+        track(context?: {
+            action?: string;
+            outcome?: string;
+        }): FluentLogEntry<LogSchema>;
+    } | undefined : never;
+} & {
+    /** Get async flag value. Returns undefined when false, FlagContext when truthy. */
+    get(flag: string): Promise<{
+        value: unknown;
+        track(context?: {
+            action?: string;
+            outcome?: string;
+        }): FluentLogEntry<LogSchema>;
+    } | undefined>;
+};
+//# sourceMappingURL=featureFlagTypes.d.ts.map