@smoothbricks/lmao 0.2.2 → 0.3.0

package/src/lib/opContext/defineOp.ts

@@ -9,9 +9,11 @@
 
 import { intern, PreEncodedEntry } from '@smoothbricks/arrow-builder';
 import { Op as OpClass } from '../op.js';
+import { resolveEagerColumns } from '../physicalLayoutPlan.js';
+import { runtimeHintMessageLayoutFamily, runtimeHintMessagePhysicalLayout } from '../runtimeHint.js';
 import { getSpanBufferClass } from '../spanBuffer.js';
 import type { OpGroup, OpGroupOps } from './opGroupTypes.js';
-import type { Op, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
+import type { Op, OpCompileMetadata, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
 import type { OpContext } from './types.js';
 
 //#region smoo/lmao!n/metadata-injection
@@ -57,6 +59,31 @@ export function createOpMetadata(
  */
 export const DEFAULT_METADATA: OpMetadata = createOpMetadata('unknown', 'unknown', 'unknown', 'unknown', 0);
 
+const DEFAULT_COMPILE_METADATA: OpCompileMetadata = Object.freeze({
+  runtimeHint: 0,
+});
+
+const EMPTY_EAGER_COLUMNS: readonly string[] = Object.freeze([]);
+const EMPTY_LOCAL_MESSAGE_DICTIONARY: readonly number[] = Object.freeze([]);
+
+function normalizeCompileMetadata(compileMetadata?: OpCompileMetadata): OpCompileMetadata {
+  if (compileMetadata === undefined) return DEFAULT_COMPILE_METADATA;
+  const eagerColumns = compileMetadata.eagerColumns;
+  const localMessageDictionary = compileMetadata.localMessageDictionary;
+  return Object.freeze({
+    runtimeHint: compileMetadata.runtimeHint,
+    eagerColumns:
+      eagerColumns === undefined || eagerColumns.length === 0
+        ? EMPTY_EAGER_COLUMNS
+        : Object.freeze([...new Set(eagerColumns)]),
+    localMessageDictionary:
+      localMessageDictionary === undefined || localMessageDictionary.length === 0
+        ? EMPTY_LOCAL_MESSAGE_DICTIONARY
+        : Object.freeze([...localMessageDictionary]),
+    materializeSpanBufferClass: compileMetadata.materializeSpanBufferClass,
+  });
+}
+
 // =============================================================================
 // STACK TRACE METADATA EXTRACTION
 // =============================================================================
@@ -173,7 +200,7 @@ type CreateOpGroupFn<Ctx extends OpContext> = <Ops extends OpGroupOps<Ctx>>(
  * - 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)
+ * - remapDescriptor: undefined for original ops (set by .prefix()/.mapColumns())
  *
  * @template Ctx - Bundled OpContext (logSchema, flags, deps, userCtx)
  * @param factoryConfig - Configuration containing logSchema and flags
@@ -185,21 +212,39 @@ export function createDefineOp<Ctx extends OpContext>(
   name: string,
   fn: OpFn<Ctx, Args, S, E>,
   metadata?: Partial<OpMetadata>,
+  compileMetadata?: OpCompileMetadata,
 ) => Op<Ctx, Args, S, E> {
-  // Why get class from schema: Class has static schema + stats shared by all instances
-  const SpanBufferClass = getSpanBufferClass(factoryConfig.logSchema);
-
   return function defineOpImpl<Args extends unknown[], S, E>(
     name: string,
     fn: OpFn<Ctx, Args, S, E>,
     metadata?: Partial<OpMetadata>,
+    compileMetadata?: OpCompileMetadata,
   ): Op<Ctx, Args, S, E> {
+    const normalizedCompileMetadata = normalizeCompileMetadata(compileMetadata);
+    normalizedCompileMetadata.materializeSpanBufferClass?.(factoryConfig.logSchema);
+    const eagerColumns = resolveEagerColumns(
+      factoryConfig.logSchema,
+      normalizedCompileMetadata.eagerColumns ?? EMPTY_EAGER_COLUMNS,
+    );
+    const messageLayoutFamily = runtimeHintMessageLayoutFamily(normalizedCompileMetadata.runtimeHint);
+    const messagePhysicalLayout = runtimeHintMessagePhysicalLayout(normalizedCompileMetadata.runtimeHint);
+    const SelectedSpanBufferClass = getSpanBufferClass(
+      factoryConfig.logSchema,
+      messageLayoutFamily,
+      messagePhysicalLayout,
+      eagerColumns,
+    );
+
     // 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 };
+    const finalMetadata: OpMetadata = {
+      ...baseMetadata,
+      ...metadata,
+      name: metadata?.name ?? name,
+    };
 
     // Use the Op class which handles all span/buffer management:
     // - Creates SpanBuffer for the op
@@ -207,9 +252,18 @@ export function createDefineOp<Ctx extends OpContext>(
     // - 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);
+    // Why SelectedSpanBufferClass: Ops with the same physical layout share one constructor and stats object.
+    // Base Ops have no remap descriptor; mapped OpGroups bind one during startup cloning.
+    return new OpClass(
+      finalMetadata,
+      SelectedSpanBufferClass,
+      fn,
+      undefined,
+      factoryConfig.opContextBinding,
+      normalizedCompileMetadata.runtimeHint,
+      normalizedCompileMetadata.eagerColumns ?? EMPTY_EAGER_COLUMNS,
+      normalizedCompileMetadata.localMessageDictionary ?? EMPTY_LOCAL_MESSAGE_DICTIONARY,
+    );
   };
 }
 
@@ -258,20 +312,43 @@ export function createDefineOps<Ctx extends OpContext>(
   createOpGroup: CreateOpGroupFn<Ctx>,
 ): <Defs extends Record<string, Op<Ctx, unknown[], unknown, unknown> | OpFn<Ctx, unknown[], unknown, unknown>>>(
   definitions: Defs & ThisType<OpsFromRecord<Ctx, Defs>>,
+  compileMetadataByKey?: Partial<Record<keyof Defs, OpCompileMetadata>>,
 ) => OpGroup<Ctx, OpsFromRecord<Ctx, Defs>> {
   // Get the defineOp function for wrapping raw functions
   const defineOp = createDefineOp<Ctx>(factoryConfig);
 
   return function defineOpsImpl<
     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>> {
+  >(
+    definitions: Defs & ThisType<OpsFromRecord<Ctx, Defs>>,
+    compileMetadataByKey?: Partial<Record<keyof Defs, OpCompileMetadata>>,
+  ): OpGroup<Ctx, OpsFromRecord<Ctx, Defs>> {
     // Build the ops record by processing each definition.
     // Keep the runtime container broad, then narrow once we've populated every key.
     const ops: Record<string, Op<Ctx, unknown[], unknown, unknown>> = {};
 
     for (const name in definitions) {
       const def = definitions[name];
-      ops[name] = isOp<Ctx>(def) ? def : defineOp(name, def);
+      const compileMetadata = compileMetadataByKey?.[name];
+      if (isOp<Ctx>(def)) {
+        if (compileMetadata === undefined) {
+          ops[name] = def;
+        } else {
+          const normalizedCompileMetadata = normalizeCompileMetadata(compileMetadata);
+          ops[name] = new OpClass(
+            def.metadata,
+            def.callsitePlan.SpanBufferClass,
+            def.fn,
+            def.callsitePlan.remapDescriptor ?? undefined,
+            def._opContextBinding,
+            normalizedCompileMetadata.runtimeHint,
+            normalizedCompileMetadata.eagerColumns ?? EMPTY_EAGER_COLUMNS,
+            normalizedCompileMetadata.localMessageDictionary ?? EMPTY_LOCAL_MESSAGE_DICTIONARY,
+          );
+        }
+      } else {
+        ops[name] = defineOp(name, def, undefined, compileMetadata);
+      }
     }
 
     if (!hasAllDefinedOps(definitions, ops)) {

package/src/lib/opContext/opGroupTypes.ts

@@ -164,8 +164,8 @@ export type OpGroup<Ctx extends OpContext, Ops extends object = NoOpMembers> = O
 /**
  * An OpGroup with column mapping applied.
  *
- * The mapping is used during wiring to create RemappedBufferView
- * that translates the library's column writes to the app's column names.
+ * Wiring composes the mapping into immutable metadata interpreted only by cold
+ * Arrow conversion; library child buffers keep their canonical storage layout.
  *
  * Note: Ops are accessed directly as properties (`.opName` not `.ops.opName`)
  * for V8 hidden class optimization and cleaner API ergonomics.

package/src/lib/opContext/opTypes.ts

@@ -24,7 +24,7 @@ import type { OpContext } from './types.js';
 // Re-export the Op class and OpMetadata from op.ts - single source of truth
 // The class is defined in op.ts to be the canonical type used by both
 // defineOp (creates instances) and Tracer (checks instanceof)
-export { Op, type OpMetadata } from '../op.js';
+export { Op, type OpCompileMetadata, type OpMetadata } from '../op.js';
 
 // =============================================================================
 // OP FUNCTION TYPE

package/src/lib/opContext/spanContextTypes.ts

@@ -28,21 +28,38 @@ import type { Op } from './opTypes.js';
 import type { OpContext } from './types.js';
 
 // =============================================================================
-// DEPENDENCY TYPES (structural to avoid circular imports)
+// DEPENDENCY TYPES (deliberate `any` placeholders — see rationale below)
 // =============================================================================
 
+// WHY these are `any` and not the real `DepsConfig`/`ResolvedDeps` from opGroupTypes:
+//
+// `ResolvedDeps<D>` maps each dep to `OpGroup<Ctx, Ops>`, and an OpGroup's ops carry
+// `SpanContext<DepCtx>` in their signatures. If `SpanContext` referenced the *real*
+// `ResolvedDeps<Ctx['deps']>` for its `deps` member, `SpanContext` would become
+// structurally recursive: deps -> OpGroup -> op -> SpanContext -> deps -> ...
+//
+// That recursion breaks the structural assignability TypeScript performs when a
+// dependency's op is passed to `ctx.span(name, ctx.deps.x.op)` across libraries
+// (verified: it regresses the nested-library-tasks composition tests) and makes
+// type comparison cost explode. The `any` keeps `ctx.deps.x.op` ergonomic for op
+// authors while keeping `SpanContext` comparisons tractable and non-recursive.
+//
+// A real fix (fully-typed `ctx.deps`) requires reworking deps resolution so the
+// resolved-deps view does not pull `SpanContext` back into its own definition.
+// Until then these placeholders are load-bearing, not laziness.
+
 /**
- * DepsConfig - structural type to avoid importing from opGroupTypes.
- * Represents a record of dependency groups.
+ * DepsConfig - structural placeholder for a record of dependency groups.
+ * The authoritative type is `DepsConfig` in opGroupTypes; see the WHY above.
  */
-// biome-ignore lint/suspicious/noExplicitAny: Structural placeholder - actual type in opGroupTypes
+// biome-ignore lint/suspicious/noExplicitAny: load-bearing placeholder — real type makes SpanContext recursive (see WHY above)
 export type DepsConfig = Record<string, any>;
 
 /**
- * ResolvedDeps - structural type to avoid importing from opGroupTypes.
- * At runtime, deps are resolved OpGroups with their ops accessible.
+ * ResolvedDeps - structural placeholder for resolved dependency OpGroups.
+ * The authoritative type is `ResolvedDeps` in opGroupTypes; see the WHY above.
  */
-// biome-ignore lint/suspicious/noExplicitAny: Structural placeholder - actual type in opGroupTypes
+// biome-ignore lint/suspicious/noExplicitAny: load-bearing placeholder — real type makes SpanContext recursive (see WHY above)
 export type ResolvedDeps<_D extends DepsConfig> = Record<string, any>;
 
 // =============================================================================
@@ -68,24 +85,29 @@ export type TagWriter<T extends LogSchema> = {
 /**
  * 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.
+ * Operational info/warn/error calls accept either a static template or the
+ * untransformed fallback form `(template, fields)`. Debug/trace retain the raw
+ * dynamic message API. The transformer lowers supported calls to direct writes;
+ * internal methods and buffers remain 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()
+ * Per specs/lmao/01h_entry_types_and_logging_primitives.md, each call creates
+ * exactly one log entry. The generated runtime implementation binds structured
+ * fallback fields to the schema-specific column writers.
  */
 export interface SpanLogger<T extends LogSchema> {
-  /** Log at info level */
-  info(message: string): FluentLogEntry<T>;
+  /** Log a static info template, optionally with schema-bound fallback fields */
+  info(template: string): FluentLogEntry<T>;
+  info(template: string, fields: Partial<InferSchema<T>>): 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>;
+  /** Log a static warn template, optionally with schema-bound fallback fields */
+  warn(template: string): FluentLogEntry<T>;
+  warn(template: string, fields: Partial<InferSchema<T>>): FluentLogEntry<T>;
+  /** Log a static error template, optionally with schema-bound fallback fields */
+  error(template: string): FluentLogEntry<T>;
+  error(template: string, fields: Partial<InferSchema<T>>): FluentLogEntry<T>;
+  /** Log at trace level */
+  trace(message: string): FluentLogEntry<T>;
 }
 
 /**
@@ -208,10 +230,7 @@ export type SpanFn<Ctx extends OpContext> = {
  * 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>;
+export type SpanSyncFn<Ctx extends OpContext> = <S, E>(name: string, op: Op<Ctx, [], S, E>) => Result<S, E>;
 
 // =============================================================================
 // SPAN CONTEXT TYPE
@@ -359,6 +378,85 @@ export type SpanContext<Ctx extends OpContext> = {
    */
   spanSync: SpanSyncFn<Ctx>;
 
+  /** @internal Transformer-only fixed-arity sync-fast span ABI. */
+  spanAuto0<S, E>(line: number, name: string, op: Op<Ctx, [], S, E>): Result<S, E> | Promise<Result<S, E>>;
+  spanAuto1<S, E, A1>(
+    line: number,
+    name: string,
+    op: Op<Ctx, [A1], S, E>,
+    a1: A1,
+  ): Result<S, E> | Promise<Result<S, E>>;
+  spanAuto2<S, E, A1, A2>(
+    line: number,
+    name: string,
+    op: Op<Ctx, [A1, A2], S, E>,
+    a1: A1,
+    a2: A2,
+  ): Result<S, E> | Promise<Result<S, E>>;
+  spanAuto3<S, E, A1, A2, A3>(
+    line: number,
+    name: string,
+    op: Op<Ctx, [A1, A2, A3], S, E>,
+    a1: A1,
+    a2: A2,
+    a3: A3,
+  ): Result<S, E> | Promise<Result<S, E>>;
+  spanAuto4<S, E, A1, A2, A3, A4>(
+    line: number,
+    name: string,
+    op: Op<Ctx, [A1, A2, A3, A4], S, E>,
+    a1: A1,
+    a2: A2,
+    a3: A3,
+    a4: A4,
+  ): Result<S, E> | Promise<Result<S, E>>;
+  spanAuto5<S, E, A1, A2, A3, A4, A5>(
+    line: number,
+    name: string,
+    op: Op<Ctx, [A1, A2, A3, A4, A5], S, E>,
+    a1: A1,
+    a2: A2,
+    a3: A3,
+    a4: A4,
+    a5: A5,
+  ): Result<S, E> | Promise<Result<S, E>>;
+  spanAuto6<S, E, A1, A2, A3, A4, A5, A6>(
+    line: number,
+    name: string,
+    op: Op<Ctx, [A1, A2, A3, A4, A5, A6], S, E>,
+    a1: A1,
+    a2: A2,
+    a3: A3,
+    a4: A4,
+    a5: A5,
+    a6: A6,
+  ): Result<S, E> | Promise<Result<S, E>>;
+  spanAuto7<S, E, A1, A2, A3, A4, A5, A6, A7>(
+    line: number,
+    name: string,
+    op: Op<Ctx, [A1, A2, A3, A4, A5, A6, A7], S, E>,
+    a1: A1,
+    a2: A2,
+    a3: A3,
+    a4: A4,
+    a5: A5,
+    a6: A6,
+    a7: A7,
+  ): Result<S, E> | Promise<Result<S, E>>;
+  spanAuto8<S, E, A1, A2, A3, A4, A5, A6, A7, A8>(
+    line: number,
+    name: string,
+    op: Op<Ctx, [A1, A2, A3, A4, A5, A6, A7, A8], S, E>,
+    a1: A1,
+    a2: A2,
+    a3: A3,
+    a4: A4,
+    a5: A5,
+    a6: A6,
+    a7: A7,
+    a8: A8,
+  ): Result<S, E> | Promise<Result<S, E>>;
+
   /**
    * Set scoped attributes that auto-propagate to all subsequent log entries.
    *

package/src/lib/opContext/types.ts

@@ -52,7 +52,7 @@ export type {
   UnionToIntersection,
 } from './opGroupTypes.js';
 // Op types (metadata, function signature, instance)
-export type { Op, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
+export type { Op, OpCompileMetadata, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
 // SpanContext types (tag writer, logger, span function, full context)
 export type { FluentLogEntry, SpanContext, SpanFn, SpanLogger, SpanSyncFn, TagWriter } from './spanContextTypes.js';
 
@@ -120,7 +120,7 @@ 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';
+import type { Op, OpCompileMetadata, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
 
 /**
  * Configuration for defineOpContext
@@ -351,6 +351,7 @@ export interface OpContextFactory<
     name: string,
     fn: OpFn<OpContext<T, FF, Deps, UserCtx>, Args, S, E>,
     metadata?: Partial<OpMetadata>,
+    compileMetadata?: OpCompileMetadata,
   ): Op<OpContext<T, FF, Deps, UserCtx>, Args, S, E>;
 
   /**
@@ -399,5 +400,8 @@ export interface OpContextFactory<
       | 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>>;
+  >(
+    definitions: Defs,
+    compileMetadataByKey?: Partial<Record<keyof Defs, OpCompileMetadata>>,
+  ): OpGroup<OpContext<T, FF, Deps, UserCtx>, OpsFromRecord<OpContext<T, FF, Deps, UserCtx>, Defs>>;
 }