@smoothbricks/lmao 0.1.0

package/src/lib/opContext/defineOp.ts

@@ -0,0 +1,281 @@
+/**
+ * Op Definition Functions
+ *
+ * Factory functions for defining Ops and OpGroups. These are used internally
+ * by OpContextFactory to create type-safe Op definitions.
+ *
+ * @module opContext/defineOp
+ */
+
+import { intern, PreEncodedEntry } from '@smoothbricks/arrow-builder';
+import { Op as OpClass } from '../op.js';
+import { getSpanBufferClass } from '../spanBuffer.js';
+import type { OpGroup, OpGroupOps } from './opGroupTypes.js';
+import type { Op, OpFn, OpMetadata, OpsFromRecord } from './opTypes.js';
+import type { OpContext } from './types.js';
+
+// =============================================================================
+// METADATA HELPERS
+// =============================================================================
+
+/**
+ * Create OpMetadata with pre-encoded entries for Arrow dictionary building.
+ * Uses global interner to deduplicate UTF-8 bytes across all Ops with same strings.
+ */
+export function createOpMetadata(
+  name: string,
+  package_name: string,
+  package_file: string,
+  git_sha: string,
+  line: number,
+): OpMetadata {
+  return {
+    name,
+    package_name,
+    package_file,
+    git_sha,
+    line,
+    // Use global interner for deduplication - same package_name across Ops shares UTF-8 bytes
+    package_name_entry: new PreEncodedEntry(package_name, intern(package_name)),
+    package_file_entry: new PreEncodedEntry(package_file, intern(package_file)),
+    git_sha_entry: new PreEncodedEntry(git_sha, intern(git_sha)),
+  };
+}
+
+// =============================================================================
+// DEFAULT METADATA
+// =============================================================================
+
+/**
+ * Default metadata values for Ops when not injected by transformer.
+ * These are placeholder values that will be replaced at compile time.
+ */
+export const DEFAULT_METADATA: OpMetadata = createOpMetadata('unknown', 'unknown', 'unknown', 'unknown', 0);
+
+// =============================================================================
+// STACK TRACE METADATA EXTRACTION
+// =============================================================================
+
+/**
+ * Extracts metadata from stack trace when transformer is not installed.
+ * Provides useful debugging info (file path, line number) even without build-time injection.
+ *
+ * Stack frame format varies by runtime:
+ * - V8 (Node/Chrome): "    at functionName (file:///path/to/file.ts:10:5)"
+ * - V8 anonymous:     "    at file:///path/to/file.ts:10:5"
+ * - JSC (Safari):     "functionName@file:///path/to/file.ts:10:5"
+ *
+ * @param skipFrames - Number of stack frames to skip (to get caller's location)
+ * @returns OpMetadata with extracted file path and line number
+ */
+export function extractMetadataFromStack(skipFrames = 2): OpMetadata {
+  const err = new Error();
+  const stack = err.stack;
+
+  if (!stack) {
+    return DEFAULT_METADATA;
+  }
+
+  const lines = stack.split('\n');
+
+  // Skip "Error" line + specified frames to get to caller
+  // Frame 0: Error
+  // Frame 1: extractMetadataFromStack
+  // Frame 2: defineOpImpl (or caller)
+  // Frame 3: actual defineOp call site
+  const targetFrame = lines[skipFrames + 1];
+
+  if (!targetFrame) {
+    return DEFAULT_METADATA;
+  }
+
+  // Try V8 format: "    at functionName (file:///path/to/file.ts:10:5)"
+  // or anonymous: "    at file:///path/to/file.ts:10:5"
+  let match = targetFrame.match(/at\s+(?:.*?\s+\()?(.+?):(\d+):\d+\)?$/);
+
+  // Try JSC format: "functionName@file:///path/to/file.ts:10:5"
+  if (!match) {
+    match = targetFrame.match(/@(.+?):(\d+):\d+$/);
+  }
+
+  if (!match) {
+    return DEFAULT_METADATA;
+  }
+
+  let filePath = match[1];
+  const lineNumber = Number.parseInt(match[2], 10);
+
+  // Clean up file:// protocol if present
+  if (filePath.startsWith('file://')) {
+    filePath = filePath.slice(7);
+  }
+
+  // Extract package name from path (last directory component before src/)
+  // e.g., "/path/to/my-package/src/ops.ts" -> "my-package"
+  let packageName = 'unknown';
+  const srcIndex = filePath.lastIndexOf('/src/');
+  if (srcIndex > 0) {
+    const beforeSrc = filePath.slice(0, srcIndex);
+    const lastSlash = beforeSrc.lastIndexOf('/');
+    if (lastSlash >= 0) {
+      packageName = beforeSrc.slice(lastSlash + 1);
+    }
+  } else {
+    // Fallback: use filename without extension
+    const lastSlash = filePath.lastIndexOf('/');
+    const fileName = lastSlash >= 0 ? filePath.slice(lastSlash + 1) : filePath;
+    const dotIndex = fileName.lastIndexOf('.');
+    packageName = dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
+  }
+
+  return createOpMetadata('unknown', packageName, filePath, 'runtime', lineNumber);
+}
+
+// =============================================================================
+// FACTORY CONFIG
+// =============================================================================
+
+/**
+ * Configuration using OpContext bundle.
+ * Simplifies factory config by carrying all context types in one parameter.
+ */
+interface DefineOpFactoryConfig<Ctx extends OpContext> {
+  readonly logSchema: Ctx['logSchema'];
+  readonly flags: Ctx['flags'];
+  /** WHY: threaded to Op._opContextBinding so downstream can extract schema */
+  readonly opContextBinding?: import('./types.js').OpContextBinding;
+}
+
+/**
+ * Factory function type for creating OpGroups.
+ * Used by createDefineOps to delegate OpGroup creation.
+ */
+type CreateOpGroupFn<Ctx extends OpContext> = <Ops extends OpGroupOps<Ctx>>(
+  logSchema: Ctx['logSchema'],
+  flags: Ctx['flags'],
+  ops: Ops,
+) => OpGroup<Ctx, Ops>;
+
+// =============================================================================
+// CREATE DEFINE OP
+// =============================================================================
+
+/**
+ * Creates a defineOp function bound to a specific factory config.
+ *
+ * The returned function creates Op objects with:
+ * - metadata: includes name + merged with defaults
+ * - SpanBufferClass: from getSpanBufferClass(logSchema) - has static schema + stats
+ * - fn(ctx, ...args): the user function to execute
+ * - remappedViewClass: undefined for original ops (set by .prefix() method)
+ *
+ * @template Ctx - Bundled OpContext (logSchema, flags, deps, userCtx)
+ * @param factoryConfig - Configuration containing logSchema and flags
+ * @returns A defineOp function for creating Op instances
+ */
+export function createDefineOp<Ctx extends OpContext>(
+  factoryConfig: DefineOpFactoryConfig<Ctx>,
+): <Args extends unknown[], S, E>(
+  name: string,
+  fn: OpFn<Ctx, Args, S, E>,
+  metadata?: Partial<OpMetadata>,
+) => Op<Ctx, Args, S, E> {
+  // Why get class from schema: Class has static schema + stats shared by all instances
+  const SpanBufferClass = getSpanBufferClass(factoryConfig.logSchema);
+
+  return function defineOpImpl<Args extends unknown[], S, E>(
+    name: string,
+    fn: OpFn<Ctx, Args, S, E>,
+    metadata?: Partial<OpMetadata>,
+  ): Op<Ctx, Args, S, E> {
+    // When transformer is not installed, extract metadata from stack trace
+    // This provides useful file/line info for debugging even without build-time injection
+    // skipFrames=3: Error -> extractMetadataFromStack -> defineOpImpl -> caller
+    const baseMetadata = metadata?.package_file ? DEFAULT_METADATA : extractMetadataFromStack(3);
+    // Use name from: 1) explicit metadata.name (transformer), 2) defineOp('name', fn), 3) baseMetadata
+    const finalMetadata = { ...baseMetadata, ...metadata, name: metadata?.name ?? name };
+
+    // Use the Op class which handles all span/buffer management:
+    // - Creates SpanBuffer for the op
+    // - Registers child buffers with parent
+    // - Sets _opMetadata and _callsiteMetadata
+    // - Writes span-start/span-ok/span-err entries
+    // - Handles exceptions with span-exception
+    // Why SpanBufferClass: All ops from same defineOpContext share this class for stats coordination
+    // Why undefined for remappedViewClass: Only prefixed ops need remapping - set by .prefix() method
+    return new OpClass(finalMetadata, SpanBufferClass, fn, undefined, factoryConfig.opContextBinding);
+  };
+}
+
+// =============================================================================
+// CREATE DEFINE OPS
+// =============================================================================
+
+/**
+ * Type guard to check if a definition is an existing Op instance.
+ */
+function isOp<Ctx extends OpContext>(def: unknown): def is Op<Ctx, unknown[], unknown, unknown> {
+  return def instanceof OpClass;
+}
+
+function hasAllDefinedOps<
+  Ctx extends OpContext,
+  Defs extends Record<string, Op<Ctx, unknown[], unknown, unknown> | OpFn<Ctx, unknown[], unknown, unknown>>,
+>(definitions: Defs, ops: Record<string, Op<Ctx, unknown[], unknown, unknown>>): ops is OpsFromRecord<Ctx, Defs> {
+  for (const name in definitions) {
+    if (!(name in ops)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Creates a defineOps function bound to a specific factory config.
+ *
+ * The returned function:
+ * - Iterates over Object.entries(definitions)
+ * - For each [name, def]:
+ *   - If def is an Op instance, use it as-is
+ *   - Else wrap with defineOpImpl(name, def)
+ * - Stores all ops in a record
+ * - Creates OpGroup using createOpGroup(logSchema, flags, ops)
+ * - Returns Object.assign(opGroup, ops) to get both OpGroup methods and individual ops
+ *
+ * @template Ctx - Bundled OpContext (logSchema, flags, deps, userCtx)
+ * @param factoryConfig - Configuration containing logSchema and flags
+ * @param createOpGroup - Factory function for creating OpGroups
+ * @returns A defineOps function for creating OpGroups
+ */
+export function createDefineOps<Ctx extends OpContext>(
+  factoryConfig: DefineOpFactoryConfig<Ctx>,
+  createOpGroup: CreateOpGroupFn<Ctx>,
+): <Defs extends Record<string, Op<Ctx, unknown[], unknown, unknown> | OpFn<Ctx, unknown[], unknown, unknown>>>(
+  definitions: Defs & ThisType<OpsFromRecord<Ctx, Defs>>,
+) => OpGroup<Ctx, OpsFromRecord<Ctx, Defs>> {
+  // Get the defineOp function for wrapping raw functions
+  const defineOp = createDefineOp<Ctx>(factoryConfig);
+
+  return function defineOpsImpl<
+    Defs extends Record<string, Op<Ctx, unknown[], unknown, unknown> | OpFn<Ctx, unknown[], unknown, unknown>>,
+  >(definitions: Defs & ThisType<OpsFromRecord<Ctx, Defs>>): OpGroup<Ctx, OpsFromRecord<Ctx, Defs>> {
+    // Build the ops record by processing each definition.
+    // Keep the runtime container broad, then narrow once we've populated every key.
+    const ops: Record<string, Op<Ctx, unknown[], unknown, unknown>> = {};
+
+    for (const name in definitions) {
+      const def = definitions[name];
+      ops[name] = isOp<Ctx>(def) ? def : defineOp(name, def);
+    }
+
+    if (!hasAllDefinedOps(definitions, ops)) {
+      throw new Error('defineOps failed to normalize all op definitions');
+    }
+
+    // Create the OpGroup
+    const opGroup = createOpGroup(factoryConfig.logSchema, factoryConfig.flags, ops);
+
+    // Return OpGroup merged with individual ops for direct access
+    return Object.assign(opGroup, ops);
+  };
+}

package/src/lib/opContext/featureFlagTypes.ts

@@ -0,0 +1,54 @@
+/**
+ * Feature Flag Types for Op-Centric API
+ *
+ * This module contains type definitions for feature flags used in the Op-centric API.
+ * Feature flags allow for runtime toggling of functionality with type-safe evaluation.
+ *
+ * Key concepts:
+ * - FeatureFlagSchema: Defines what flags exist and their types
+ * - BoundFeatureFlags: Typed accessor for flag values bound to a span context
+ *
+ * For the FlagEvaluator interface (getSync/getAsync/forContext), see:
+ * - packages/lmao/src/lib/schema/evaluator.ts
+ */
+
+import type { FluentLogEntry } from '../codegen/spanLoggerGenerator.js';
+import type { LogSchema } from '../schema/LogSchema.js';
+import type { FeatureFlagDefinition } from '../schema/types.js';
+
+// =============================================================================
+// FEATURE FLAG TYPES
+// =============================================================================
+
+/**
+ * Feature flag schema - defines what flags are available and their types
+ */
+export interface FeatureFlagSchema {
+  [key: string]: FeatureFlagDefinition<string | number | boolean>;
+}
+
+/**
+ * Feature flag accessor bound to a span context
+ * Provides typed getters for each defined flag
+ *
+ * Access patterns:
+ * - Sync flags: `ctx.ff.myFlag` returns `{ value: T, track(context?): FluentLogEntry } | undefined`
+ * - Async flags: `await ctx.ff.get('myFlag')` returns `{ value: T, track(context?): FluentLogEntry } | undefined`
+ *
+ * Returns `undefined` when flag is false/disabled.
+ * Returns wrapper object when flag is truthy/enabled, with `.track()` for usage analytics.
+ */
+export type BoundFeatureFlags<FF extends FeatureFlagSchema> = {
+  readonly [K in keyof FF]: FF[K] extends FeatureFlagDefinition<infer V, 'sync'>
+    ? { value: V; track(context?: { action?: string; outcome?: string }): FluentLogEntry<LogSchema> } | undefined
+    : FF[K] extends FeatureFlagDefinition<infer V, 'async'>
+      ? { value: V; track(context?: { action?: string; outcome?: string }): FluentLogEntry<LogSchema> } | undefined
+      : never;
+} & {
+  /** Get async flag value. Returns undefined when false, FlagContext when truthy. */
+  get(
+    flag: string,
+  ): Promise<
+    { value: unknown; track(context?: { action?: string; outcome?: string }): FluentLogEntry<LogSchema> } | undefined
+  >;
+};

package/src/lib/opContext/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Op-Centric API - Module Index
+ *
+ * Re-exports all types and implementation functions for the Op-centric API.
+ * Consumers should import from this file for a single entry point.
+ *
+ * @module opContext
+ */
+
+// Re-export implementation functions
+export { createOpGroup } from './createOpGroup.js';
+export { createDefineOp, createDefineOps, createOpMetadata, DEFAULT_METADATA } from './defineOp.js';
+// Re-export OpGroup types and helpers
+export * from './opGroupTypes.js';
+// Re-export all types from the hub
+export * from './types.js';

package/src/lib/opContext/opGroupTypes.ts

@@ -0,0 +1,342 @@
+/**
+ * OpGroup Types
+ *
+ * Type definitions for OpGroups - collections of Ops that can be mapped
+ * and wired as dependencies. These types enable:
+ * - Column mapping (prefix, rename, drop)
+ * - Schema contribution tracking
+ * - Type-safe dependency resolution
+ *
+ * Public interfaces (OpGroup, MappedOpGroup) hide internal properties from
+ * intellisense - users only see ops and methods they need.
+ * Internal interfaces (OpGroupInternal, MappedOpGroupInternal) expose all
+ * properties for library implementation.
+ *
+ * @module opContext/opGroupTypes
+ */
+
+import type { Op } from '../op.js';
+import type { LogSchema } from '../schema/LogSchema.js';
+import type { SchemaFields } from '../schema/types.js';
+import type { OpContext } from './types.js';
+
+// =============================================================================
+// COLUMN MAPPING TYPES
+// =============================================================================
+
+/**
+ * Column mapping for wiring OpGroups.
+ *
+ * Maps the library's column names to the app's column names:
+ * - `string` → map to that column name (must be type-compatible)
+ * - `null` → drop the column (library writes are ignored)
+ *
+ * @example
+ * ```typescript
+ * // Map query to shared column, rows to prefixed, drop internal column
+ * { query: 'query', rows: 'pg_rows', _internal: null }
+ * ```
+ */
+export type ColumnMapping<LibSchema extends SchemaFields = SchemaFields> = {
+  [K in keyof LibSchema]?: string | null;
+};
+
+/**
+ * Apply a prefix to all schema field names.
+ * `{ status: S.number() }` with prefix 'http' → `{ http_status: S.number() }`
+ */
+export type PrefixedSchema<T extends SchemaFields, P extends string> = {
+  [K in keyof T as `${P}_${K & string}`]: T[K];
+};
+
+/**
+ * Extract the schema fields from a LogSchema
+ */
+export type SchemaFieldsOf<T> = T extends LogSchema<infer Fields> ? Fields : never;
+
+/**
+ * Apply column mapping to schema.
+ * - Mapped columns get new names
+ * - Columns mapped to null are dropped
+ * - Unmapped columns keep original names (with prefix if using prefix())
+ */
+export type MappedSchema<T extends SchemaFields, M extends ColumnMapping<T>> = {
+  // For each key in mapping that maps to a string, use that string as the new key
+  [K in keyof T as M[K] extends string ? M[K] : M[K] extends null ? never : K]: T[K];
+};
+
+// =============================================================================
+// RESERVED OP NAMES
+// =============================================================================
+
+/**
+ * Reserved names that cannot be used as op names.
+ * These conflict with OpGroup methods or internal properties.
+ */
+export const RESERVED_OP_NAMES = ['prefix', 'mapColumns'] as const;
+
+/**
+ * Validate that an op name is allowed.
+ * Throws if the name is reserved or starts with underscore.
+ *
+ * @param name - The op name to validate
+ * @throws Error if name is invalid
+ */
+export function validateOpName(name: string): void {
+  if (name.startsWith('_')) {
+    throw new Error(
+      `Op name "${name}" cannot start with underscore (reserved for internal properties). ` +
+        `Consider using "${name.slice(1)}" instead.`,
+    );
+  }
+  if ((RESERVED_OP_NAMES as readonly string[]).includes(name)) {
+    throw new Error(
+      `Op name "${name}" is reserved (conflicts with OpGroup method). ` +
+        `Consider using a more descriptive name like "${name}Op" or "${name}Operation".`,
+    );
+  }
+}
+
+// =============================================================================
+// PUBLIC OP GROUP INTERFACES (visible to users in intellisense)
+// =============================================================================
+
+export type OpGroupOps<Ctx extends OpContext> = Record<string, Op<Ctx, unknown[], unknown, unknown>>;
+type NoOpMembers = Record<never, never>;
+
+/**
+ * A group of Ops that can be mapped and wired as a dependency.
+ *
+ * Created by defineOps() - represents a library's exported operations.
+ * Libraries declare their schema but don't know how the app will wire them.
+ *
+ * Note: Ops are accessed directly as properties (`.opName` not `.ops.opName`)
+ * for V8 hidden class optimization and cleaner API ergonomics.
+ *
+ * Internal properties (_logSchema, _flags) are hidden from intellisense
+ * but accessible at runtime for library implementation.
+ */
+interface OpGroupMethods<Ctx extends OpContext, Ops extends object> {
+  /**
+   * Apply a prefix to all schema columns.
+   *
+   * Shorthand for mapColumns where each column gets the prefix.
+   * E.g., `httpOps.prefix('http')` transforms 'status' -> 'http_status'
+   *
+   * The prefixed columns become part of the combined app schema:
+   * `appSchema & { http_status: S.number(), http_url: S.category() }`
+   *
+   * @param prefix - Prefix to apply to all schema columns
+   * @returns MappedOpGroup with prefixed schema contribution
+   */
+  prefix<P extends string>(prefix: P): MappedOpGroup<Ctx, PrefixedSchema<SchemaFieldsOf<Ctx['logSchema']>, P>, Ops>;
+
+  /**
+   * Map schema columns to different names in the app's schema.
+   *
+   * Use this for:
+   * - Deduplication: `{ query: 'query' }` - multiple libs share same column
+   * - Renaming: `{ rows: 'pg_row_count' }`
+   * - Dropping: `{ _internal: null }` - ignore library's internal column
+   * - Mixed: `{ query: 'query', rows: 'pg_rows', _debug: null }`
+   *
+   * Type-safety: Target columns must have compatible schema types.
+   *
+   * @param mapping - Maps library column names to app column names (or null to drop)
+   * @returns MappedOpGroup with mapped schema contribution
+   *
+   * @example
+   * ```typescript
+   * // Two DB libs share 'query' column, each has unique columns, drop debug
+   * deps: {
+   *   pg: postgresOps.mapColumns({ query: 'query', rows: 'pg_rows', _debug: null }),
+   *   mysql: mysqlOps.mapColumns({ query: 'query', duration: 'mysql_duration' }),
+   * }
+   * ```
+   */
+  mapColumns<M extends ColumnMapping<SchemaFieldsOf<Ctx['logSchema']>>>(
+    mapping: M,
+  ): MappedOpGroup<Ctx, MappedSchema<SchemaFieldsOf<Ctx['logSchema']>, M>, Ops>;
+}
+
+export type OpGroup<Ctx extends OpContext, Ops extends object = NoOpMembers> = OpGroupMethods<Ctx, Ops> & Ops;
+
+/**
+ * An OpGroup with column mapping applied.
+ *
+ * The mapping is used during wiring to create RemappedBufferView
+ * that translates the library's column writes to the app's column names.
+ *
+ * Note: Ops are accessed directly as properties (`.opName` not `.ops.opName`)
+ * for V8 hidden class optimization and cleaner API ergonomics.
+ *
+ * Internal properties (_logSchema, _flags, _contributedSchema, _columnMapping)
+ * are hidden from intellisense but accessible at runtime.
+ *
+ * @template Ctx - OpContext (bundled type with logSchema, flags, deps, userCtx)
+ * @template ContributedSchema - Schema fields this group contributes to app (after mapping)
+ */
+interface MappedOpGroupMethods<Ctx extends OpContext, ContributedSchema extends SchemaFields, Ops extends object> {
+  /** Chain with prefix (applies prefix to current mapping) */
+  prefix<P extends string>(prefix: P): MappedOpGroup<Ctx, PrefixedSchema<ContributedSchema, P>, Ops>;
+
+  /** Override/extend the mapping */
+  mapColumns<M extends ColumnMapping<ContributedSchema>>(
+    mapping: M,
+  ): MappedOpGroup<Ctx, MappedSchema<ContributedSchema, M>, Ops>;
+}
+
+export type MappedOpGroup<
+  Ctx extends OpContext,
+  ContributedSchema extends SchemaFields,
+  Ops extends object = NoOpMembers,
+> = MappedOpGroupMethods<Ctx, ContributedSchema, Ops> & Ops;
+
+// =============================================================================
+// INTERNAL OP GROUP INTERFACES (for library implementation)
+// =============================================================================
+
+/**
+ * Internal OpGroup interface with all properties exposed.
+ * Used by library implementation code that needs access to schema/flags.
+ *
+ * NOT exported from public API - use type assertion to access:
+ * `(opGroup as OpGroupInternal<Ctx>)._logSchema`
+ */
+export interface OpGroupInternal<Ctx extends OpContext, Ops extends object = NoOpMembers>
+  extends OpGroupMethods<Ctx, Ops> {
+  /** The log schema for this group's ops (internal) */
+  readonly _logSchema: Ctx['logSchema'];
+
+  /** The feature flag schema (internal) */
+  readonly _flags: Ctx['flags'];
+}
+
+/**
+ * Internal MappedOpGroup interface with all properties exposed.
+ * Used by library implementation code that needs access to mapping details.
+ */
+export interface MappedOpGroupInternal<
+  Ctx extends OpContext,
+  ContributedSchema extends SchemaFields,
+  Ops extends object = NoOpMembers,
+> extends MappedOpGroupMethods<Ctx, ContributedSchema, Ops> {
+  /** The log schema for this group's ops (internal) */
+  readonly _logSchema: Ctx['logSchema'];
+
+  /** The feature flag schema (internal) */
+  readonly _flags: Ctx['flags'];
+
+  /** The schema fields this group contributes to the app's combined schema (internal) */
+  readonly _contributedSchema: ContributedSchema;
+
+  /** The column mapping (library column -> app column, or null to drop) (internal) */
+  readonly _columnMapping: ColumnMapping<SchemaFieldsOf<Ctx['logSchema']>>;
+}
+
+// =============================================================================
+// DEPENDENCY CONFIG TYPES
+// =============================================================================
+
+/**
+ * Minimal structural interface for any OpGroup (internal use only).
+ *
+ * This captures only the internal properties we need to read from an OpGroup
+ * in dependency wiring. The internal properties exist at runtime but are
+ * hidden from the public TypeScript interfaces.
+ *
+ * Note: No `.ops` property - ops are accessed directly as own properties.
+ */
+export interface AnyOpGroup {
+  /** The log schema - read-only access for wiring (internal property) */
+  readonly _logSchema: LogSchema;
+}
+
+/**
+ * Minimal structural interface for a MappedOpGroup (internal use only).
+ * Used for dependency wiring when we need access to contributed schema.
+ */
+export interface AnyMappedOpGroup extends AnyOpGroup {
+  /** The contributed schema after mapping (internal property) */
+  readonly _contributedSchema: SchemaFields;
+}
+
+/**
+ * Type guard to check if an OpGroup has been mapped (has _contributedSchema)
+ */
+export function isMappedOpGroup(dep: AnyOpGroup): dep is AnyMappedOpGroup {
+  return '_contributedSchema' in dep;
+}
+
+/**
+ * Minimal public interface for OpGroups used in deps config.
+ * Accepts any OpGroup or MappedOpGroup without requiring internal properties.
+ * Internal properties are accessed at runtime via type assertion.
+ */
+export interface AnyOpGroupPublic {
+  /** Apply a prefix to all schema columns */
+  prefix(prefix: string): AnyOpGroupPublic;
+  /** Map schema columns to different names */
+  mapColumns(mapping: ColumnMapping): AnyOpGroupPublic;
+}
+
+/**
+ * Type for deps config - maps names to OpGroups (optionally mapped)
+ *
+ * This is used as a constraint (`Deps extends DepsConfig`) so it needs
+ * to be wide enough to accept any specific deps configuration.
+ *
+ * Uses AnyOpGroupPublic to accept OpGroup/MappedOpGroup without requiring
+ * internal properties in the type signature.
+ */
+export type DepsConfig = Record<string, AnyOpGroupPublic>;
+
+// =============================================================================
+// SCHEMA COMBINATION TYPES
+// =============================================================================
+
+/**
+ * Extract the contributed schema from a dep (for combining into app schema)
+ */
+export type ContributedSchemaOf<D> =
+  D extends MappedOpGroup<infer _Ctx, infer CS, infer _Ops>
+    ? CS
+    : D extends OpGroup<infer Ctx, infer _Ops>
+      ? SchemaFieldsOf<Ctx['logSchema']>
+      : never;
+
+/**
+ * Combine all contributed schemas from deps into a union of all their fields.
+ * App's effective schema = appSchema & pg_contributed & mysql_contributed & ...
+ *
+ * This is used to type the combined LogSchema that has access to all columns
+ * from both the app and all wired dependencies.
+ */
+export type CombinedDepsSchema<D extends DepsConfig> = UnionToIntersection<
+  { [K in keyof D]: ContributedSchemaOf<D[K]> }[keyof D]
+>;
+
+/**
+ * Helper: Convert union to intersection
+ * `A | B | C` → `A & B & C`
+ */
+export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void
+  ? I
+  : never;
+
+/**
+ * The effective schema for an OpContext: app schema + all dep contributed schemas.
+ */
+export type EffectiveSchema<T extends SchemaFields, D extends DepsConfig> = T & CombinedDepsSchema<D>;
+
+/**
+ * Extract the typed deps interface from a DepsConfig.
+ * Each dep becomes accessible via ctx.deps.name
+ */
+export type ResolvedDeps<D extends DepsConfig> = {
+  readonly [K in keyof D]: D[K] extends OpGroup<infer Ctx, infer Ops>
+    ? OpGroup<Ctx, Ops>
+    : D[K] extends MappedOpGroup<infer Ctx, infer _CS, infer Ops>
+      ? OpGroup<Ctx, Ops>
+      : never;
+};