@smoothbricks/lmao 0.1.3 → 0.2.0

package/src/lib/defineOpContext.ts

@@ -250,9 +250,15 @@ function buildOpContextFactory<
   };
 }
 
+//#region smoo/lmao!n/opcontext-definition
 /**
  * Define an Op context factory
  *
+ * 01j "Module Definition", renamed: this is the shipped entry point (defineOpContext,
+ * not defineModule().ctx().make()). Returns { defineOp, defineOps }; user context is the
+ * `ctx` config field (runtime defaults, reserved-key-guarded — see the nested
+ * n/schema-env-config region), deps carry their own prefix, and per-Op attribution is OpMetadata.
+ *
  * 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.
  *
@@ -334,7 +340,14 @@ export function defineOpContext<
   Deps extends DepsConfig = Record<string, never>,
   UserCtx extends Record<string, unknown> = Record<string, never>,
 >(config: OpContextConfig<T, FF, Deps, UserCtx>) {
-  // Runtime validation: check for reserved property names in user context
+  //#region smoo/lmao!n/schema-env-config
+  // Runtime validation: check for reserved property names in user context.
+  // The `ctx` config object is the env/deployment-config surface from
+  // 01a "Environment Variable Configuration" — a plain user object (env, services,
+  // requestId, ...) spread into SpanContext, guarded only against reserved/internal keys.
+  //#region smoo/lmao!n/schema-env-config.reserved
+  // 01l "Reserved Names": ctx keys cannot collide with built-in SpanContext members
+  // (buffer/tag/log/scope/setScope/ok/err/span/ff/deps) or start with `_` (internal).
   if (config.ctx) {
     const userKeys = Object.keys(config.ctx);
     for (const key of userKeys) {
@@ -350,6 +363,8 @@ export function defineOpContext<
       }
     }
   }
+  //#endregion smoo/lmao!n/schema-env-config.reserved
+  //#endregion smoo/lmao!n/schema-env-config
 
   // Compute effective schema by combining app schema with dep contributions.
   // This merges app fields + all dep contributed fields (after prefix/mapping).
@@ -387,6 +402,7 @@ export function defineOpContext<
 
   return buildOpContextFactory(effectiveFields, config.flags, config.deps, config.ctx);
 }
+//#endregion smoo/lmao!n/opcontext-definition
 
 // Re-export everything from opContext for convenience
 export * from './opContext/index.js';

package/src/lib/errors/Blocked.ts

@@ -53,6 +53,7 @@
 
 import type { TaggedError } from '../result.js';
 
+//#region smoo/lmao!n/op-context-tagged-errors.blocked
 /**
  * Reason why an Op is blocked.
  */
@@ -163,3 +164,4 @@ export class Blocked extends Error implements TaggedError<'Blocked'> {
     };
   }
 }
+//#endregion smoo/lmao!n/op-context-tagged-errors.blocked

package/src/lib/errors/Transient.ts

@@ -1,3 +1,4 @@
+//#region smoo/lmao!n/op-retry.transient
 /**
  * TransientError - typed transient error codes with embedded retry policy.
  *
@@ -166,3 +167,4 @@ function isRetryPolicyLike(value: unknown): value is Partial<RetryPolicy> {
 
 // Re-export policy helpers for convenience
 export { exponentialBackoff, fixedDelay, linearBackoff, mergePolicy, type RetryPolicy } from './retry-policy.js';
+//#endregion smoo/lmao!n/op-retry.transient

package/src/lib/errors/retry-policy.ts

@@ -1,3 +1,4 @@
+//#region smoo/lmao!n/op-retry.policy
 /**
  * RetryPolicy - configures retry behavior for transient failures.
  *
@@ -85,3 +86,4 @@ export function mergePolicy(base: RetryPolicy, override?: Partial<RetryPolicy>):
   if (!override) return base;
   return { ...base, ...override };
 }
+//#endregion smoo/lmao!n/op-retry.policy

package/src/lib/flushScheduler.ts

@@ -120,6 +120,7 @@ export interface FlushSchedulerConfig {
  * Background flush scheduler
  * Manages automatic flushing of span buffers to Arrow tables
  */
+//#region smoo/lmao!n/buffer-tuning-flush
 export class FlushScheduler {
   private config: Required<FlushSchedulerConfig>;
   private handler: FlushHandler;
@@ -464,6 +465,7 @@ export class FlushScheduler {
     this.lastActivityTime = Date.now();
   }
 }
+//#endregion smoo/lmao!n/buffer-tuning-flush
 
 /**
  * Global flush scheduler instance (optional)

package/src/lib/library.ts

@@ -71,10 +71,16 @@ function isRemappedSpanLoggerClass<T extends LogSchema>(value: unknown): value i
   );
 }
 
+//#region smoo/lmao!n/codegen-prefixed-remap
 /**
  * Prefix a tag attribute schema
  * Renames all fields with a prefix to avoid conflicts
  *
+ * 01j "Library Compilation (Prefixed)": a library defines clean field names
+ * (status, method); the consumer applies a prefix (http) at wire time. This block
+ * generates the prefixed schema, the clean->prefixed mapping, and the RemappedSpanLogger /
+ * RemappedBufferView classes whose clean methods write to prefixed columns.
+ *
  * Example:
  * - Input: { status: S.number(), method: S.enum(['GET', 'POST']) }
  * - Prefix: 'http'
@@ -680,3 +686,4 @@ export function createRemappedSpanLoggerClass<T extends LogSchema>(
 
   return GeneratedClass;
 }
+//#endregion smoo/lmao!n/codegen-prefixed-remap

package/src/lib/op.ts

@@ -31,6 +31,11 @@ import type { SpanBufferConstructor } from './spanBuffer.js';
  * Includes pre-encoded UTF-8 entries for Arrow dictionary building -
  * encode once at Op definition time, reuse for every span conversion.
  */
+//#region smoo/lmao!n/opcontext-hierarchy
+// 01j "ModuleContext", renamed: per-Op source-attribution metadata
+// (package_name/package_file/git_sha) + pre-encoded UTF-8 entries for Arrow
+// dictionary building. One per defineOp; SpanBuffer/SpanContext are the other
+// two levels of the 01j Context Hierarchy.
 export interface OpMetadata {
   /** Op name for metrics tracking (distinct from span names which are provided at call sites) */
   readonly name: string;
@@ -50,11 +55,13 @@ export interface OpMetadata {
   /** Pre-encoded git_sha for Arrow dictionary building */
   readonly git_sha_entry: PreEncodedEntry;
 }
+//#endregion smoo/lmao!n/opcontext-hierarchy
 
 // =============================================================================
 // Op Class
 // =============================================================================
 
+//#region smoo/lmao!n/op-class
 /**
  * Op - Traced operation (Phase 2 architecture)
  *
@@ -101,3 +108,4 @@ export class Op<Ctx extends OpContext, Args extends unknown[], S, E> {
     readonly _opContextBinding?: OpContextBinding,
   ) {}
 }
+//#endregion smoo/lmao!n/op-class

package/src/lib/opContext/createOpGroup.ts

@@ -34,6 +34,11 @@ import type {
 import { validateOpName } from './opGroupTypes.js';
 import type { OpContext } from './types.js';
 
+//#region smoo/lmao!n/column-mapping-api
+// 01l "Dependencies with Column Mapping" + 01e "Column Mapping API": .prefix(name) and
+// .mapColumns({ col: 'new' | 'shared' | null }) are realized here. Each call clones the
+// OpGroup's ops with a fresh RemappedBufferView (cold-path codegen via library.ts), so the
+// hot path still writes the clean unprefixed columns; the view remaps clean->target for Arrow.
 // =============================================================================
 // INTERNAL HELPERS
 // =============================================================================
@@ -454,3 +459,4 @@ export function createOpGroup<Ctx extends OpContext, Ops extends OpGroupOps<Ctx>
   assertGroupCarriesOps<Ctx, Ops>(group, ops);
   return group;
 }
+//#endregion smoo/lmao!n/column-mapping-api

package/src/lib/opContext/defineOp.ts

@@ -14,6 +14,11 @@ import type { OpGroup, OpGroupOps } from './opGroupTypes.js';
 import type { Op, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
 import type { OpContext } from './types.js';
 
+//#region smoo/lmao!n/metadata-injection
+// 01l "Metadata Injection (Transformer)": package_name/package_file/git_sha/line are the
+// per-Op OpMetadata the transformer injects at the defineOpContext call site. createOpMetadata
+// pre-encodes the dictionary entries (interned UTF-8); DEFAULT_METADATA is the un-injected
+// placeholder; extractMetadataFromStack is the no-transformer dev fallback (parses the stack).
 // =============================================================================
 // METADATA HELPERS
 // =============================================================================
@@ -130,6 +135,7 @@ export function extractMetadataFromStack(skipFrames = 2): OpMetadata {
 
   return createOpMetadata('unknown', packageName, filePath, 'runtime', lineNumber);
 }
+//#endregion smoo/lmao!n/metadata-injection
 
 // =============================================================================
 // FACTORY CONFIG

package/src/lib/result.ts

@@ -104,6 +104,7 @@ function createCodeErrorValue<Code extends string, Fields extends object>(
 // OK CLASS
 // =============================================================================
 
+//#region smoo/lmao!n/lmao-entry-fluentok
 /**
  * Success result with fluent tag application.
  *
@@ -240,11 +241,13 @@ export class Ok<V, T extends LogSchema = LogSchema> {
     return { ok: true, value: this.value };
   }
 }
+//#endregion smoo/lmao!n/lmao-entry-fluentok
 
 // =============================================================================
 // ERR CLASS
 // =============================================================================
 
+//#region smoo/lmao!n/lmao-entry-fluenterr
 /**
  * Error result with fluent tag application.
  *
@@ -410,6 +413,7 @@ export class Err<E, T extends LogSchema = LogSchema> {
     return { ok: false, error: this.error };
   }
 }
+//#endregion smoo/lmao!n/lmao-entry-fluenterr
 
 // =============================================================================
 // RESULT TYPE

package/src/lib/schema/builder.ts

@@ -66,6 +66,7 @@ function createSchemaWithFlagBuilder<Value, TSchema extends Schema<Value>>(
   return schemaWithBuilder;
 }
 
+//#region smoo/lmao!n/schema-string-types
 /**
  * Schema builder that wraps arrow-builder's S with feature flag support
  *
@@ -199,3 +200,4 @@ const schemaBuilderImpl: SchemaBuilder = {
 // Export as S for convenience
 // Note: The SchemaBuilder type is exported from types.ts
 export const S = schemaBuilderImpl;
+//#endregion smoo/lmao!n/schema-string-types

package/src/lib/schema/defineFeatureFlags.ts

@@ -1,3 +1,4 @@
+//#region smoo/lmao!n/flag-flag-schema
 import type { Output } from '@smoothbricks/arrow-builder';
 import type { FeatureFlagDefinition } from './types.js';
 
@@ -89,3 +90,4 @@ export interface UsageContext {
   value?: number;
   metadata?: Record<string, string | number | boolean>;
 }
+//#endregion smoo/lmao!n/flag-flag-schema

package/src/lib/schema/defineLogSchema.ts

@@ -229,6 +229,7 @@ function assertValidatedObject<T extends SchemaFields>(
   }
 }
 
+//#region smoo/lmao!n/schema-log-schema
 export function defineLogSchema<T extends SchemaFields>(
   schema: T,
   options?: DefineLogSchemaOptions,
@@ -289,3 +290,4 @@ export function defineLogSchema<T extends SchemaFields>(
   // Return logSchema (still a LogSchema instance with added methods)
   return result;
 }
+//#endregion smoo/lmao!n/schema-log-schema

package/src/lib/schema/evaluator.ts

@@ -1,3 +1,4 @@
+//#region smoo/lmao!n/flag-evaluator
 import type { Schema, SchemaWithMetadata } from '@smoothbricks/arrow-builder';
 import { createEvaluatorClass, type GeneratedEvaluatorInstance } from '../codegen/evaluatorGenerator.js';
 import type { FluentLogEntry } from '../codegen/spanLoggerGenerator.js';
@@ -402,3 +403,4 @@ export class InMemoryFlagEvaluator<Ctx extends OpContext = OpContext> implements
     return createFeatureFlagEvaluator(this.ffSchema, ctx, this);
   }
 }
+//#endregion smoo/lmao!n/flag-evaluator

package/src/lib/schema/systemSchema.ts

@@ -203,6 +203,7 @@ export function mergeWithSystemSchema<T extends Record<string, unknown>>(userSch
   return merged;
 }
 
+//#region smoo/lmao!n/lmao-entry-entry-type-definitions
 // =============================================================================
 // Entry Type Constants
 // =============================================================================
@@ -337,3 +338,4 @@ export const ENTRY_TYPE_NAMES = [
   'buffer-spans', // 23
   'buffer-capacity', // 24
 ] as const;
+//#endregion smoo/lmao!n/lmao-entry-entry-type-definitions

package/src/lib/spanBuffer.ts

@@ -122,6 +122,7 @@ export const SpanBufferTestUtils = {
  *
  * traceRoot is ALWAYS provided - factories extract it from parent when needed.
  */
+//#region smoo/lmao!n/spanbuffer-layout.class-signature
 export interface SpanBufferConstructor<T extends LogSchema = LogSchema> {
   new (
     capacity: number,
@@ -137,6 +138,7 @@ export interface SpanBufferConstructor<T extends LogSchema = LogSchema> {
   readonly schema: T;
   readonly stats: SpanBufferStats;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.class-signature
 
 type GeneratedSpanBufferClass<T extends LogSchema> = new (
   capacity: number,
@@ -214,6 +216,7 @@ const spanBufferClassCache = new WeakMap<LogSchema, SpanBufferConstructor>();
  * @param schema - LogSchema defining the buffer structure
  * @returns SpanBufferConstructor with static schema and stats properties
  */
+//#region smoo/lmao!n/spanbuffer-layout.constructor
 export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferConstructor<T> {
   const cached = spanBufferClassCache.get(schema);
   if (isSpanBufferConstructorForSchema(cached, schema)) {
@@ -439,6 +442,7 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
 
   return SpanBufferClass;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.constructor
 
 // ============================================================================
 // SpanBuffer factory functions
@@ -458,6 +462,7 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
  */
 const MIN_CAPACITY = 8;
 
+//#region smoo/lmao!n/spanbuffer-layout.create-root
 export function createSpanBuffer<T extends LogSchema>(
   schema: T,
   traceRoot: ITraceRoot,
@@ -485,6 +490,7 @@ export function createSpanBuffer<T extends LogSchema>(
     traceRoot, // pre-built TraceRoot with trace_id, anchors, tracer
   );
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.create-root
 
 /**
  * Creates a continuation buffer when the current buffer overflows.
@@ -496,6 +502,7 @@ export function createSpanBuffer<T extends LogSchema>(
  *
  * @returns New SpanBuffer linked via `buffer._overflow`, with same schema type
  */
+//#region smoo/lmao!n/spanbuffer-layout.create-overflow
 export function createOverflowBuffer<T extends LogSchema>(buffer: SpanBuffer<T>): SpanBuffer<T> {
   const SpanBufferClass = getSpanBufferConstructorForBuffer(buffer);
   const stats = SpanBufferClass.stats;
@@ -520,6 +527,7 @@ export function createOverflowBuffer<T extends LogSchema>(buffer: SpanBuffer<T>)
 
   return nextBuffer;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.create-overflow
 
 /**
  * Creates a child span buffer with parent linkage.
@@ -537,6 +545,7 @@ export function createOverflowBuffer<T extends LogSchema>(buffer: SpanBuffer<T>)
  *
  * @returns New SpanBuffer linked to parent
  */
+//#region smoo/lmao!n/spanbuffer-layout.create-child
 export function createChildSpanBuffer<T extends LogSchema>(
   parentBuffer: AnySpanBuffer,
   SpanBufferClass: SpanBufferConstructor<T>,
@@ -563,6 +572,7 @@ export function createChildSpanBuffer<T extends LogSchema>(
 
   return childBuffer;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.create-child
 
 // ============================================================================
 // Constants for Arrow conversion

package/src/lib/spanBufferHelpers.ts

@@ -10,6 +10,7 @@
 
 import { copyThreadIdTo } from './threadId.js';
 
+//#region smoo/lmao!n/spanbuffer-layout.helpers
 /**
  * Shared TextEncoder instance for traceId encoding.
  * TextEncoder is stateless and thread-safe, so one instance suffices.
@@ -71,3 +72,4 @@ export const spanBufferHelpers = {
 } as const;
 
 export type SpanBufferHelpers = typeof spanBufferHelpers;
+//#endregion smoo/lmao!n/spanbuffer-layout.helpers

package/src/lib/spanBufferStats.ts

@@ -28,6 +28,7 @@
  * Created once per `defineOpContext`, stored as static property on generated
  * SpanBuffer class. All buffers from same context share these stats.
  */
+//#region smoo/lmao!n/spanbuffer-layout.stats
 export interface SpanBufferStats {
   /** Current buffer capacity for new buffers (grows/shrinks based on utilization) */
   capacity: number;
@@ -38,3 +39,4 @@ export interface SpanBufferStats {
   /** Number of non-chained spans created (root + child spans, NOT overflow buffers) */
   spansCreated: number;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.stats

package/src/lib/spanContext.ts

@@ -69,9 +69,14 @@ export const SPAN_CONTEXT_MARKER = Symbol.for('lmao.SpanContext');
 // Type Exports
 // =============================================================================
 
+//#region smoo/lmao!n/codegen-spanlogger.ff
 /**
  * Internal SpanLogger type with FF methods and internal methods exposed.
  * Used by FeatureFlagEvaluator and internal span management code.
+ *
+ * The 01g "SpanLoggerInternal Type Pattern": the public SpanLogger<T> hides
+ * ffAccess/ffUsage; the evaluator casts to this internal type to reach them.
+ * The methods themselves are generated in codegen/spanLoggerGenerator.ts.
  */
 export type SpanLoggerInternal<T extends LogSchema> = SpanLoggerImpl<T> & {
   /**
@@ -85,6 +90,7 @@ export type SpanLoggerInternal<T extends LogSchema> = SpanLoggerImpl<T> & {
    */
   ffUsage(flagName: string, context?: Record<string, unknown>): FluentLogEntry<T>;
 };
+//#endregion smoo/lmao!n/codegen-spanlogger.ff
 
 type SpanDispatchFn<Ctx extends OpContext, Args extends unknown[] = unknown[], S = unknown, E = unknown> = (
   ctx: SpanContext<Ctx>,
@@ -202,6 +208,7 @@ function resolveSpanTarget<Ctx extends OpContext>(
 // Helper Functions
 // =============================================================================
 
+//#region smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.start
 /**
  * Write span-start entry to buffer at row 0 (fixed layout)
  * Pre-initialize row 1 as span-exception (will be overwritten by ok/err)
@@ -219,6 +226,7 @@ export function writeSpanStart<T extends LogSchema>(buffer: SpanBuffer<T>, spanN
   // Delegate to TraceRoot - platform-specific implementation handles timestamps
   buffer._traceRoot.writeSpanStart(buffer, spanName);
 }
+//#endregion smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.start
 
 /**
  * Create a SpanLogger for the given buffer.
@@ -234,6 +242,7 @@ export function createSpanLogger<T extends LogSchema>(schema: T, buffer: SpanBuf
   return createSpanLoggerFromGenerator(schema, buffer);
 }
 
+//#region smoo/lmao!n/op-retry.delay
 /**
  * Calculate delay for retry based on policy and attempt number.
  *
@@ -268,7 +277,9 @@ function calculateDelay(policy: RetryPolicy, attempt: number): number {
 
   return delay;
 }
+//#endregion smoo/lmao!n/op-retry.delay
 
+//#region smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.retry
 /**
  * Write span-retry entry to buffer.
  *
@@ -308,7 +319,9 @@ function writeRetryEntry<T extends LogSchema>(
   buffer.retry_attempt(index, attempt);
   buffer.retry_delay_ms(index, delayMs);
 }
+//#endregion smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.retry
 
+//#region smoo/lmao!n/op-retry.loop
 /**
  * Sleep for the specified duration.
  *
@@ -383,7 +396,9 @@ async function executeWithRetry<T extends LogSchema, S, E>(
     return result;
   }
 }
+//#endregion smoo/lmao!n/op-retry.loop
 
+//#region smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.end
 /**
  * Write span-end entry to buffer at row 1.
  *
@@ -408,14 +423,20 @@ export function writeSpanEnd<T extends LogSchema, S, E>(buffer: SpanBuffer<T>, r
     }
   }
 }
+//#endregion smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.end
 
 // =============================================================================
 // SpanContext Class Types
 // =============================================================================
 
+//#region smoo/lmao!n/spancontext-type
 /**
  * Constructor type for SpanContext classes created by createSpanContextClass.
  * Takes buffer, schema, spanLogger, tag directly (no temp object allocation).
+ *
+ * 01j "SpanContext Type Definition": the runtime SpanContext shape, parameterised by a single
+ * bundled OpContext (logSchema/flags/deps/...) rather than separate Schema/Deps/FF/Extra params,
+ * and SpanFn realized as the monomorphic span0-span8 overloads + variadic span() dispatcher.
  */
 export type SpanContextClass<Ctx extends OpContext> = new (
   buffer: SpanBuffer<Ctx['logSchema']>,
@@ -596,6 +617,7 @@ export type SpanContextInstance<Ctx extends OpContext> = SpanContext<Ctx> & {
     a8: A8,
   ): Promise<Result<S, E, Ctx['logSchema']>>;
 };
+//#endregion smoo/lmao!n/spancontext-type
 
 // =============================================================================
 // SpanContext Class Factory
@@ -654,6 +676,10 @@ export function createSpanContextClass<Ctx extends OpContext>(
       spanLogger: SpanLoggerImpl<Ctx['logSchema']>,
       tag: TagWriter<Ctx['logSchema']>,
     ) {
+      //#region smoo/lmao!n/codegen-destructured-context
+      // Destructured-context assembly (01g): every property an op destructures —
+      // tag, log, scope (setScope), ok, err, span — is wired here as a closed-over
+      // field/closure so `op(({ tag, log, span, ok, err }) => ...)` needs no ctx drilling.
       this._buffer = buffer;
       this._schema = schema;
       this._spanLogger = spanLogger;
@@ -669,7 +695,14 @@ export function createSpanContextClass<Ctx extends OpContext>(
       this.ok = <V>(value: V): Ok<V, Ctx['logSchema']> => new Ok<V, Ctx['logSchema']>(value, schema, buffer);
 
       this.err = <E>(error: E): Err<E, Ctx['logSchema']> => new Err<E, Ctx['logSchema']>(error, schema, buffer);
-
+      //#endregion smoo/lmao!n/codegen-destructured-context
+
+      //#region smoo/lmao!n/context-flow-span-promise
+      // 01c "Why span() Is Promise-Based" + "Child Span Creation via span()" + "spanSync()".
+      // span() is the variadic, line-number-aware Promise-based dispatcher: it detects the
+      // (line?, name, overrides?, op|fn, ...args) pattern via arguments.length (no rest-spread
+      // allocation) and routes to the monomorphic span0-span8. spanSync() is the sync-only
+      // sibling (returns Result, no Promise, no async retry loop) for guaranteed-sync callbacks.
       // span uses regular function to access `arguments` (no ...rest spread allocation)
       // Closes over `self` for calling prototype methods
       // Named function for better stack traces
@@ -866,6 +899,7 @@ export function createSpanContextClass<Ctx extends OpContext>(
           fn,
         );
       };
+      //#endregion smoo/lmao!n/context-flow-span-promise
     }
 
     // =========================================================================
@@ -902,9 +936,13 @@ export function createSpanContextClass<Ctx extends OpContext>(
       return this._buffer;
     }
 
+    //#region smoo/lmao!n/scope-attributes.read
+    // 01i read-only scope view: the immutable _scopeValues snapshot (setScope is wired in the
+    // destructured-context region; the immutable merge is _setScope in spanLoggerGenerator).
     get scope(): Readonly<Partial<InferSchema<Ctx['logSchema']>>> {
       return this._buffer._scopeValues;
     }
+    //#endregion smoo/lmao!n/scope-attributes.read
 
     // =========================================================================
     // Internal methods (on prototype)
@@ -944,6 +982,12 @@ export function createSpanContextClass<Ctx extends OpContext>(
      * @param remappedViewClass - Optional view class for prefixed ops (wraps buffer for Arrow conversion)
      * @param opMetadata - Metadata for the executing op (Op's metadata or parent's for plain functions)
      */
+    //#region smoo/lmao!n/context-flow-child-span
+    // 01c "Child Span Creation via span()" / "How span() Works" and 01e "Op's Responsibility:
+    // Buffer Creation and Registration": _spanPre is where the child SpanBuffer is created
+    // (via the buffer strategy, using the Op's SpanBufferClass for cross-library schema),
+    // wrapped in a RemappedBufferView when the dep is prefixed/mapped, registered in the
+    // parent's _children, and span-start (row 0) is written with the caller's line number.
     _spanPre(
       childCtx: SpanContextInstance<Ctx>,
       line: number,
@@ -1203,7 +1247,9 @@ export function createSpanContextClass<Ctx extends OpContext>(
 
       return ctx;
     }
+    //#endregion smoo/lmao!n/context-flow-child-span
 
+    //#region smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.exception
     /**
      * Handle span exception - writes exception details to row 1.
      * Called in catch blocks of span methods.
@@ -1218,6 +1264,7 @@ export function createSpanContextClass<Ctx extends OpContext>(
         childBuffer.exception_stack(1, errorStack);
       }
     }
+    //#endregion smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.exception
 
     // =========================================================================
     // Monomorphic span methods (for transformer output)

package/src/lib/sqlite/__tests__/sqlite-common.test.ts

@@ -1,3 +1,4 @@
+import { Database } from 'bun:sqlite';
 import { describe, expect, it } from 'bun:test';
 import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
 import { defineOpContext } from '../../defineOpContext.js';
@@ -5,7 +6,13 @@ import { S } from '../../schema/builder.js';
 import { defineLogSchema } from '../../schema/defineLogSchema.js';
 import { TestTracer } from '../../tracers/TestTracer.js';
 import type { AnySpanBuffer } from '../../types.js';
-import { buildInsertParams, parseSqliteTableInfoRows, type SpanSegment } from '../sqlite-common.js';
+import {
+  buildInsertParams,
+  buildInsertSql,
+  parseSqliteTableInfoRows,
+  SPANS_TABLE_INIT_SQL,
+  type SpanSegment,
+} from '../sqlite-common.js';
 
 const opContext = defineOpContext({
   logSchema: defineLogSchema({
@@ -87,3 +94,35 @@ describe('parseSqliteTableInfoRows', () => {
     ).toThrow('PRAGMA table_info(spans) returned an invalid SQLite row 0: type expected string, got number');
   });
 });
+
+describe('buildInsertSql', () => {
+  it('quotes user column identifiers so reserved words do not break the INSERT', () => {
+    // `check` and `order` are SQLite reserved words; a LogSchema field may use
+    // either (e.g. a `check` column). Unquoted, these produce
+    // `near "check": syntax error` at flush time.
+    const sql = buildInsertSql(['check', 'order', 'node']);
+    expect(sql).toContain('"check"');
+    expect(sql).toContain('"order"');
+    expect(sql).toContain('"node"');
+  });
+
+  it('omits the user-column clause entirely when there are no active fields', () => {
+    const sql = buildInsertSql([]);
+    expect(sql).toContain(
+      'INSERT INTO spans (trace_id, span_id, parent_span_id, row_index, entry_type, timestamp_ns, message)',
+    );
+  });
+
+  it('prepares against a real SQLite spans table with a reserved-word column', () => {
+    const db = new Database(':memory:');
+    db.exec(SPANS_TABLE_INIT_SQL);
+    db.exec('ALTER TABLE spans ADD COLUMN "check" TEXT');
+    // The bug: db.prepare(buildInsertSql(['check'])) threw `near "check": syntax error`.
+    const stmt = db.prepare(buildInsertSql(['check']));
+    stmt.run('trace-1', 1, 0, 0, 0, 0, 'msg', 'pass');
+    // .values() yields raw cell arrays (no object shape to assert / no cast).
+    const rows = db.query('SELECT "check" FROM spans').values();
+    expect(rows).toEqual([['pass']]);
+    db.close();
+  });
+});

package/src/lib/sqlite/index.ts

@@ -8,6 +8,7 @@
  */
 
 export { SQLiteAsyncTraceWriter } from './sqlite-async-writer.js';
+export type { SQLiteTableInfoRow } from './sqlite-common.js';
 export {
   buildAddColumnSql,
   extractSqliteColumnsFromTableInfo,

package/src/lib/sqlite/sqlite-common.ts

@@ -284,12 +284,21 @@ export function getInsertStatementCacheKey(activeUserFields: readonly string[]):
 }
 
 export function buildInsertSql(activeUserFields: readonly string[]): string {
-  const userColsSql = activeUserFields.length > 0 ? `, ${activeUserFields.join(', ')}` : '';
+  // WHY quote: user column names come from arbitrary LogSchema fields and may
+  // collide with SQLite reserved words (e.g. a `check` or `order` trace column).
+  // buildAddColumnSql already quotes via quoteSqlIdentifier; the INSERT column
+  // list must too, or `near "check": syntax error` at flush time.
+  const userColsSql = activeUserFields.length > 0 ? `, ${activeUserFields.map(quoteSqlIdentifier).join(', ')}` : '';
   const userPlaceholders = activeUserFields.length > 0 ? `, ${activeUserFields.map(() => '?').join(', ')}` : '';
   return `INSERT INTO spans (trace_id, span_id, parent_span_id, row_index, entry_type, timestamp_ns, message${userColsSql})
    VALUES (?, ?, ?, ?, ?, ?, ?${userPlaceholders})`;
 }
 
+/** Read a user schema field for one buffer row, falling back to the buffer's scope values. */
+export function readSpanFieldValue(buffer: AnySpanBuffer, fieldName: string, row: number): unknown {
+  return readUserValue(buffer, fieldName, row) ?? readScopeValue(buffer, fieldName);
+}
+
 export function buildInsertParams(segment: SpanSegment, row: number, activeUserFields: readonly string[]): unknown[] {
   const { buffer, traceId, spanId, parentSpanId, rowOffset } = segment;
   const entryType = buffer.entry_type[row];