@smoothbricks/lmao 0.1.0

package/dist/lib/schema/defineLogSchema.js

@@ -0,0 +1,171 @@
+import { LogSchema } from './LogSchema.js';
+/**
+ * Validate a single field value against its schema metadata.
+ * Uses __schema_type for type dispatch — no Sury dependency.
+ *
+ * Handles all schema compositions: optional, refine, union, key.
+ * Throws on unknown __schema_type to prevent silent acceptance of invalid data.
+ */
+function validateField(key, value, schema) {
+    const s = schema;
+    // Handle optional schemas (created via S.optional())
+    if (s.__optional) {
+        if (value === undefined || value === null)
+            return undefined;
+        // Value is present — recursively validate against the inner schema
+        if (s.__inner) {
+            return validateField(key, value, s.__inner);
+        }
+        // Optional with no inner schema — accept the value as-is
+        // (shouldn't happen with well-formed schemas, but defensive)
+        return value;
+    }
+    if (value === undefined || value === null) {
+        throw new Error(`Field "${key}": expected a value, got ${value === null ? 'null' : 'undefined'}`);
+    }
+    // Handle refine() schemas — invoke the stored refiner function
+    if (s.__refiner) {
+        try {
+            return s.__refiner(value, {
+                fail(msg) {
+                    throw new Error(`Field "${key}": refinement failed — ${msg}`);
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith(`Field "${key}":`))
+                throw err;
+            throw new Error(`Field "${key}": refinement failed — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Handle union() schemas — try each member, accept if any matches
+    if (s.__union) {
+        const errors = [];
+        for (const member of s.__union) {
+            try {
+                return validateField(key, value, member);
+            }
+            catch (err) {
+                errors.push(err instanceof Error ? err.message : String(err));
+            }
+        }
+        throw new Error(`Field "${key}": value does not match any union member. Tried ${s.__union.length}: ${errors.join('; ')}`);
+    }
+    switch (s.__schema_type) {
+        case 'number':
+            if (typeof value !== 'number')
+                throw new Error(`Field "${key}": expected number, got ${typeof value}`);
+            return value;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                throw new Error(`Field "${key}": expected boolean, got ${typeof value}`);
+            return value;
+        case 'text':
+        case 'category':
+            if (typeof value !== 'string')
+                throw new Error(`Field "${key}": expected string, got ${typeof value}`);
+            return value;
+        case 'enum':
+            if (typeof value !== 'string')
+                throw new Error(`Field "${key}": expected string, got ${typeof value}`);
+            if (s.__enum_values && !s.__enum_values.includes(value)) {
+                throw new Error(`Field "${key}": expected one of [${s.__enum_values.join(', ')}], got "${value}"`);
+            }
+            return value;
+        case 'bigUint64':
+            if (typeof value !== 'bigint')
+                throw new Error(`Field "${key}": expected bigint, got ${typeof value}`);
+            return value;
+        case 'binary':
+            // Binary accepts any value (raw bytes or encoder-wrapped)
+            return value;
+        case 'key':
+            // Key schema — validate the runtime value using the stored validator
+            if (typeof value !== 'string')
+                throw new Error(`Field "${key}": expected string key value, got ${typeof value}`);
+            if (s.__key_validator) {
+                return s.__key_validator(value);
+            }
+            return value;
+        default:
+            throw new Error(`Field "${key}": unknown schema type "${s.__schema_type ?? '<none>'}". ` +
+                'All schema types must be explicitly handled in validateField.');
+    }
+}
+/**
+ * Validate an object against a set of schema columns.
+ */
+function validateObject(data, columns) {
+    if (!isUnknownRecord(data)) {
+        throw new Error(`Expected object, got ${data === null ? 'null' : typeof data}`);
+    }
+    const result = {};
+    for (const [key, schema] of columns) {
+        result[key] = validateField(key, data[key], schema);
+    }
+    assertValidatedObject(result, columns);
+    return result;
+}
+function isUnknownRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function assertValidatedObject(value, columns) {
+    for (const [key] of columns) {
+        if (!(key in value)) {
+            throw new Error(`Missing validated field "${key}"`);
+        }
+    }
+}
+export function defineLogSchema(schema, options) {
+    // Wrap user input into LogSchema first
+    const logSchema = schema instanceof LogSchema ? schema : new LogSchema(schema);
+    // Assert attribute names don't use reserved names
+    if (!options?._skipReservedNameValidation) {
+        LogSchema.assertUserFieldNames(logSchema._columnNames);
+    }
+    // Add validation methods directly to logSchema (preserves LogSchema instance)
+    // Use Object.assign to mutate logSchema in place, preserving prototype chain
+    const result = Object.assign(logSchema, {
+        /**
+         * Validate data and throw on error
+         *
+         * @throws Error if validation fails
+         */
+        validate: (data) => {
+            return validateObject(data, logSchema._columns);
+        },
+        /**
+         * Validate data and return null on error
+         *
+         * @returns Validated data or null if invalid
+         */
+        parse: (data) => {
+            try {
+                return validateObject(data, logSchema._columns);
+            }
+            catch {
+                return null;
+            }
+        },
+        /**
+         * Safe parse with detailed error information
+         *
+         * @returns Result object with success flag
+         */
+        safeParse: (data) => {
+            try {
+                return { success: true, value: validateObject(data, logSchema._columns) };
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                return { success: false, error };
+            }
+        },
+    });
+    // Verify result is still a LogSchema instance (Object.assign returns the mutated target)
+    if (!(result instanceof LogSchema)) {
+        throw new Error('defineLogSchema: Object.assign broke LogSchema instance');
+    }
+    // Return logSchema (still a LogSchema instance with added methods)
+    return result;
+}

package/dist/lib/schema/evaluator.d.ts

@@ -0,0 +1,267 @@
+import type { FluentLogEntry } from '../codegen/spanLoggerGenerator.js';
+import type { OpContext } from '../opContext/types.js';
+import type { SpanContext } from '../spanContext.js';
+import type { FeatureFlagSchema } from './defineFeatureFlags.js';
+import type { LogSchema } from './LogSchema.js';
+/**
+ * Serializable flag value types
+ */
+export type FlagValue = string | number | boolean | null;
+/**
+ * SpanContext without 'ff' field - prevents infinite recursion in evaluators
+ */
+export type SpanContextWithoutFf<Ctx extends OpContext> = Omit<SpanContext<Ctx>, 'ff'>;
+/**
+ * Feature flag evaluator interface (backend implementation)
+ *
+ * This is implemented by the backend (database, LaunchDarkly, etc.)
+ * and provides the actual flag values.
+ *
+ * ## Stateless Design - ctx is a parameter
+ *
+ * The evaluator receives `Omit<SpanContext, 'ff'>` as a PARAMETER (not stored state).
+ * This allows the evaluator to:
+ * - Be stateless (CAN be a singleton, but doesn't have to be)
+ * - Access full context (ctx.log, ctx.span, ctx.scope, ctx.deps, user properties)
+ * - Prevent infinite recursion (can't access ctx.ff which would call evaluator again)
+ *
+ * ## forContext() - Flexible Wrapper Creation
+ *
+ * The evaluator decides how to create the per-span wrapper:
+ * - Return a new wrapper with `this` as the evaluator (most common - reuse evaluator)
+ * - Return `this` if the evaluator itself implements the wrapper interface
+ * - Return a completely different evaluator/wrapper (e.g., per-span caching)
+ *
+ * The wrapper (FeatureFlagEvaluator) holds a ctx reference to enable fluent getters.
+ *
+ * @template Ctx - OpContext bundle (contains flags via Ctx['flags'])
+ */
+export interface FlagEvaluator<Ctx extends OpContext = OpContext> {
+    /**
+     * Get a flag value synchronously (for cached/static flags)
+     *
+     * The evaluator receives ctx as a parameter (stateless design).
+     * Can use ctx.log/ctx.span for tracing, ctx.scope for targeting.
+     *
+     * @param ctx - SpanContext without 'ff' (can log, create spans, access scope)
+     * @param flag - Flag name to evaluate
+     */
+    getSync<K extends string>(ctx: SpanContextWithoutFf<Ctx>, flag: K): FlagValue;
+    /**
+     * Get a flag value asynchronously (for dynamic flags)
+     *
+     * The evaluator receives ctx as a parameter (stateless design).
+     * Can use ctx.log/ctx.span for tracing external calls.
+     *
+     * @param ctx - SpanContext without 'ff' (can log, create spans, access scope)
+     * @param flag - Flag name to evaluate
+     */
+    getAsync<K extends string>(ctx: SpanContextWithoutFf<Ctx>, flag: K): Promise<FlagValue>;
+    /**
+     * Factory method: Create per-span wrapper from span context.
+     *
+     * Returns a FeatureFlagEvaluator (per-span wrapper) with typed getters for each flag.
+     *
+     * ## Implementation Choices
+     *
+     * Common pattern: Return a new wrapper that holds `this` as the evaluator
+     * ```typescript
+     * forContext(ctx) {
+     *   return new FeatureFlagEvaluator(schema, ctx, this); // Reuse evaluator, new wrapper
+     * }
+     * ```
+     *
+     * Alternative: Return `this` if evaluator implements the wrapper interface
+     * ```typescript
+     * forContext(ctx) {
+     *   return this; // Evaluator itself is the wrapper (uncommon)
+     * }
+     * ```
+     *
+     * Alternative: Return different evaluator (e.g., per-span caching layer)
+     * ```typescript
+     * forContext(ctx) {
+     *   return new CachedEvaluator(ctx, this); // Different wrapper with caching
+     * }
+     * ```
+     *
+     * The wrapper MUST store ctx because JS getters (`get darkMode()`) cannot receive parameters.
+     *
+     * Receives `Omit<SpanContext, 'ff'>` to prevent infinite recursion.
+     */
+    forContext(ctx: SpanContextWithoutFf<Ctx>): FeatureFlagEvaluator<Ctx> & InferFeatureFlagsWithContext<Ctx>;
+}
+/**
+ * Column writers interface (to be implemented in buffer phase)
+ *
+ * Used for logging flag access and usage to span buffers.
+ */
+export interface FlagColumnWriters {
+    writeEntryType(type: 'ff-access' | 'ff-usage'): void;
+    writeFfName(name: string): void;
+    writeFfValue(value: FlagValue): void;
+    writeAction(action?: string): void;
+    writeOutcome(outcome?: string): void;
+    writeContextAttributes(context: Record<string, unknown>): void;
+}
+/**
+ * Track context for feature flag usage analytics
+ */
+export interface FlagTrackContext {
+    action?: string;
+    outcome?: string;
+}
+/**
+ * Boolean flag context - returned when boolean flag is true
+ */
+export interface BooleanFlagContext<TLog extends LogSchema = LogSchema> {
+    readonly value: true;
+    track(context?: FlagTrackContext): FluentLogEntry<TLog>;
+}
+/**
+ * Variant flag context - returned when variant flag is enabled
+ */
+export interface VariantFlagContext<V extends string, TLog extends LogSchema = LogSchema> {
+    readonly value: V;
+    track(context?: FlagTrackContext): FluentLogEntry<TLog>;
+}
+/**
+ * Config flag context - returned when config flag is enabled
+ * Spreads the config object and adds track() method
+ */
+export type ConfigFlagContext<T extends Record<string, unknown>, TLog extends LogSchema = LogSchema> = T & {
+    track(context?: FlagTrackContext): FluentLogEntry<TLog>;
+};
+/**
+ * Infer the flag context type for a single flag definition
+ */
+type InferFlagContextType<Ctx extends OpContext, T> = T extends boolean ? BooleanFlagContext<Ctx['logSchema']> : T extends string ? VariantFlagContext<T, Ctx['logSchema']> : T extends Record<string, unknown> ? ConfigFlagContext<T, Ctx['logSchema']> : {
+    value: T;
+    track(context?: FlagTrackContext): FluentLogEntry<Ctx['logSchema']>;
+};
+/**
+ * Infer feature flag types from OpContext - returns FlagContext | undefined for each flag
+ *
+ * - Returns undefined when flag is false/disabled
+ * - Returns FlagContext wrapper when flag is truthy/enabled
+ */
+export type InferFeatureFlagsWithContext<Ctx extends OpContext> = Ctx['flags'] extends FeatureFlagSchema ? {
+    readonly [K in keyof Ctx['flags']]: InferFlagContextType<Ctx, import('@smoothbricks/arrow-builder').Output<Ctx['flags'][K]['schema']>> | undefined;
+} : Record<string, never>;
+/**
+ * Feature flag evaluator with undefined/truthy semantics (PER-SPAN WRAPPER)
+ *
+ * ## Architecture: Stateless Evaluator + Per-Span Wrapper
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ FlagEvaluator (backend - CAN be singleton)                  │
+ * │ - getSync(ctx, flag) → FlagValue                            │
+ * │ - getAsync(ctx, flag) → Promise<FlagValue>                  │
+ * │ - forContext(ctx) → new FeatureFlagEvaluator(ctx, this)     │
+ * └─────────────────────────────────────────────────────────────┘
+ *                          ▲
+ *                          │ reference (can be reused or new)
+ *                          │
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ FeatureFlagEvaluator (PER-SPAN - holds ctx reference)       │
+ * │ #spanContext = ctx                                          │
+ * │ #evaluator = backend evaluator                              │
+ * │                                                             │
+ * │ get darkMode() {                                            │
+ * │   return this.#getFlag('darkMode');                         │
+ * │   // calls this.#evaluator.getSync(this.#spanContext, 'x')  │
+ * │ }                                                           │
+ * │                                                             │
+ * │ forContext(childCtx) {                                      │
+ * │   // Reuse same evaluator, new wrapper with childCtx        │
+ * │   return new FeatureFlagEvaluator(childCtx, this.#evaluator)│
+ * │ }                                                           │
+ * └─────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Why Per-Span Wrapper?
+ *
+ * JS getters (`get darkMode()`) cannot receive parameters. To provide the fluent
+ * API `ctx.ff.darkMode`, we need to store the ctx reference in the wrapper instance.
+ *
+ * The backend evaluator (FlagEvaluator) receives ctx as a parameter, so it CAN be
+ * stateless/singleton. The wrapper is created per-span to bind ctx to getters.
+ *
+ * ## Behavior
+ *
+ * - Returns undefined when flag is false/disabled
+ * - Returns FlagContext wrapper when flag is truthy/enabled
+ * - First access logs ff-access entry
+ * - Subsequent access in same span returns cached value (no duplicate log)
+ * - track() always logs ff-usage entry
+ *
+ * ## V8 Optimization Benefits
+ *
+ * - Stable hidden class (all instances have same shape)
+ * - Monomorphic property access (getters are real properties)
+ * - No Proxy trap overhead
+ * - Inline caching works properly
+ *
+ * ## Generated Class Pattern
+ *
+ * The class constructor returns a generated class instance rather than this instance.
+ * This is a valid JavaScript pattern for creating optimized instances with schema-specific properties.
+ *
+ * @template Ctx - OpContext bundle (contains flags via Ctx['flags'])
+ */
+export declare abstract class FeatureFlagEvaluator<Ctx extends OpContext = OpContext> {
+    /**
+     * Get async flag value
+     * Returns undefined when false, FlagContext when truthy
+     */
+    abstract get<K extends keyof InferFeatureFlagsWithContext<Ctx> & string>(flag: K): Promise<InferFeatureFlagsWithContext<Ctx>[K]>;
+    abstract get(flag: string): Promise<unknown>;
+    /**
+     * Create a new wrapper for a child span context.
+     *
+     * The implementation can reuse the same evaluator (singleton pattern),
+     * create a new evaluator, or return `this` if the evaluator itself
+     * implements the wrapper interface.
+     */
+    abstract forContext(ctx: SpanContext<Ctx>): FeatureFlagEvaluator<Ctx> & InferFeatureFlagsWithContext<Ctx>;
+}
+/**
+ * Create a FeatureFlagEvaluator instance using the generated class
+ */
+export declare function createFeatureFlagEvaluator<Ctx extends OpContext>(schema: Ctx['flags'], spanContext: SpanContextWithoutFf<Ctx>, evaluator: FlagEvaluator<Ctx>): FeatureFlagEvaluator<Ctx> & InferFeatureFlagsWithContext<Ctx>;
+/**
+ * Simple in-memory flag evaluator for testing
+ *
+ * Demonstrates the simplest evaluator pattern:
+ * - getSync/getAsync receive ctx first, enabling evaluators to use ctx.log, ctx.scope
+ * - forContext bootstraps the generated FeatureFlagEvaluator class (creates per-span wrapper)
+ * - Generated class has typed getters (ff.darkMode) and calls this.getSync(ctx, flag)
+ */
+export declare class InMemoryFlagEvaluator<Ctx extends OpContext = OpContext> implements FlagEvaluator<Ctx> {
+    private flags;
+    private ffSchema;
+    constructor(ffSchema: Ctx['flags'], initialFlags?: Record<string, FlagValue>);
+    /**
+     * Get flag value synchronously.
+     * Simple evaluator ignores ctx - just returns stored value.
+     * Advanced evaluators can use ctx.log, ctx.span, ctx.scope, etc.
+     */
+    getSync<K extends string>(_ctx: SpanContextWithoutFf<Ctx>, flag: K): FlagValue;
+    /**
+     * Get flag value asynchronously.
+     * Simple evaluator ignores ctx - just returns stored value.
+     * Advanced evaluators can use ctx.log, ctx.span for tracing external calls.
+     */
+    getAsync<K extends string>(_ctx: SpanContextWithoutFf<Ctx>, flag: K): Promise<FlagValue>;
+    setFlag(flag: string, value: FlagValue): void;
+    /**
+     * Create span-bound FeatureFlagEvaluator with typed getters.
+     *
+     * Returns a per-span wrapper that holds ctx reference and reuses this evaluator.
+     * The generated class has typed getters (ff.darkMode) and calls this.getSync(ctx, flag).
+     */
+    forContext(ctx: SpanContextWithoutFf<Ctx>): FeatureFlagEvaluator<Ctx> & InferFeatureFlagsWithContext<Ctx>;
+}
+export {};
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/lib/schema/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/evaluator.ts"],"names":[],"mappings":"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"}

package/dist/lib/schema/evaluator.js

@@ -0,0 +1,169 @@
+import { createEvaluatorClass } from '../codegen/evaluatorGenerator.js';
+import { ENTRY_TYPE_FF_ACCESS } from './systemSchema.js';
+function validateFlagValue(value, schema, defaultValue) {
+    const meta = schema;
+    // Handle refine() schemas — invoke the stored refiner, fall back to default on failure
+    if (meta.__refiner) {
+        try {
+            return meta.__refiner(value, {
+                fail(msg) {
+                    throw new Error(msg);
+                },
+            });
+        }
+        catch {
+            return defaultValue;
+        }
+    }
+    switch (meta.__schema_type) {
+        case 'number':
+            return typeof value === 'number' ? value : defaultValue;
+        case 'boolean':
+            return typeof value === 'boolean' ? value : defaultValue;
+        case 'text':
+        case 'category':
+            return typeof value === 'string' ? value : defaultValue;
+        case 'enum':
+            if (typeof value !== 'string')
+                return defaultValue;
+            if (meta.__enum_values && !meta.__enum_values.includes(value))
+                return defaultValue;
+            return value;
+        case 'bigUint64':
+            return typeof value === 'bigint' ? value : defaultValue;
+        case 'key':
+            // Key schema in feature flags — validate it's a string
+            return typeof value === 'string' ? value : defaultValue;
+        default:
+            // Unknown schema type — reject by returning the default value.
+            // This prevents silently accepting invalid data for unhandled schema types.
+            return defaultValue;
+    }
+}
+// ============================================================================
+// Feature Flag Evaluator Class
+// ============================================================================
+/**
+ * Get or create a generated evaluator class for a schema.
+ *
+ * The worker-safe constructor cache lives in `evaluatorGenerator.ts`.
+ */
+function getOrCreateEvaluatorClass(schema) {
+    return createEvaluatorClass(schema, validateFlagValue, ENTRY_TYPE_FF_ACCESS);
+}
+/**
+ * Feature flag evaluator with undefined/truthy semantics (PER-SPAN WRAPPER)
+ *
+ * ## Architecture: Stateless Evaluator + Per-Span Wrapper
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ FlagEvaluator (backend - CAN be singleton)                  │
+ * │ - getSync(ctx, flag) → FlagValue                            │
+ * │ - getAsync(ctx, flag) → Promise<FlagValue>                  │
+ * │ - forContext(ctx) → new FeatureFlagEvaluator(ctx, this)     │
+ * └─────────────────────────────────────────────────────────────┘
+ *                          ▲
+ *                          │ reference (can be reused or new)
+ *                          │
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ FeatureFlagEvaluator (PER-SPAN - holds ctx reference)       │
+ * │ #spanContext = ctx                                          │
+ * │ #evaluator = backend evaluator                              │
+ * │                                                             │
+ * │ get darkMode() {                                            │
+ * │   return this.#getFlag('darkMode');                         │
+ * │   // calls this.#evaluator.getSync(this.#spanContext, 'x')  │
+ * │ }                                                           │
+ * │                                                             │
+ * │ forContext(childCtx) {                                      │
+ * │   // Reuse same evaluator, new wrapper with childCtx        │
+ * │   return new FeatureFlagEvaluator(childCtx, this.#evaluator)│
+ * │ }                                                           │
+ * └─────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Why Per-Span Wrapper?
+ *
+ * JS getters (`get darkMode()`) cannot receive parameters. To provide the fluent
+ * API `ctx.ff.darkMode`, we need to store the ctx reference in the wrapper instance.
+ *
+ * The backend evaluator (FlagEvaluator) receives ctx as a parameter, so it CAN be
+ * stateless/singleton. The wrapper is created per-span to bind ctx to getters.
+ *
+ * ## Behavior
+ *
+ * - Returns undefined when flag is false/disabled
+ * - Returns FlagContext wrapper when flag is truthy/enabled
+ * - First access logs ff-access entry
+ * - Subsequent access in same span returns cached value (no duplicate log)
+ * - track() always logs ff-usage entry
+ *
+ * ## V8 Optimization Benefits
+ *
+ * - Stable hidden class (all instances have same shape)
+ * - Monomorphic property access (getters are real properties)
+ * - No Proxy trap overhead
+ * - Inline caching works properly
+ *
+ * ## Generated Class Pattern
+ *
+ * The class constructor returns a generated class instance rather than this instance.
+ * This is a valid JavaScript pattern for creating optimized instances with schema-specific properties.
+ *
+ * @template Ctx - OpContext bundle (contains flags via Ctx['flags'])
+ */
+export class FeatureFlagEvaluator {
+}
+/**
+ * Create a FeatureFlagEvaluator instance using the generated class
+ */
+export function createFeatureFlagEvaluator(schema, spanContext, evaluator) {
+    const GeneratedClass = getOrCreateEvaluatorClass(schema);
+    const instance = new GeneratedClass(spanContext, evaluator);
+    return instance;
+}
+/**
+ * Simple in-memory flag evaluator for testing
+ *
+ * Demonstrates the simplest evaluator pattern:
+ * - getSync/getAsync receive ctx first, enabling evaluators to use ctx.log, ctx.scope
+ * - forContext bootstraps the generated FeatureFlagEvaluator class (creates per-span wrapper)
+ * - Generated class has typed getters (ff.darkMode) and calls this.getSync(ctx, flag)
+ */
+export class InMemoryFlagEvaluator {
+    flags = {};
+    ffSchema;
+    constructor(ffSchema, initialFlags = {}) {
+        this.ffSchema = ffSchema;
+        this.flags = initialFlags;
+    }
+    /**
+     * Get flag value synchronously.
+     * Simple evaluator ignores ctx - just returns stored value.
+     * Advanced evaluators can use ctx.log, ctx.span, ctx.scope, etc.
+     */
+    getSync(_ctx, flag) {
+        return this.flags[flag] ?? null;
+    }
+    /**
+     * Get flag value asynchronously.
+     * Simple evaluator ignores ctx - just returns stored value.
+     * Advanced evaluators can use ctx.log, ctx.span for tracing external calls.
+     */
+    async getAsync(_ctx, flag) {
+        return this.flags[flag] ?? null;
+    }
+    setFlag(flag, value) {
+        this.flags[flag] = value;
+    }
+    /**
+     * Create span-bound FeatureFlagEvaluator with typed getters.
+     *
+     * Returns a per-span wrapper that holds ctx reference and reuses this evaluator.
+     * The generated class has typed getters (ff.darkMode) and calls this.getSync(ctx, flag).
+     */
+    forContext(ctx) {
+        return createFeatureFlagEvaluator(this.ffSchema, ctx, this);
+    }
+}

package/dist/lib/schema/extend.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Schema extension utilities for composing tag attribute schemas
+ *
+ * This enables building complex schemas from smaller, reusable pieces:
+ * - Base attributes (requestId, userId, etc.)
+ * - HTTP-specific attributes (httpStatus, httpMethod, etc.)
+ * - Database-specific attributes (dbQuery, dbDuration, etc.)
+ * - Custom domain attributes
+ */
+import { LogSchema } from './LogSchema.js';
+import type { SchemaFields } from './types.js';
+export declare function extendSchema<T extends SchemaFields, U extends SchemaFields>(base: LogSchema<T>, extension: U): LogSchema<T & U>;
+export declare function extendSchema<T extends SchemaFields, U extends SchemaFields>(base: T, extension: U): T & U;
+//# sourceMappingURL=extend.d.ts.map

package/dist/lib/schema/extend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/extend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,YAAY,EACzE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,EAClB,SAAS,EAAE,CAAC,GACX,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACpB,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC"}