@smoothbricks/lmao 0.1.0

package/src/lib/schema/systemSchema.ts

@@ -0,0 +1,339 @@
+/**
+ * System schema - base columns that all modules inherit
+ *
+ * Per specs/lmao/01h_entry_types_and_logging_primitives.md and 01f_arrow_table_structure.md:
+ * - These columns are available in all traces regardless of user schema
+ * - The `message` column is UNIFIED for span names, log message templates, exception messages, result messages, and feature flag names
+ */
+
+import type {
+  EagerCategorySchema,
+  LazyBigUint64Schema,
+  LazyCategorySchema,
+  LazyNumberSchema,
+  LazyTextSchema,
+} from '@smoothbricks/arrow-builder';
+import { S as ArrowS } from '@smoothbricks/arrow-builder';
+import { type DefinedLogSchema, defineLogSchema } from './defineLogSchema.js';
+import { LogSchema, type Schema } from './types.js';
+
+/**
+ * System schema field type - explicit type to avoid Sury's internal brand symbol leaking.
+ */
+export interface SystemSchemaFieldTypes extends Record<string, Schema<unknown>> {
+  message: EagerCategorySchema;
+  line: LazyNumberSchema;
+  error_code: LazyCategorySchema;
+  retry_attempt: LazyNumberSchema;
+  retry_delay_ms: LazyNumberSchema;
+  exception_stack: LazyTextSchema;
+  ff_value: LazyCategorySchema;
+  uint64_value: LazyBigUint64Schema;
+}
+
+// Use arrow-builder's S directly (not lmao's wrapped version) to get clean types
+// that don't include the flag builder methods - this avoids type inference issues.
+const messageSchema: EagerCategorySchema = ArrowS.category().eager();
+const lineSchema: LazyNumberSchema = ArrowS.number();
+const errorCodeSchema: LazyCategorySchema = ArrowS.category();
+const retryAttemptSchema: LazyNumberSchema = ArrowS.number();
+const retryDelayMsSchema: LazyNumberSchema = ArrowS.number();
+const exceptionStackSchema: LazyTextSchema = ArrowS.text();
+const ffValueSchema: LazyCategorySchema = ArrowS.category();
+const uint64ValueSchema: LazyBigUint64Schema = ArrowS.bigUint64();
+
+/**
+ * Raw system schema fields object.
+ * Using explicit type annotation to ensure proper type inference.
+ */
+/**
+ * System schema field names - used to filter out system fields when processing user schema
+ * These fields are handled separately in Arrow conversion and should not be included
+ * in the user attribute columns.
+ */
+export const SYSTEM_SCHEMA_FIELD_NAMES = new Set([
+  'message',
+  'line',
+  'error_code',
+  'retry_attempt',
+  'retry_delay_ms',
+  'exception_stack',
+  'ff_value',
+  'uint64_value',
+]);
+
+/**
+ * Reserved system column names - these correspond to Arrow table columns and cannot be
+ * used as user schema field names because they conflict with SpanBuffer properties.
+ */
+export const RESERVED_SYSTEM_COLUMN_NAMES = new Set([
+  // Arrow table columns (exact names)
+  'trace_id',
+  'thread_id',
+  'span_id',
+  'parent_thread_id',
+  'parent_span_id',
+  'timestamp',
+  'entry_type',
+]);
+
+const systemSchemaFields: SystemSchemaFieldTypes = {
+  /**
+   * Unified message column - serves different purposes based on entry type.
+   *
+   * Per specs/lmao/01h_entry_types_and_logging_primitives.md:
+   * - span-start, span-ok, span-err: Span name (e.g., 'create-user')
+   * - span-exception: Exception message (e.g., 'Connection timeout')
+   * - info, debug, warn, error, trace: Log message TEMPLATE (e.g., 'User ${userId} created')
+   * - ff-access, ff-usage: Feature flag name (e.g., 'darkMode')
+   * - tag: Span name (same as span lifecycle entries)
+   *
+   * Uses S.category().eager() because:
+   * - Message is ALWAYS written for every entry type (span name, log message, etc.)
+   * - Eager allocation eliminates null bitmap overhead (never null)
+   * - Span names repeat across many traces
+   * - Log templates repeat (only values differ)
+   * - Flag names repeat across evaluations
+   * - Exception messages often repeat (same error types)
+   * - String interning provides excellent compression
+   *
+   * NOTE: Log messages are FORMAT STRINGS, NOT interpolated! The template is stored
+   * verbatim, and values go in their own typed columns for queryability.
+   */
+  message: messageSchema,
+
+  /**
+   * Source code line number for this entry.
+   *
+   * Per specs/lmao/01c_context_flow_and_op_wrappers.md "Line Number System":
+   * - Uint16 column (max 65535 lines per file)
+   * - TypeScript transformer injects line numbers at compile time
+   * - No runtime overhead - just a method call with literal number
+   * - Value of 0 means "line number not set"
+   *
+   * Used for:
+   * - Linking trace entries back to source code
+   * - Debugging and error analysis
+   * - IDE integration for "jump to line"
+   */
+  line: lineSchema,
+
+  // Error handling
+  error_code: errorCodeSchema,
+  retry_attempt: retryAttemptSchema,
+  retry_delay_ms: retryDelayMsSchema,
+  exception_stack: exceptionStackSchema,
+
+  // Feature flags (ffName is now part of unified `message` column)
+  ff_value: ffValueSchema, // Can be boolean, string, or number as string
+
+  /**
+   * uint64 value column for metrics and user .uint64() API.
+   *
+   * Per specs/lmao/01f_arrow_table_structure.md:
+   * - Metric values (counts, durations in nanoseconds)
+   * - User large integers via .uint64() fluent method
+   * - Sparse data (only rows that need uint64)
+   *
+   * Uses S.bigUint64() (lazy BigUint64Array) because:
+   * - Most trace rows don't have a uint64 value
+   * - Only metrics rows and entries where .uint64() is called
+   * - Zero overhead for rows that don't use it
+   */
+  uint64_value: uint64ValueSchema,
+};
+
+/**
+ * Base system schema that all modules inherit.
+ * Wrapped with defineLogSchema for validation and extension support.
+ */
+export const systemSchema: DefinedLogSchema<SystemSchemaFieldTypes> = defineLogSchema(
+  systemSchemaFields,
+  // Skip reserved name validation for system schema - `message` is a system column
+  { _skipReservedNameValidation: true },
+);
+
+/**
+ * Merge system schema with user schema
+ * System columns are always included, user schema extends them
+ *
+ * Warns if user schema conflicts with system schema fields or reserved column names.
+ */
+export function mergeWithSystemSchema<T extends Record<string, unknown>>(userSchema: T): SystemSchemaFieldTypes & T {
+  // Check for conflicts between user schema and system schema
+  // Use fieldNames to get only actual field names, not ColumnSchema properties or methods
+  const systemKeys = new Set(systemSchema._columnNames);
+  const reservedKeys = RESERVED_SYSTEM_COLUMN_NAMES;
+  const userKeys = userSchema instanceof LogSchema ? userSchema._columnNames : Object.keys(userSchema);
+  const userFields = userSchema instanceof LogSchema ? userSchema.fields : userSchema;
+
+  const conflictingSystemKeys = userKeys.filter((key) => {
+    // Only check if it's a schema field (not a method like validate/parse/extend)
+    const value = userFields[key];
+    return systemKeys.has(key) && typeof value !== 'function';
+  });
+
+  const conflictingReservedKeys = userKeys.filter((key) => {
+    const value = userFields[key];
+    return reservedKeys.has(key) && typeof value !== 'function';
+  });
+
+  if (conflictingSystemKeys.length > 0) {
+    throw new Error(
+      `User schema conflicts with system schema fields: ${conflictingSystemKeys.join(', ')}\n` +
+        'System schema fields are reserved and cannot be overridden.\n' +
+        `System fields: ${Array.from(systemKeys).join(', ')}`,
+    );
+  }
+
+  if (conflictingReservedKeys.length > 0) {
+    throw new Error(
+      `User schema cannot include reserved system column names: ${conflictingReservedKeys.join(', ')}\n` +
+        '   These names conflict with SpanBuffer properties that correspond to Arrow table columns.\n' +
+        `   Reserved names: ${Array.from(reservedKeys).join(', ')}`,
+    );
+  }
+
+  // Spread .fields to get the actual schema field definitions
+  // (spreading systemSchema directly would spread class instance properties like _fieldNames, not schema fields)
+  const merged: SystemSchemaFieldTypes & T = {
+    ...systemSchema.fields,
+    ...userFields,
+  };
+  return merged;
+}
+
+// =============================================================================
+// Entry Type Constants
+// =============================================================================
+// Per specs/lmao/01h_entry_types_and_logging_primitives.md
+// Stored in Uint8Array for 1-byte storage per entry.
+// Ordered by frequency/importance:
+// 1-4: Span lifecycle (most common - every span has start + end)
+// 5-9: Logging levels (ordered by verbosity: trace < debug < info < warn < error)
+// 10-11: Feature flags (least common)
+// =============================================================================
+
+/** Span start event - written at row 0 when a span begins */
+export const ENTRY_TYPE_SPAN_START = 1;
+
+/** Span success completion - written to row 1 via ctx.ok() */
+export const ENTRY_TYPE_SPAN_OK = 2;
+
+/** Span error completion - written to row 1 via ctx.err() */
+export const ENTRY_TYPE_SPAN_ERR = 3;
+
+/** Span exception - written to row 1 when an unhandled exception occurs */
+export const ENTRY_TYPE_SPAN_EXCEPTION = 4;
+
+/** Span retry - written when a transient failure triggers a retry attempt (Phase 19) */
+export const ENTRY_TYPE_SPAN_RETRY = 5;
+
+/** Trace log level entry - via ctx.log.trace() (most verbose) */
+export const ENTRY_TYPE_TRACE = 6;
+
+/** Debug log level entry - via ctx.log.debug() */
+export const ENTRY_TYPE_DEBUG = 7;
+
+/** Info log level entry - via ctx.log.info() */
+export const ENTRY_TYPE_INFO = 8;
+
+/** Warning log level entry - via ctx.log.warn() */
+export const ENTRY_TYPE_WARN = 9;
+
+/** Error log level entry - via ctx.log.error() */
+export const ENTRY_TYPE_ERROR = 10;
+
+/** Feature flag access event - logged when a flag value is first read in a span */
+export const ENTRY_TYPE_FF_ACCESS = 11;
+
+/** Feature flag usage event - logged when a flag influences a code path decision */
+export const ENTRY_TYPE_FF_USAGE = 12;
+
+// =============================================================================
+// Period Markers
+// =============================================================================
+
+/** Period start marker - written at the beginning of each metrics collection period */
+export const ENTRY_TYPE_PERIOD_START = 13;
+
+// =============================================================================
+// Op Metrics (per specs/lmao/01n_op_and_buffer_metrics.md)
+// =============================================================================
+
+/** Op invocations counter - total calls to this operation */
+export const ENTRY_TYPE_OP_INVOCATIONS = 14;
+
+/** Op errors counter - calls that returned err() */
+export const ENTRY_TYPE_OP_ERRORS = 15;
+
+/** Op exceptions counter - calls that threw unhandled exceptions */
+export const ENTRY_TYPE_OP_EXCEPTIONS = 16;
+
+/** Op duration total - sum of all invocation durations (ms) */
+export const ENTRY_TYPE_OP_DURATION_TOTAL = 17;
+
+/** Op duration ok - sum of successful invocation durations (ms) */
+export const ENTRY_TYPE_OP_DURATION_OK = 18;
+
+/** Op duration err - sum of error invocation durations (ms) */
+export const ENTRY_TYPE_OP_DURATION_ERR = 19;
+
+/** Op duration min - minimum invocation duration (ms) */
+export const ENTRY_TYPE_OP_DURATION_MIN = 20;
+
+/** Op duration max - maximum invocation duration (ms) */
+export const ENTRY_TYPE_OP_DURATION_MAX = 21;
+
+// =============================================================================
+// Buffer Metrics (utilization-based capacity tuning)
+// =============================================================================
+
+/** Buffer writes counter - total writes across all buffers */
+export const ENTRY_TYPE_BUFFER_WRITES = 22;
+
+/** Buffer spans counter - number of spans created (non-overflow buffers) */
+export const ENTRY_TYPE_BUFFER_SPANS = 23;
+
+/** Buffer capacity - current buffer capacity for this module */
+export const ENTRY_TYPE_BUFFER_CAPACITY = 24;
+
+/**
+ * Human-readable names for entry types, indexed by entry type code.
+ *
+ * Used for Arrow dictionary encoding and display purposes.
+ * Index 0 is unused (entry types start at 1).
+ *
+ * @example
+ * ```typescript
+ * const entryType = buffer.entry_type[index];
+ * const typeName = ENTRY_TYPE_NAMES[entryType]; // e.g., 'span-ok'
+ * ```
+ */
+export const ENTRY_TYPE_NAMES = [
+  '', // 0 - unused
+  'span-start', // 1
+  'span-ok', // 2
+  'span-err', // 3
+  'span-exception', // 4
+  'span-retry', // 5 (Phase 19 - transient failure retry)
+  'trace', // 6 (most verbose)
+  'debug', // 7
+  'info', // 8
+  'warn', // 9
+  'error', // 10
+  'ff-access', // 11
+  'ff-usage', // 12
+  'period-start', // 13
+  'op-invocations', // 14
+  'op-errors', // 15
+  'op-exceptions', // 16
+  'op-duration-total', // 17
+  'op-duration-ok', // 18
+  'op-duration-err', // 19
+  'op-duration-min', // 20
+  'op-duration-max', // 21
+  'buffer-writes', // 22
+  'buffer-spans', // 23
+  'buffer-capacity', // 24
+] as const;

package/src/lib/schema/typeGuards.ts

@@ -0,0 +1,163 @@
+/**
+ * Type guard functions for runtime type checking
+ *
+ * Re-exports schema type guards from arrow-builder and adds lmao-specific guards.
+ */
+
+// Re-export schema type guards from arrow-builder
+export {
+  getBinaryEncoder,
+  getEnumUtf8,
+  getEnumValues,
+  getSchemaType,
+  isEnumSchema,
+  isSchemaWithMetadata,
+} from '@smoothbricks/arrow-builder';
+
+import type { EvaluationContext, UsageContext } from './defineFeatureFlags.js';
+import type { FeatureFlagDefinition } from './types.js';
+
+/** Narrow unknown to Record<string, unknown> — non-null object with string-keyed access. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Type guard to check if a value is a FeatureFlagDefinition
+ */
+export function isFeatureFlagDefinition(value: unknown): value is FeatureFlagDefinition<string | number | boolean> {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  return (
+    'schema' in value &&
+    'defaultValue' in value &&
+    'evaluationType' in value &&
+    (value.evaluationType === 'sync' || value.evaluationType === 'async')
+  );
+}
+
+/**
+ * Type guard to check if a value is a valid EvaluationContext
+ */
+export function isEvaluationContext(value: unknown): value is EvaluationContext {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  // EvaluationContext can have various string/number/boolean properties
+  // Check that all values are of valid types
+  for (const key in value) {
+    const val = value[key];
+    if (val !== undefined && typeof val !== 'string' && typeof val !== 'number' && typeof val !== 'boolean') {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Type guard to check if a value is a valid UsageContext
+ */
+export function isUsageContext(value: unknown): value is UsageContext {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  // Check action property if present
+  if ('action' in value && typeof value.action !== 'string' && value.action !== undefined) {
+    return false;
+  }
+
+  // Check outcome property if present
+  if ('outcome' in value && value.outcome !== undefined && value.outcome !== 'success' && value.outcome !== 'failure') {
+    return false;
+  }
+
+  // Check value property if present
+  if ('value' in value && typeof value.value !== 'number' && value.value !== undefined) {
+    return false;
+  }
+
+  // Check metadata property if present
+  if ('metadata' in value && value.metadata !== undefined) {
+    if (!isRecord(value.metadata)) {
+      return false;
+    }
+
+    // Validate metadata values
+    const metadata = value.metadata;
+    for (const key in metadata) {
+      const val = metadata[key];
+      if (typeof val !== 'string' && typeof val !== 'number' && typeof val !== 'boolean') {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Type guard to check if a value is a string
+ * Useful for narrowing unknown types in safe contexts
+ */
+export function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+/**
+ * Type guard to check if a value is a number
+ * Useful for narrowing unknown types in safe contexts
+ */
+export function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && !Number.isNaN(value);
+}
+
+/**
+ * Type guard to check if a value is a boolean
+ * Useful for narrowing unknown types in safe contexts
+ */
+export function isBoolean(value: unknown): value is boolean {
+  return typeof value === 'boolean';
+}
+
+/**
+ * Type guard to check if a value is a primitive type (string | number | boolean)
+ * Useful for validating feature flag values and tag attributes
+ */
+export function isPrimitive(value: unknown): value is string | number | boolean {
+  return isString(value) || isNumber(value) || isBoolean(value);
+}
+
+/**
+ * Type guard to check if a value is a plain object (not array, not null)
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+/**
+ * Type guard to check if a value is a valid record with primitive values
+ * Useful for validating tag attribute objects
+ */
+export function isRecordOfPrimitives(value: unknown): value is Record<string, string | number | boolean> {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+
+  for (const key in value) {
+    if (!isPrimitive(value[key])) {
+      return false;
+    }
+  }
+
+  return true;
+}