@smoothbricks/lmao 0.1.0

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

@@ -0,0 +1,83 @@
+/// <reference types="node" />
+
+import { DatabaseSync } from 'node:sqlite';
+import type {
+  AsyncSQLiteDatabase,
+  AsyncSQLiteStatement,
+  SyncSQLiteDatabase,
+  SyncSQLiteStatement,
+} from './sqlite-db.js';
+
+function toSyncStatement(statement: {
+  run(...params: unknown[]): unknown;
+  all(...params: unknown[]): unknown[];
+  get(...params: unknown[]): unknown;
+}): SyncSQLiteStatement {
+  return {
+    run(...params: unknown[]): void {
+      statement.run(...params);
+    },
+    all(...params: unknown[]): unknown[] {
+      return statement.all(...params);
+    },
+    get(...params: unknown[]): unknown {
+      return statement.get(...params);
+    },
+  };
+}
+
+/**
+ * Create a Node built-in sqlite database adapter.
+ *
+ * Use this in Node Vitest setup when you want trace output persisted
+ * to a deterministic file path.
+ */
+export function createNodeSQLiteDatabase(dbPath: string): SyncSQLiteDatabase {
+  const db = new DatabaseSync(dbPath);
+  return {
+    exec(sql: string): void {
+      db.exec(sql);
+    },
+    prepare(sql: string): SyncSQLiteStatement {
+      return toSyncStatement(db.prepare(sql));
+    },
+    close(): void {
+      db.close();
+    },
+  };
+}
+
+function toAsyncStatement(statement: SyncSQLiteStatement): AsyncSQLiteStatement {
+  return {
+    async run(...params: unknown[]): Promise<void> {
+      statement.run(...params);
+    },
+    async all(...params: unknown[]): Promise<unknown[]> {
+      return statement.all(...params);
+    },
+    async get(...params: unknown[]): Promise<unknown> {
+      return statement.get(...params);
+    },
+  };
+}
+
+/**
+ * Create an async adapter around Node built-in sqlite.
+ *
+ * Useful when wiring into `createAsyncDatabase` callbacks while still
+ * writing to a deterministic file path on Node.
+ */
+export function createNodeSQLiteAsyncDatabase(dbPath: string): AsyncSQLiteDatabase {
+  const syncDb = createNodeSQLiteDatabase(dbPath);
+  return {
+    async exec(sql: string): Promise<void> {
+      syncDb.exec(sql);
+    },
+    prepare(sql: string): AsyncSQLiteStatement {
+      return toAsyncStatement(syncDb.prepare(sql));
+    },
+    async close(): Promise<void> {
+      syncDb.close();
+    },
+  };
+}

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

@@ -0,0 +1,128 @@
+/**
+ * SQLiteTraceWriter - General-purpose writer that persists span buffer trees to SQLite.
+ *
+ * Accepts a SyncSQLiteDatabase instance (from bun:sqlite or better-sqlite3)
+ * and persists the full span tree as a flat `spans` table with dynamic column
+ * evolution based on the LogSchema fields found at flush time.
+ *
+ * Architecture:
+ * - Single `spans` table — no runs/log_entries decomposition
+ * - trace_id IS the run identifier (one root span per trace)
+ * - Tree structure via span_id / parent_span_id (no depth column)
+ * - User schema columns added dynamically via ALTER TABLE
+ * - Per-buffer ensureColumns for cross-library schema merging
+ *
+ * @module sqlite-writer
+ */
+
+import type { LogSchema } from '../schema/LogSchema.js';
+import type { AnySpanBuffer } from '../types.js';
+import {
+  buildAddColumnSql,
+  buildInsertParams,
+  buildInsertSql,
+  extractSqliteColumnsFromTableInfo,
+  getActiveUserFields,
+  getInsertStatementCacheKey,
+  getMissingSchemaColumns,
+  isSqliteDuplicateColumnError,
+  parseSqliteTableInfoRows,
+  SPANS_TABLE_INFO_SQL,
+  SPANS_TABLE_INIT_SQL,
+  type SpanSegment,
+  walkSpanSegments,
+} from './sqlite-common.js';
+import type { SyncSQLiteDatabase, SyncSQLiteStatement } from './sqlite-db.js';
+
+export interface SQLiteWriterConfig {
+  /** Path to SQLite file. Default: '.trace-results.db' */
+  dbPath?: string;
+}
+
+export class SQLiteTraceWriter {
+  private knownColumns = new Set<string>();
+  private insertStmtCache = new Map<string, SyncSQLiteStatement>();
+
+  constructor(private db: SyncSQLiteDatabase) {
+    this.init();
+  }
+
+  private init(): void {
+    // Parallel Bun test workers share one trace DB, so wait for short SQLite writer locks instead of failing setup.
+    this.db.exec('PRAGMA busy_timeout = 10000');
+    this.db.exec(SPANS_TABLE_INIT_SQL);
+
+    this.refreshKnownColumns();
+  }
+
+  private refreshKnownColumns(): void {
+    this.knownColumns.clear();
+    // WHY: PRAGMA row shape changes would make later ALTER/INSERT logic drift silently, so validate here before
+    // mutating the writer's cached schema view.
+    const rows = parseSqliteTableInfoRows(this.db.prepare(SPANS_TABLE_INFO_SQL).all());
+    for (const column of extractSqliteColumnsFromTableInfo(rows)) {
+      this.knownColumns.add(column.name);
+    }
+  }
+
+  /** Ensure user-defined schema columns exist in the spans table */
+  private ensureColumns(schema: LogSchema): void {
+    for (const column of getMissingSchemaColumns(schema, this.knownColumns)) {
+      try {
+        this.db.exec(buildAddColumnSql(column));
+      } catch (error) {
+        if (!isSqliteDuplicateColumnError(error, column.name)) {
+          throw error;
+        }
+      }
+
+      this.refreshKnownColumns();
+      this.knownColumns.add(column.name);
+    }
+  }
+
+  private writeSegmentRows(segment: SpanSegment): void {
+    this.ensureColumns(segment.buffer._logSchema);
+
+    const activeUserFields = getActiveUserFields(segment.buffer._logSchema, this.knownColumns);
+    const insertStmt = this.getInsertStatement(activeUserFields);
+
+    for (let row = 0; row < segment.buffer._writeIndex; row++) {
+      insertStmt.run(...buildInsertParams(segment, row, activeUserFields));
+    }
+  }
+
+  private flushAllSegments(rootBuffer: AnySpanBuffer): void {
+    for (const segment of walkSpanSegments(rootBuffer)) {
+      this.writeSegmentRows(segment);
+    }
+  }
+
+  private getInsertStatement(activeUserFields: readonly string[]): SyncSQLiteStatement {
+    const key = getInsertStatementCacheKey(activeUserFields);
+    const cached = this.insertStmtCache.get(key);
+    if (cached) {
+      return cached;
+    }
+
+    const stmt = this.db.prepare(buildInsertSql(activeUserFields));
+    this.insertStmtCache.set(key, stmt);
+    return stmt;
+  }
+
+  /** Write a root SpanBuffer tree to the database */
+  flush(rootBuffer: AnySpanBuffer): void {
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      this.flushAllSegments(rootBuffer);
+      this.db.exec('COMMIT');
+    } catch (error) {
+      this.db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/lib/testing/TRACE-TESTING.md

@@ -0,0 +1,100 @@
+# Trace-Testing with LMAO
+
+> Based on Akkartik's "tracing tests": https://akkartik.name/post/tracing-tests
+
+## Core Principle
+
+**Test WHAT happened (domain facts), not HOW (implementation details).**
+
+Traditional tests couple to internal structure:
+
+```typescript
+const result = await myOp(args);
+expect(result.status).toBe('success'); // Brittle - breaks on refactor
+```
+
+Trace-tests assert on facts emitted during execution:
+
+```typescript
+await trace('my-op', myOp);
+expect(facts.has(spanOk('my-op'))).toBe(true); // Robust - survives refactoring
+```
+
+## LMAO Fact Types
+
+Facts are strongly-typed template literals. Invalid facts = compile errors.
+
+| Type        | Format                   | Example                    |
+| ----------- | ------------------------ | -------------------------- |
+| `SpanFact`  | `span:${name}: ${state}` | `span:fetch-user: ok`      |
+| `LogFact`   | `log:${level}: ${msg}`   | `log:info: Processing`     |
+| `TagFact`   | `tag:${key}: ${value}`   | `tag:userId: 123`          |
+| `ScopeFact` | `scope:${key}: ${value}` | `scope:requestId: req-abc` |
+| `FFFact`    | `ff:${flag}: ${value}`   | `ff:darkMode: true`        |
+
+Span states: `started`, `ok`, `err(CODE)`, `exception(msg)`
+
+## Usage
+
+```typescript
+import { TestTracer, defineOpContext } from '@smoothbricks/lmao';
+import { extractFacts, spanStarted, spanOk, spanErr, tagFact, logInfo } from '@smoothbricks/lmao/testing';
+
+// 1. Run traced code
+const tracer = new TestTracer(opContext);
+await tracer.trace('process-order', async (ctx) => {
+  ctx.tag.orderId('ord-123');
+  await ctx.span('validate', async (c) => c.ok(null));
+  await ctx.span('charge', async (c) => c.ok(null));
+  return ctx.ok('done');
+});
+
+// 2. Extract facts from buffer tree
+const facts = extractFacts(tracer.rootBuffers[0]);
+
+// 3. Assert on WHAT happened
+expect(facts.has(spanOk('process-order'))).toBe(true);
+expect(facts.has(tagFact('orderId', 'ord-123'))).toBe(true);
+expect(facts.hasInOrder([spanStarted('validate'), spanOk('validate'), spanStarted('charge'), spanOk('charge')])).toBe(
+  true
+);
+expect(facts.hasMatch('span:*: err(*)')).toBe(false);
+```
+
+## FactArray API
+
+| Method                          | Purpose                                |
+| ------------------------------- | -------------------------------------- |
+| `has(fact)`                     | Exact match                            |
+| `hasMatch(pattern)`             | Glob match (`*` = any non-colon chars) |
+| `hasInOrder([...])`             | Facts appear in order (not adjacent)   |
+| `byNamespace('span')`           | Filter to namespace                    |
+| `spans()` / `logs()` / `tags()` | Typed filters                          |
+| `match(pattern)`                | Return matching facts                  |
+
+## Buffer Layout (Why This Works)
+
+Per `specs/lmao/01h_entry_types_and_logging_primitives.md`:
+
+- **Row 0**: `span-start` + tag writes (`ctx.tag.*` overwrites here)
+- **Row 1**: Completion (`span-ok`/`span-err`/`span-exception`)
+- **Row 2+**: Log entries (`ctx.log.*` appends here)
+
+`extractFacts()` walks the buffer tree depth-first, emitting facts in execution order.
+
+## When to Use Trace-Testing
+
+✅ **Use for**: Operation ordering, error handling, tag/scope propagation, multi-span workflows ❌ **Don't use for**:
+Return value validation, performance benchmarks, schema validation
+
+## Key Insight
+
+> "Tests no longer need call fine-grained helpers directly... The trace checks that the program correctly computed a
+> specific _fact_, while remaining oblivious about _how_ it was computed." — Akkartik
+
+This makes tests resilient to:
+
+- Function boundary changes
+- Sync → async refactoring
+- Internal restructuring
+- Adding/removing intermediate steps

package/src/lib/testing/__tests__/bun-harness.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'bun:test';
+import { defineOpContext } from '../../defineOpContext.js';
+import { S } from '../../schema/builder.js';
+import { defineLogSchema } from '../../schema/defineLogSchema.js';
+import { TestTracer } from '../../tracers/TestTracer.js';
+import { type BunTestModuleShape, makeBunTestSuiteTracer, makeTestTracer } from '../bun-harness.js';
+
+type BunTestModuleLike = BunTestModuleShape;
+
+function createImmediateTestFn(): BunTestModuleLike['it'] {
+  const runBase = (_name: string, fn: () => unknown | Promise<unknown>) => fn();
+  return Object.assign(runBase, it, {
+    only: runBase,
+    skipIf: (condition: boolean) => (condition ? it.skip : runBase),
+    if: (condition: boolean) => (condition ? runBase : it.skip),
+  });
+}
+
+function createImmediateDescribeFn(): BunTestModuleLike['describe'] {
+  const runBase = (_name: string, fn: () => void) => fn();
+  return Object.assign(runBase, describe, {
+    only: runBase,
+    skipIf: (condition: boolean) => (condition ? describe.skip : runBase),
+    if: (condition: boolean) => (condition ? runBase : describe.skip),
+  });
+}
+
+function createImmediateIt() {
+  return createImmediateTestFn();
+}
+
+function createImmediateDescribe() {
+  return createImmediateDescribeFn();
+}
+
+function createImmediateBunTestModule(): BunTestModuleLike {
+  const itFn = createImmediateIt();
+  return {
+    it: itFn,
+    describe: createImmediateDescribe(),
+    test: itFn,
+  };
+}
+
+const baseBinding = defineOpContext({
+  logSchema: defineLogSchema({ base_field: S.category() }),
+});
+
+const suiteWithExtension = makeBunTestSuiteTracer(baseBinding, {
+  extraTestColumns: {
+    test_metric: S.number(),
+  },
+});
+
+type ExtendedSpan = ReturnType<typeof suiteWithExtension.useTestSpan>;
+type HasExtendedTag = ExtendedSpan['tag'] extends { test_metric: (value: number) => unknown } ? true : false;
+type HasExtendedLog =
+  ReturnType<ExtendedSpan['log']['info']> extends { test_metric: (value: number) => unknown } ? true : false;
+const hasExtendedTag: HasExtendedTag = true;
+const hasExtendedLog: HasExtendedLog = true;
+
+describe('bun harness test log schema extension', () => {
+  it('includes extension fields in suite span typing', () => {
+    expect(hasExtendedTag).toBe(true);
+    expect(hasExtendedLog).toBe(true);
+  });
+
+  it('writes extension fields through tag and log APIs', async () => {
+    const tracer = makeTestTracer(baseBinding, {
+      extraTestColumns: {
+        test_metric: S.number(),
+        test_note: S.text(),
+      },
+    });
+    tracer.setup();
+
+    const wrappedModule = tracer.createBunTestMock(createImmediateBunTestModule());
+    await wrappedModule.it('writes test-only fields', async () => {
+      const span = tracer.useTestSpan();
+      span.tag.test_metric(123);
+      span.log.info('row-1').test_metric(456).test_note('hello');
+
+      const buffer = span.buffer;
+      expect(buffer.test_metric_values[0]).toBe(123);
+      expect(buffer.test_metric_values[2]).toBe(456);
+      expect(buffer.test_note_values[2]).toBe('hello');
+    });
+  });
+
+  it('defaults to an in-memory TestTracer when sqlite and verbose are off', () => {
+    const tracer = makeTestTracer(baseBinding);
+    tracer.setup();
+
+    expect(tracer.getTracer()).toBeInstanceOf(TestTracer);
+  });
+
+  it('rejects duplicate extra test columns instead of silently erasing them', () => {
+    const tracer = makeTestTracer(baseBinding, {
+      extraTestColumns: {
+        base_field: S.category(),
+      },
+    });
+
+    expect(() => tracer.setup()).toThrow(
+      "Test harness schema column 'base_field' already exists in the bound log schema",
+    );
+  });
+});

package/src/lib/testing/__tests__/extractFacts.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Tests for extractFacts - the bridge between buffers and facts.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
+import { defineOpContext } from '../../defineOpContext.js';
+import { defineCodeError } from '../../result.js';
+import { S } from '../../schema/builder.js';
+import { defineFeatureFlags } from '../../schema/defineFeatureFlags.js';
+import { defineLogSchema } from '../../schema/defineLogSchema.js';
+import { InMemoryFlagEvaluator } from '../../schema/evaluator.js';
+import { TestTracer } from '../../tracers/TestTracer.js';
+import { extractFacts } from '../extractFacts.js';
+import { ffFact, logInfo, logWarn, spanErr, spanOk, spanStarted, tagFact } from '../facts.js';
+
+// Define a test error for ctx.err tests
+const NOT_FOUND = defineCodeError('NOT_FOUND')<{ detail: string }>();
+
+describe('extractFacts', () => {
+  // Create a test schema
+  const testSchema = defineLogSchema({
+    userId: S.category(),
+    orderId: S.category(),
+    amount: S.number(),
+  });
+
+  const opContext = defineOpContext({ logSchema: testSchema });
+  const featureFlags = defineFeatureFlags({
+    advancedValidation: S.boolean().default(false).sync(),
+  });
+  const opContextWithFlags = defineOpContext({
+    logSchema: testSchema,
+    flags: featureFlags.schema,
+  });
+  const flagEvaluator = new InMemoryFlagEvaluator(featureFlags.schema, {
+    advancedValidation: true,
+  });
+
+  it('extracts span lifecycle facts from a simple trace', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    await tracer.trace('my-operation', async (ctx) => {
+      return ctx.ok('done');
+    });
+
+    expect(tracer.rootBuffers).toHaveLength(1);
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    // Should have started and ok facts
+    expect(facts.has(spanStarted('my-operation'))).toBe(true);
+    expect(facts.has(spanOk('my-operation'))).toBe(true);
+  });
+
+  it('extracts log facts', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    await tracer.trace('with-logs', async (ctx) => {
+      ctx.log.info('Starting process');
+      ctx.log.warn('Something to note');
+      return ctx.ok('done');
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    expect(facts.has(logInfo('Starting process'))).toBe(true);
+    expect(facts.has(logWarn('Something to note'))).toBe(true);
+  });
+
+  it('extracts tag facts from row 0', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    await tracer.trace('with-tags', async (ctx) => {
+      ctx.tag.userId('user-123').orderId('order-456');
+      return ctx.ok('done');
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    expect(facts.has(tagFact('userId', 'user-123'))).toBe(true);
+    expect(facts.has(tagFact('orderId', 'order-456'))).toBe(true);
+  });
+
+  it('extracts facts from nested spans in order', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    await tracer.trace('parent', async (ctx) => {
+      await ctx.span('child-1', async (childCtx) => {
+        return childCtx.ok('child-1 done');
+      });
+
+      await ctx.span('child-2', async (childCtx) => {
+        return childCtx.ok('child-2 done');
+      });
+
+      return ctx.ok('parent done');
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    // Check order: parent starts, child-1 complete, child-2 complete, parent completes
+    expect(
+      facts.hasInOrder([
+        spanStarted('parent'),
+        spanStarted('child-1'),
+        spanOk('child-1'),
+        spanStarted('child-2'),
+        spanOk('child-2'),
+        spanOk('parent'),
+      ]),
+    ).toBe(true);
+  });
+
+  it('extracts error facts from span:err', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    await tracer.trace('failing-op', async (ctx) => {
+      return ctx.err(NOT_FOUND({ detail: 'Resource missing' }));
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    expect(facts.has(spanStarted('failing-op'))).toBe(true);
+    expect(facts.has(spanErr('failing-op', 'NOT_FOUND'))).toBe(true);
+    expect(facts.has(spanOk('failing-op'))).toBe(false);
+  });
+
+  it('extracts feature flag access facts from system columns', async () => {
+    const tracer = new TestTracer(opContextWithFlags, {
+      ...createTestTracerOptions(),
+      flagEvaluator,
+    });
+
+    await tracer.trace('with-ff', async (ctx) => {
+      const validationFlag = ctx.ff.advancedValidation;
+      expect(validationFlag?.value).toBe(true);
+      return ctx.ok('done');
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    expect(facts.has(ffFact('advancedValidation', 'true'))).toBe(true);
+  });
+
+  it('filters facts by namespace', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    await tracer.trace('mixed', async (ctx) => {
+      ctx.log.info('A log message');
+      ctx.tag.userId('user-1');
+      return ctx.ok('done');
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    // Filter to just span facts
+    const spanFacts = facts.byNamespace('span');
+    expect(spanFacts.length).toBe(2); // started + ok
+
+    // Filter to just log facts
+    const logFacts = facts.byNamespace('log');
+    expect(logFacts.length).toBe(1);
+
+    // Filter to just tag facts
+    const tagFacts = facts.byNamespace('tag');
+    expect(tagFacts.length).toBe(1);
+  });
+
+  it('supports pattern matching', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    await tracer.trace('fetch-user', async (ctx) => {
+      await ctx.span('fetch-profile', async (c) => c.ok(null));
+      await ctx.span('fetch-orders', async (c) => c.ok(null));
+      return ctx.ok('done');
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    // Match any fetch-* span that started
+    expect(facts.hasMatch('span:fetch-*: started')).toBe(true);
+
+    // Match any span that completed ok
+    expect(facts.hasMatch('span:*: ok')).toBe(true);
+
+    // Should match multiple
+    const fetchStarts = facts.match('span:fetch-*: started');
+    expect(fetchStarts.length).toBe(3); // fetch-user, fetch-profile, fetch-orders
+  });
+
+  it('handles deeply nested spans', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    await tracer.trace('level-0', async (ctx) => {
+      await ctx.span('level-1', async (c1) => {
+        await c1.span('level-2', async (c2) => {
+          await c2.span('level-3', async (c3) => {
+            return c3.ok('deepest');
+          });
+          return c2.ok('l2');
+        });
+        return c1.ok('l1');
+      });
+      return ctx.ok('l0');
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    // All levels should appear
+    expect(facts.has(spanStarted('level-0'))).toBe(true);
+    expect(facts.has(spanStarted('level-1'))).toBe(true);
+    expect(facts.has(spanStarted('level-2'))).toBe(true);
+    expect(facts.has(spanStarted('level-3'))).toBe(true);
+
+    // Inner spans complete before outer
+    expect(facts.hasInOrder([spanOk('level-3'), spanOk('level-2'), spanOk('level-1'), spanOk('level-0')])).toBe(true);
+  });
+});
+
+describe('trace-testing patterns', () => {
+  const testSchema = defineLogSchema({
+    sku: S.category(),
+    quantity: S.number(),
+    reservationId: S.category(),
+  });
+
+  const opContext = defineOpContext({ logSchema: testSchema });
+
+  it('example: verify operation order without implementation details', async () => {
+    const tracer = new TestTracer(opContext, { ...createTestTracerOptions() });
+
+    // Simulate an order processing workflow
+    await tracer.trace('process-order', async (ctx) => {
+      ctx.tag.sku('SKU-A').quantity(5);
+
+      // Validate
+      await ctx.span('validate', async (c) => {
+        c.log.info('Validating order');
+        return c.ok({ valid: true });
+      });
+
+      // Reserve inventory
+      await ctx.span('reserve-inventory', async (c) => {
+        c.tag.reservationId('res-123');
+        return c.ok({ reserved: true });
+      });
+
+      // Charge payment
+      await ctx.span('charge-payment', async (c) => {
+        c.log.info('Charging $49.99');
+        return c.ok({ charged: true });
+      });
+
+      return ctx.ok('Order processed');
+    });
+
+    const facts = extractFacts(tracer.rootBuffers[0]);
+
+    // Test WHAT happened, not HOW
+
+    // 1. Order was processed successfully
+    expect(facts.has(spanOk('process-order'))).toBe(true);
+
+    // 2. Validation happened before inventory reservation
+    expect(facts.hasInOrder([spanOk('validate'), spanStarted('reserve-inventory')])).toBe(true);
+
+    // 3. Inventory was reserved before payment was charged
+    expect(facts.hasInOrder([spanOk('reserve-inventory'), spanStarted('charge-payment')])).toBe(true);
+
+    // 4. Expected tags were set
+    expect(facts.has(tagFact('sku', 'SKU-A'))).toBe(true);
+    expect(facts.has(tagFact('quantity', 5))).toBe(true);
+    expect(facts.has(tagFact('reservationId', 'res-123'))).toBe(true);
+
+    // 5. No errors occurred
+    expect(facts.hasMatch('span:*: err(*)')).toBe(false);
+    expect(facts.hasMatch('log:error: *')).toBe(false);
+  });
+});