@smoothbricks/lmao 0.1.0

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

@@ -0,0 +1,62 @@
+/**
+ * LogSchema class for logging-specific schema functionality
+ *
+ * Extends ColumnSchema from arrow-builder with logging-specific features:
+ * - Schema extension with reserved name validation
+ * - Integration with lmao's logging system
+ *
+ * The base ColumnSchema provides generic cached field access.
+ * LogSchema adds logging-specific extension capabilities.
+ */
+import { ColumnSchema } from '@smoothbricks/arrow-builder';
+import type { SchemaFields } from './types.js';
+/**
+ * LogSchema class - extends ColumnSchema with logging-specific features
+ *
+ * Provides all the generic schema functionality from ColumnSchema plus
+ * logging-specific extension with reserved name validation.
+ *
+ * @template T - The schema fields type (SchemaFields)
+ */
+export declare class LogSchema<T extends SchemaFields = SchemaFields> extends ColumnSchema<T> {
+    /**
+     * Assert that user-provided field names don't conflict with reserved names
+     * and don't start with underscore (reserved for system properties)
+     *
+     * @throws Error if any field name is reserved or starts with _
+     */
+    static assertUserFieldNames(fieldNames: readonly string[]): void;
+    /**
+     * Extend this schema with additional fields
+     *
+     * Creates a new LogSchema instance with merged fields.
+     * Validates that extension fields don't conflict with existing fields
+     * and don't use reserved names (logging-specific validation).
+     *
+     * @param extension - Additional schema fields to add
+     * @returns New LogSchema instance with merged fields
+     * @throws Error if field names conflict or reserved names are used
+     *
+     * @example
+     * ```typescript
+     * const base = new LogSchema({ requestId: S.category() });
+     * const extended = base.extend({ duration: S.number() });
+     * // extended.fields = { requestId: ..., duration: ... }
+     * ```
+     */
+    extend<U extends SchemaFields>(extension: U): LogSchema<T & U>;
+    /**
+     * Check if this is a LogSchema instance
+     *
+     * Used for type guards and instanceof checks
+     */
+    static isLogSchema(value: unknown): value is LogSchema;
+}
+/**
+ * Type guard to check if a value is a LogSchema instance
+ *
+ * @param value - Value to check
+ * @returns True if value is a LogSchema instance
+ */
+export declare function isLogSchema(value: unknown): value is LogSchema;
+//# sourceMappingURL=LogSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LogSchema.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/LogSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA6C/C;;;;;;;GAOG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IACnF;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAchE;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,CAAC,SAAS,YAAY,EAAE,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC;IA8B9D;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS;CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D"}

package/dist/lib/schema/LogSchema.js

@@ -0,0 +1,134 @@
+/**
+ * LogSchema class for logging-specific schema functionality
+ *
+ * Extends ColumnSchema from arrow-builder with logging-specific features:
+ * - Schema extension with reserved name validation
+ * - Integration with lmao's logging system
+ *
+ * The base ColumnSchema provides generic cached field access.
+ * LogSchema adds logging-specific extension capabilities.
+ */
+import { ColumnSchema } from '@smoothbricks/arrow-builder';
+/**
+ * Reserved method names that cannot be used as attribute names
+ *
+ * These names are reserved to prevent conflicts or confusion:
+ * - Technically conflicting: Names that would shadow actual methods/properties
+ *   on TagWriter, SpanLogger, FluentLogEntry, or result objects
+ * - Confusing: Names that would create confusing code patterns even though
+ *   they don't technically conflict (e.g., ctx.tag.tag() or ctx.scope.scope)
+ */
+const RESERVED_NAMES = new Set([
+    // Technically conflicting - methods on TagWriter/FluentLogEntry/result objects
+    'with', // Used on TagWriter, FluentLogEntry, Ok, Err
+    'message', // Used on Ok, Err
+    // Technically conflicting - log level methods on SpanLogger
+    'info', // ctx.log.info()
+    'debug', // ctx.log.debug()
+    'warn', // ctx.log.warn()
+    'error', // ctx.log.error()
+    'trace', // ctx.log.trace()
+    // Internal SpanLogger methods (prefixed with _ but included for completeness)
+    '_nextRow', // Internal row advancement
+    '_buffer', // Internal buffer reference
+    '_writeIndex', // Internal write position
+    '_getNextBuffer', // Internal buffer chaining
+    '_setScope', // Internal scope setter
+    '_prefillScopedAttributes', // Internal scope prefill
+    // Internal FF logging methods (called by evaluator, not on public type)
+    'ffAccess', // Feature flag access logging
+    'ffUsage', // Feature flag usage logging
+    // Confusing - properties on SpanContext (not technically conflicting)
+    'tag', // ctx.tag is TagWriter; ctx.tag.tag() would be confusing
+    'scope', // ctx.scope is readonly; ctx.scope.scope would be confusing
+    // Confusing - methods on SpanContext (not technically conflicting)
+    'ok', // ctx.ok() is method; ctx.tag.ok() or ctx.ok(result).ok() would be confusing
+    'err', // ctx.err() is method; ctx.tag.err() or ctx.err(code, details).err() would be confusing
+    'span', // ctx.span() is method; ctx.tag.span() would be confusing
+]);
+/**
+ * LogSchema class - extends ColumnSchema with logging-specific features
+ *
+ * Provides all the generic schema functionality from ColumnSchema plus
+ * logging-specific extension with reserved name validation.
+ *
+ * @template T - The schema fields type (SchemaFields)
+ */
+export class LogSchema extends ColumnSchema {
+    /**
+     * Assert that user-provided field names don't conflict with reserved names
+     * and don't start with underscore (reserved for system properties)
+     *
+     * @throws Error if any field name is reserved or starts with _
+     */
+    static assertUserFieldNames(fieldNames) {
+        for (const name of fieldNames) {
+            if (name.startsWith('_')) {
+                throw new Error(`Field name '${name}' cannot start with '_' - this prefix is reserved for system properties`);
+            }
+            if (RESERVED_NAMES.has(name)) {
+                throw new Error(`Attribute name '${name}' is reserved and cannot be used. ` +
+                    `Reserved names: ${Array.from(RESERVED_NAMES).join(', ')}`);
+            }
+        }
+    }
+    /**
+     * Extend this schema with additional fields
+     *
+     * Creates a new LogSchema instance with merged fields.
+     * Validates that extension fields don't conflict with existing fields
+     * and don't use reserved names (logging-specific validation).
+     *
+     * @param extension - Additional schema fields to add
+     * @returns New LogSchema instance with merged fields
+     * @throws Error if field names conflict or reserved names are used
+     *
+     * @example
+     * ```typescript
+     * const base = new LogSchema({ requestId: S.category() });
+     * const extended = base.extend({ duration: S.number() });
+     * // extended.fields = { requestId: ..., duration: ... }
+     * ```
+     */
+    extend(extension) {
+        // Check for field name conflicts
+        const extensionKeys = Object.keys(extension);
+        for (const key of extensionKeys) {
+            if (this._columnNames.includes(key)) {
+                throw new Error(`Schema conflict: attribute '${key}' already exists in base schema. ` +
+                    `Base schema has: ${this._columnNames.join(', ')}`);
+            }
+        }
+        // Assert extension doesn't use reserved names (logging-specific)
+        LogSchema.assertUserFieldNames(extensionKeys);
+        // Perform shallow merge
+        // Create merged via explicit property assignment to preserve property order for V8 hidden class stability
+        const merged = Object.create(null);
+        for (const key of this._columnNames) {
+            // Use prototypeless object for stable prototype, prevents hidden class deopt
+            merged[key] = this.fields[key];
+        }
+        for (const key of extensionKeys) {
+            merged[key] = extension[key];
+        }
+        // Return new LogSchema instance
+        return new LogSchema(merged);
+    }
+    /**
+     * Check if this is a LogSchema instance
+     *
+     * Used for type guards and instanceof checks
+     */
+    static isLogSchema(value) {
+        return value instanceof LogSchema;
+    }
+}
+/**
+ * Type guard to check if a value is a LogSchema instance
+ *
+ * @param value - Value to check
+ * @returns True if value is a LogSchema instance
+ */
+export function isLogSchema(value) {
+    return LogSchema.isLogSchema(value);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Schema builder for lmao - extends arrow-builder's schema builder with feature flags, masking, and binary sugar
+ *
+ * This module re-exports the S object from arrow-builder and adds:
+ * - Feature flag support via .default().sync()/.async() pattern
+ * - Masking transformations for sensitive data
+ * - S.unknown() and S.object<T>() sugar for msgpack-encoded binary columns
+ * - S.binary() passthrough to arrow-builder's S.binary()
+ */
+import type { SchemaBuilder } from './types.js';
+export declare const S: SchemaBuilder;
+//# sourceMappingURL=builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,OAAO,KAAK,EAAiD,aAAa,EAAuB,MAAM,YAAY,CAAC;AAoLpH,eAAO,MAAM,CAAC,eAAoB,CAAC"}

package/dist/lib/schema/builder.js

@@ -0,0 +1,169 @@
+/**
+ * Schema builder for lmao - extends arrow-builder's schema builder with feature flags, masking, and binary sugar
+ *
+ * This module re-exports the S object from arrow-builder and adds:
+ * - Feature flag support via .default().sync()/.async() pattern
+ * - Masking transformations for sensitive data
+ * - S.unknown() and S.object<T>() sugar for msgpack-encoded binary columns
+ * - S.binary() passthrough to arrow-builder's S.binary()
+ */
+import { encode } from '@msgpack/msgpack';
+import { S as ArrowS, } from '@smoothbricks/arrow-builder';
+/**
+ * Msgpack encoder singleton -- per-value, synchronous.
+ * Encodes at flush time (cold path), not on the hot write path.
+ * @msgpack/msgpack already handles most types; functions/symbols become undefined (dropped silently).
+ *
+ * Both wrap @msgpack/msgpack's encode(). This encoder is private to the schema builder;
+ */
+const msgpackEncoder = {
+    encode(value) {
+        return encode(value);
+    },
+};
+function createSchemaWithFlagBuilder(schema) {
+    const schemaWithBuilder = Object.assign(schema, {
+        default(defaultValue) {
+            return {
+                sync() {
+                    return {
+                        schema,
+                        defaultValue,
+                        evaluationType: 'sync',
+                    };
+                },
+                async() {
+                    return {
+                        schema,
+                        defaultValue,
+                        evaluationType: 'async',
+                    };
+                },
+            };
+        },
+    });
+    return schemaWithBuilder;
+}
+/**
+ * Schema builder that wraps arrow-builder's S with feature flag support
+ *
+ * STRING TYPE SYSTEM (See specs/lmao/01a_trace_schema_system.md):
+ * Three distinct string types, each with different storage strategies:
+ * - S.enum(['A', 'B', 'C']) - Known values at compile time (Uint8Array, 1 byte)
+ * - S.category() - Repeated values (raw string storage, dictionary built at Arrow conversion)
+ * - S.text() - Unique values (no dictionary overhead)
+ */
+const schemaBuilderImpl = {
+    /**
+     * Create number schema
+     *
+     * Usage:
+     * - S.number() - any number for tag attributes
+     * - S.number().default(0).sync() - feature flag
+     */
+    number: () => {
+        const schema = ArrowS.number();
+        return createSchemaWithFlagBuilder(schema);
+    },
+    /**
+     * Create boolean schema
+     *
+     * Usage:
+     * - S.boolean() - for tag attributes
+     * - S.boolean().default(false).sync() - feature flag
+     */
+    boolean: () => {
+        const schema = ArrowS.boolean();
+        return createSchemaWithFlagBuilder(schema);
+    },
+    /**
+     * Wrap schema to make it optional
+     *
+     * Usage:
+     * - SchemaBuilder.optional(SchemaBuilder.string()) - string | undefined
+     */
+    optional: (schema) => {
+        return ArrowS.optional(schema);
+    },
+    /**
+     * Create union of multiple schemas
+     *
+     * Usage:
+     * - SchemaBuilder.union([SchemaBuilder.string(), SchemaBuilder.number()]) - string | number
+     */
+    union: (schemas) => {
+        return ArrowS.union(schemas);
+    },
+    /**
+     * Enum - Known values at compile time
+     *
+     * Storage: Uint8Array (1 byte) with compile-time mapping
+     * Arrow: Dictionary with pre-defined values (UTF-8 pre-computed at definition time)
+     * Use for: Operations, HTTP methods, entry types, status enums
+     *
+     * Usage:
+     * - S.enum(['CREATE', 'READ', 'UPDATE', 'DELETE']) - for tag attributes
+     * - S.enum(['dev', 'staging', 'prod']).default('dev').sync() - feature flag
+     */
+    enum: (values) => {
+        const schema = ArrowS.enum(values);
+        return createSchemaWithFlagBuilder(schema);
+    },
+    /**
+     * Category - Values that often repeat (limited cardinality)
+     *
+     * Storage: Raw strings (no hot-path interning)
+     * Arrow: Dictionary built dynamically from values at Arrow conversion
+     * Use for: userIds, sessionIds, moduleNames, spanNames, table names
+     */
+    category: () => {
+        const schema = ArrowS.category();
+        return createSchemaWithFlagBuilder(schema);
+    },
+    /**
+     * Text - Unique values that rarely repeat
+     *
+     * Storage: Raw strings without interning
+     * Arrow: Plain string column (no dictionary overhead)
+     * Use for: Unique error messages, URLs, request bodies, masked queries
+     */
+    text: () => {
+        const schema = ArrowS.text();
+        return createSchemaWithFlagBuilder(schema);
+    },
+    /**
+     * Binary - Raw bytes or encoder-wrapped values
+     *
+     * Passthrough to arrow-builder's S.binary().
+     * Without encoder: accepts Uint8Array (raw binary).
+     * With encoder: accepts any value T (encoded to bytes at flush time).
+     */
+    binary: ((options) => {
+        if (options?.encoder) {
+            return ArrowS.binary(options);
+        }
+        return ArrowS.binary();
+    }),
+    /**
+     * Unknown - accepts any value, msgpack-encoded at flush time
+     *
+     * Sugar for S.binary({ encoder: msgpackEncoder }).
+     * Use for: arbitrary objects, request bodies, error context, unknown-shape data.
+     * Hot path stores frozen object reference; flush path encodes via @msgpack/msgpack.
+     */
+    unknown: () => {
+        return ArrowS.binary({ encoder: msgpackEncoder });
+    },
+    /**
+     * Object<T> - typed variant of unknown, same underlying binary storage with msgpack encoding
+     *
+     * TypeScript enforces shape at compile time; no runtime validation on hot path.
+     * Sugar for S.binary<T>({ encoder: msgpackEncoder }).
+     */
+    object: () => {
+        return ArrowS.binary({ encoder: msgpackEncoder });
+    },
+};
+// Export as S for convenience
+// Note: The SchemaBuilder type is exported from types.ts
+export const S = schemaBuilderImpl;

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

@@ -0,0 +1,60 @@
+import type { Output } from '@smoothbricks/arrow-builder';
+import type { FeatureFlagDefinition } from './types.js';
+/**
+ * Feature flag schema with sync/async markers
+ */
+export interface FeatureFlagSchema {
+    [key: string]: FeatureFlagDefinition<string | number | boolean>;
+}
+type DefinedFeatureFlags<T extends FeatureFlagSchema> = {
+    schema: T;
+    syncFlags: SyncFlagKeys<T>[];
+    asyncFlags: AsyncFlagKeys<T>[];
+    readonly type?: InferFeatureFlags<T>;
+};
+/**
+ * Define feature flags with type-safe access patterns
+ *
+ * @param schema - Object mapping flag names to flag definitions
+ * @returns Feature flag definition object for use with evaluator
+ */
+export declare function defineFeatureFlags<T extends FeatureFlagSchema>(schema: T): DefinedFeatureFlags<T>;
+/**
+ * Extract sync flag keys
+ */
+export type SyncFlagKeys<T extends FeatureFlagSchema> = {
+    [K in keyof T]: T[K]['evaluationType'] extends 'sync' ? K : never;
+}[keyof T];
+/**
+ * Extract async flag keys
+ */
+export type AsyncFlagKeys<T extends FeatureFlagSchema> = {
+    [K in keyof T]: T[K]['evaluationType'] extends 'async' ? K : never;
+}[keyof T];
+/**
+ * Infer TypeScript types from feature flag schema
+ */
+export type InferFeatureFlags<T extends FeatureFlagSchema> = {
+    [K in keyof T]: Output<T[K]['schema']>;
+};
+/**
+ * Evaluation context for feature flag decisions
+ */
+export interface EvaluationContext {
+    userId?: string;
+    requestId?: string;
+    userPlan?: string;
+    region?: string;
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Usage tracking context for A/B testing analytics
+ */
+export interface UsageContext {
+    action?: string;
+    outcome?: 'success' | 'failure';
+    value?: number;
+    metadata?: Record<string, string | number | boolean>;
+}
+export {};
+//# sourceMappingURL=defineFeatureFlags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defineFeatureFlags.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/defineFeatureFlags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACjE;AAED,KAAK,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,IAAI;IACtD,MAAM,EAAE,CAAC,CAAC;IACV,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;CACtC,CAAC;AAUF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,iBAAiB,EAAE,MAAM,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAiBjG;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,iBAAiB,IAAI;KACrD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK;CAClE,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,iBAAiB,IAAI;KACtD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,OAAO,GAAG,CAAC,GAAG,KAAK;CACnE,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,iBAAiB,IAAI;KAC1D,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACtD"}

package/dist/lib/schema/defineFeatureFlags.js

@@ -0,0 +1,29 @@
+function isSyncFlagKey(schema, key) {
+    return schema[key].evaluationType === 'sync';
+}
+function isAsyncFlagKey(schema, key) {
+    return schema[key].evaluationType === 'async';
+}
+/**
+ * Define feature flags with type-safe access patterns
+ *
+ * @param schema - Object mapping flag names to flag definitions
+ * @returns Feature flag definition object for use with evaluator
+ */
+export function defineFeatureFlags(schema) {
+    const syncFlags = [];
+    const asyncFlags = [];
+    for (const key in schema) {
+        if (isSyncFlagKey(schema, key)) {
+            syncFlags.push(key);
+        }
+        else if (isAsyncFlagKey(schema, key)) {
+            asyncFlags.push(key);
+        }
+    }
+    return {
+        schema,
+        syncFlags,
+        asyncFlags,
+    };
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Define log schema with runtime validation and type inference
+ *
+ * This module leverages __schema_type metadata on schema objects for:
+ * - Runtime validation via schema-type dispatch
+ * - Automatic TypeScript inference
+ * - Schema transformations (masking)
+ * - Extension composition
+ */
+import { LogSchema } from './LogSchema.js';
+import type { InferSchema, SchemaFields } from './types.js';
+/**
+ * Brand symbol for DefinedLogSchema - used to detect this type in conditionals.
+ * Must be exported so types.ts can import it for ExtractOriginalSchema.
+ */
+export declare const DEFINED_LOG_SCHEMA_BRAND: unique symbol;
+/**
+ * Define log schema with runtime validation and type inference
+ *
+ * Example:
+ * ```typescript
+ * const schema = defineLogSchema({
+ *   requestId: S.category(),
+ *   userId: S.optional(S.category()),
+ *   httpStatus: S.number(),
+ *   operation: S.enum(['SELECT', 'INSERT', 'UPDATE'])
+ * });
+ *
+ * // Validate data
+ * const result = schema.validate({
+ *   requestId: 'req-123',
+ *   userId: 'user-456',
+ *   httpStatus: 200,
+ *   operation: 'SELECT'
+ * });
+ * ```
+ *
+ * @param schema - Object mapping field names to schema objects
+ * @returns Extended schema with validation and extension methods
+ */
+/**
+ * DefinedLogSchema type - result of defineLogSchema()
+ *
+ * Includes:
+ * - All original schema fields (T)
+ * - Extension methods (extend)
+ * - Validation methods (validate, parse, safeParse)
+ * - LogSchema methods (fieldEntries, fieldCount, fieldNames, fields)
+ * - Brand marker for type detection in InferSchema
+ */
+export type DefinedLogSchema<T extends SchemaFields> = LogSchema<T> & {
+    /** Brand marker - never actually set, only for type discrimination */
+    readonly [DEFINED_LOG_SCHEMA_BRAND]?: T;
+};
+type SafeParseResult<T extends SchemaFields> = {
+    success: true;
+    value: InferSchema<T>;
+} | {
+    success: false;
+    error: Error;
+};
+/**
+ * Options for defineLogSchema
+ */
+export interface DefineLogSchemaOptions {
+    /**
+     * Skip validation of reserved names.
+     * Only used internally for defining system schema columns.
+     * @internal
+     */
+    _skipReservedNameValidation?: boolean;
+}
+/**
+ * LogSchema with validation methods added by defineLogSchema.
+ * These methods are added via Object.assign at runtime.
+ */
+export type ValidatedLogSchema<T extends SchemaFields> = LogSchema<T> & {
+    /** Validate data and throw on error */
+    validate(data: unknown): InferSchema<T>;
+    /** Validate data and return null on error */
+    parse(data: unknown): InferSchema<T> | null;
+    /** Safe parse with detailed error information */
+    safeParse(data: unknown): SafeParseResult<T>;
+};
+export declare function defineLogSchema<T extends SchemaFields>(schema: T, options?: DefineLogSchemaOptions): ValidatedLogSchema<T>;
+export {};
+//# sourceMappingURL=defineLogSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defineLogSchema.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/defineLogSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5D;;;GAGG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,wBAAwB,EAAE,OAAO,MAAM,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,YAAY,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG;IACpE,sEAAsE;IACtE,QAAQ,CAAC,CAAC,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC;CACzC,CAAC;AAEF,KAAK,eAAe,CAAC,CAAC,SAAS,YAAY,IACvC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;CAAE,GACxC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,YAAY,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG;IACtE,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IACxC,6CAA6C;IAC7C,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC5C,iDAAiD;IACjD,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;CAC9C,CAAC;AAgJF,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,sBAAsB,GAC/B,kBAAkB,CAAC,CAAC,CAAC,CAwDvB"}