@smoothbricks/lmao 0.1.0

package/src/lib/logApi.ts

@@ -0,0 +1,70 @@
+/**
+ * LogAPI - Simple logging interface for contexts that need structured logging
+ * without direct access to a SpanBuffer.
+ *
+ * Used by:
+ * - Other contexts where a simplified logging interface is needed
+ *
+ * Unlike SpanLogger which is tightly coupled to a SpanBuffer and returns
+ * FluentLogEntry for chaining, LogAPI is a simple fire-and-forget interface
+ * that can be backed by any logging implementation.
+ */
+
+/**
+ * Structured logging API.
+ *
+ * Provides info/warn/error/debug methods with optional structured data.
+ * Implementation determines where logs are written (span buffer, console, etc).
+ *
+ * @example
+ * ```typescript
+ * function decide(ctx) {
+ *   ctx.log.info('Processing order', { orderId: ctx.instanceId });
+ *   if (!ctx.state.inventory) {
+ *     ctx.log.warn('No inventory data', { state: ctx.state });
+ *   }
+ * }
+ * ```
+ */
+export interface LogAPI {
+  /**
+   * Log at info level.
+   * @param message - Log message
+   * @param data - Optional structured data to include with the log
+   */
+  info(message: string, data?: Record<string, unknown>): void;
+
+  /**
+   * Log at warn level.
+   * @param message - Log message
+   * @param data - Optional structured data to include with the log
+   */
+  warn(message: string, data?: Record<string, unknown>): void;
+
+  /**
+   * Log at error level.
+   * @param message - Log message
+   * @param data - Optional structured data to include with the log
+   */
+  error(message: string, data?: Record<string, unknown>): void;
+
+  /**
+   * Log at debug level.
+   * @param message - Log message
+   * @param data - Optional structured data to include with the log
+   */
+  debug(message: string, data?: Record<string, unknown>): void;
+}
+
+/**
+ * No-op LogAPI implementation.
+ *
+ * Used when tracing is disabled or for testing contexts that don't
+ * need actual logging.
+ */
+export const noopLogAPI: LogAPI = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+};

package/src/lib/logBinding.ts

@@ -0,0 +1,67 @@
+/**
+ * LogBinding - Logging infrastructure binding for ops and buffers
+ *
+ * Represents the binding between a set of operations and their logging infrastructure.
+ * Contains the schema and optional remapping support for prefixed modules.
+ *
+ * Note: Buffer stats (self-tuning capacity) are stored on SpanBufferClass.stats as static
+ * properties, NOT on LogBinding. See agent-todo/opgroup-refactor.md for rationale.
+ *
+ * Per specs:
+ * - 01b2_buffer_self_tuning.md - Self-tuning via SpanBufferClass.stats
+ * - 01e_library_integration_pattern.md - Library prefix/remapping support
+ */
+
+import type { LogSchema } from './schema/LogSchema.js';
+
+// Type-only import keeps this file runtime-safe while preserving buffer shape information.
+type SpanBuffer = import('./types.js').AnySpanBuffer;
+
+/**
+ * RemappedViewConstructor - Constructor type for RemappedBufferView classes.
+ *
+ * Generated at module composition time (cold path) by `generateRemappedBufferViewClass()`.
+ * Used by prefixed modules to wrap SpanBuffer instances for Arrow conversion when
+ * the module's schema columns have been renamed with a prefix.
+ *
+ * The constructor takes a raw SpanBuffer and returns a view that remaps column access
+ * from prefixed names to unprefixed names for tree traversal during Arrow conversion.
+ *
+ * Per specs/lmao/01e_library_integration_pattern.md:
+ * - Hot path: Library writes directly to unprefixed columns (zero overhead)
+ * - Cold path: Arrow conversion uses RemappedBufferView to access via prefixed names
+ */
+export type RemappedViewConstructor = new (buffer: SpanBuffer) => SpanBuffer;
+
+/**
+ * LogBinding - Everything needed for a group of ops to write logs.
+ *
+ * Represents the binding between a set of operations and their logging infrastructure.
+ * Contains the schema and optional remapping support for prefixed modules.
+ *
+ * Note: Buffer stats (self-tuning capacity) are stored on SpanBufferClass.stats as static
+ * properties, NOT on LogBinding. This avoids sync bugs from having two stat objects and
+ * reduces per-instance memory. See agent-todo/opgroup-refactor.md for rationale.
+ *
+ * Per specs:
+ * - 01b2_buffer_self_tuning.md - Self-tuning via SpanBufferClass.stats
+ * - 01e_library_integration_pattern.md - Library prefix/remapping support
+ *
+ * @property logSchema - The unprefixed schema defining what columns can be written.
+ *   This is the canonical schema. Column names in remappedViewClass will be prefixed versions
+ *   of these field names when a prefix or column mapping has been applied.
+ *
+ * @property remappedViewClass - Optional RemappedBufferView class for prefixed/remapped buffers.
+ *   - When present: the module's ops write to unprefixed columns, but buffers must be wrapped
+ *     in this view for Arrow conversion to access them by prefixed names
+ *   - When absent: buffers can be used directly without remapping
+ *   - Set during module composition when prefix() or mapColumns() is applied (cold path)
+ *   - Used when registering child spans to parent's tree (see op.ts)
+ */
+export interface LogBinding<T extends LogSchema = LogSchema> {
+  /** The unprefixed schema defining what columns exist */
+  readonly logSchema: T;
+
+  /** Optional RemappedBufferView class for prefixed/remapped buffers */
+  readonly remappedViewClass?: RemappedViewConstructor;
+}

package/src/lib/op.ts

@@ -0,0 +1,103 @@
+/**
+ * Op - Traced operation class and OpMetadata
+ *
+ * This is the single source of truth for the Op class and OpMetadata interface.
+ * Other modules re-export these types for convenience.
+ *
+ * Wraps a user function with automatic span tracking.
+ * Created by defineOp() from the Op-centric API (defineOpContext).
+ *
+ * Per specs/lmao/01l_op_context_pattern.md and specs/lmao/01c_context_flow_and_op_wrappers.md:
+ * - Captures OpMetadata for attribution (package_name, package_file, git_sha, line)
+ * - fn is called by span_op() after span_op creates the SpanBuffer/SpanContext
+ * - Op name is used for metrics tracking (separate from span names)
+ */
+
+import type { PreEncodedEntry } from '@smoothbricks/arrow-builder';
+import type { RemappedViewConstructor } from './logBinding.js';
+import type { SpanContext } from './opContext/spanContextTypes.js';
+import type { OpContext, OpContextBinding } from './opContext/types.js';
+import type { Result } from './result.js';
+import type { SpanBufferConstructor } from './spanBuffer.js';
+
+// =============================================================================
+// OP METADATA
+// =============================================================================
+
+/**
+ * Metadata injected by the transformer into each Op.
+ * These values are determined at compile time from the source location.
+ *
+ * Includes pre-encoded UTF-8 entries for Arrow dictionary building -
+ * encode once at Op definition time, reuse for every span conversion.
+ */
+export interface OpMetadata {
+  /** Op name for metrics tracking (distinct from span names which are provided at call sites) */
+  readonly name: string;
+  /** Package name from package.json */
+  readonly package_name: string;
+  /** File path relative to package root */
+  readonly package_file: string;
+  /** Git SHA at build time */
+  readonly git_sha: string;
+  /** Line number where defineOp was called */
+  readonly line: number;
+
+  /** Pre-encoded package_name for Arrow dictionary building */
+  readonly package_name_entry: PreEncodedEntry;
+  /** Pre-encoded package_file for Arrow dictionary building */
+  readonly package_file_entry: PreEncodedEntry;
+  /** Pre-encoded git_sha for Arrow dictionary building */
+  readonly git_sha_entry: PreEncodedEntry;
+}
+
+// =============================================================================
+// Op Class
+// =============================================================================
+
+/**
+ * Op - Traced operation (Phase 2 architecture)
+ *
+ * Per spec 01l lines 436-453 and 01c lines 292-362:
+ * - Wraps a user function with automatic span tracking
+ * - Captures module metadata for attribution
+ * - fn is public and called by span_op() after buffer/context creation
+ *
+ * Type parameter order matches function signature: (ctx: SpanContext<Ctx>, ...args: Args) => Result<S, E>
+ *
+ * Op has TWO names:
+ * - `name`: The Op's name for metrics (invocations, errors, duration tracking)
+ * - Span names are provided at CALL SITE: `await span('contextual-name', myOp, args)`
+ *
+ * Op captures the metadata for source attribution:
+ * - When span() invokes this Op, the Op's metadata becomes buffer._opMetadata (for rows 1+)
+ * - The caller's metadata becomes buffer._callsiteMetadata (for row 0)
+ *
+ * Phase 2 architecture:
+ * - SpanBufferClass carries static schema + stats (shared by all ops from same defineOpContext)
+ * - remappedViewClass only set for prefixed ops (wraps child buffers before adding to _children)
+ * - No LogBinding - stats accessed via SpanBufferClass.stats
+ *
+ * @typeParam Ctx - OpContext with deps, ff, env (contravariant position)
+ * @typeParam Args - Tuple of argument types (excluding ctx)
+ * @typeParam S - Success type of the Result
+ * @typeParam E - Error type of the Result
+ */
+export class Op<Ctx extends OpContext, Args extends unknown[], S, E> {
+  constructor(
+    /** Op name for metrics, telemetry, and debugging */
+    readonly metadata: OpMetadata,
+    /** Op owns buffer creation - class has static schema + stats shared by all instances */
+    readonly SpanBufferClass: SpanBufferConstructor,
+    /** The user function to execute - called by span_op after context creation (can be sync or async) */
+    readonly fn: (ctx: SpanContext<Ctx>, ...args: Args) => Result<S, E> | Promise<Result<S, E>>,
+    /** Only set for prefixed ops - wraps child buffers during registration */
+    readonly remappedViewClass?: RemappedViewConstructor,
+    /**
+     * WHY: Carries the OpContextBinding from the factory that created this Op.
+     * Enables downstream consumers (defineAgentOps, OpRegistry) to extract the
+     * LMAO schema for context merging and conflict detection.
+     */
+    readonly _opContextBinding?: OpContextBinding,
+  ) {}
+}