@avelonjs/core 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@avelonjs/core",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Frozen TypeScript contracts, errors, and capability types shared by Avelon packages.",
+  "license": "MIT",
+  "author": "Ryan Yannelli <ryanyannelli@gmail.com>",
+  "homepage": "https://github.com/yannelli/avelon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yannelli/avelon.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/yannelli/avelon/issues"
+  },
+  "keywords": [
+    "avelon",
+    "typescript",
+    "contracts",
+    "query-ir"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,204 @@
+/** HTTP methods understood by route manifests. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD'
+
+/** A route entry consumed by adapters and dispatched by the kernel. */
+export interface RouteDefinition<TController = unknown> {
+  /** Stable route name used for URL generation. */
+  name: string
+  /** Transport-neutral HTTP method. POST remains valid when server actions are unavailable. */
+  method: HttpMethod
+  /** Route path with named parameters. */
+  path: string
+  /** Controller reference passed through to the kernel without adapter inspection. */
+  controller: TController
+  /** Controller method invoked by the kernel. */
+  action: string
+  /** Middleware aliases applied in declaration order. */
+  middleware: readonly string[]
+  /** Route parameter names that require model binding. */
+  bindings: Readonly<Record<string, string>>
+  /** Whether the route also exposes a JSON transport. */
+  api: boolean
+}
+
+/** Complete route input supplied to an adapter. */
+export interface RouteManifest<TController = unknown> {
+  /** Manifest revision used to reject stale generated output. */
+  version: string
+  /** Routes in declaration order. */
+  routes: readonly RouteDefinition<TController>[]
+}
+
+/** Options applied when writing a request or response cookie. */
+export interface CookieOptions {
+  /** Host to which the cookie is sent. */
+  readonly domain?: string
+  /** Absolute time after which the cookie is invalid. */
+  readonly expires?: Date
+  /** Whether browser scripts are prevented from reading the cookie. */
+  readonly httpOnly?: boolean
+  /** Lifetime in seconds relative to when the cookie is written. */
+  readonly maxAge?: number
+  /** Whether the cookie is isolated to its top-level site partition. */
+  readonly partitioned?: boolean
+  /** Request path to which the cookie is sent. */
+  readonly path?: string
+  /** Cross-site sending policy. */
+  readonly sameSite?: 'lax' | 'strict' | 'none'
+  /** Whether the cookie is sent only over secure transports. */
+  readonly secure?: boolean
+}
+
+/** Request-scoped cookie access supplied to identity drivers through application wiring. */
+export interface RequestCookies {
+  /** Returns a cookie value or undefined when it is absent. */
+  get(name: string): string | undefined
+  /** Writes a cookie using transport-neutral options. */
+  set(name: string, value: string, options?: CookieOptions): void
+  /** Deletes a cookie using the path and domain that scoped the original cookie. */
+  delete(name: string, options?: Pick<CookieOptions, 'domain' | 'path'>): void
+}
+
+/** Framework-neutral request passed from an adapter to the kernel. */
+export interface HttpRequest<TBody = unknown> {
+  /** Request method. */
+  method: HttpMethod
+  /** Absolute request URL. */
+  url: string
+  /** Matched route parameters. */
+  params: Readonly<Record<string, string>>
+  /** Parsed query values, preserving repeated keys. */
+  query: Readonly<Record<string, string | readonly string[]>>
+  /** Normalized request headers. */
+  headers: Readonly<Record<string, string>>
+  /** Parsed request cookies. */
+  cookies: Readonly<Record<string, string>>
+  /** Adapter-decoded request body. */
+  body: TBody
+  /** Returns the undecoded wire payload independently of `body` decoding. */
+  rawBody(): Promise<Uint8Array>
+  /** Whether the native transport has observed request cancellation; may be a live getter. */
+  aborted: boolean
+}
+
+/** Successful or failed controller action state suitable for any write transport. */
+export interface ActionResult<TData = unknown> {
+  /** Result discriminator. */
+  type: 'action'
+  /** Whether the action completed successfully. */
+  ok: boolean
+  /** Serializable action output when available. */
+  data?: TData
+  /** Field-keyed validation messages when the action is invalid. */
+  errors?: Readonly<Record<string, readonly string[]>>
+  /** Transport-neutral HTTP status hint. */
+  status?: number
+}
+
+/** Redirect requested by a controller. */
+export interface RedirectResult {
+  /** Result discriminator. */
+  type: 'redirect'
+  /** Destination URL or application-relative path. */
+  location: string
+  /** Redirect status with defined browser semantics. */
+  status: 302 | 303 | 307 | 308
+}
+
+/** Opaque adapter-owned view reference that core never inspects. */
+export type ViewRef<TReference = unknown> = TReference
+
+/** Controller result rendered by the configured adapter. */
+export interface ViewResult<TViewRef = ViewRef, TProps extends object = Record<string, unknown>> {
+  /** Result discriminator. */
+  type: 'view'
+  /** Opaque view reference interpreted only by the adapter. */
+  view: TViewRef
+  /** Serializable properties supplied to the view. */
+  props: TProps
+  /** Transport-neutral HTTP status hint. */
+  status?: number
+}
+
+/** Byte stream returned by an API controller through a streaming-capable adapter. */
+export interface StreamResult {
+  /** Result discriminator. */
+  type: 'stream'
+  /** Response bytes yielded in transport order. */
+  body: AsyncIterable<Uint8Array>
+  /** Media type written before streaming begins. */
+  contentType: string
+  /** Transport-neutral HTTP status hint. */
+  status?: number
+}
+
+/** Result variants the kernel may return to an adapter. */
+export type KernelResult<TViewRef = ViewRef> =
+  | ActionResult
+  | RedirectResult
+  | ViewResult<TViewRef, object>
+  | StreamResult
+
+/** Core request pipeline boundary used by every adapter. */
+export interface Kernel<TController = unknown, TViewRef = ViewRef> {
+  /**
+   * Runs the request pipeline. Adapter wiring prevents stream results when the configured adapter
+   * declares `streaming: false`.
+   */
+  dispatch(
+    route: RouteDefinition<TController>,
+    request: HttpRequest,
+  ): Promise<KernelResult<TViewRef>>
+}
+
+/** Options supplied while mounting a route manifest. */
+export interface MountOptions<TController = unknown, TViewRef = ViewRef> {
+  /** Core dispatcher all mounted routes delegate to. */
+  kernel: Kernel<TController, TViewRef>
+  /** Optional URL prefix prepended by the adapter. */
+  basePath?: string
+  /** Whether development-only adapter behavior may be enabled. */
+  development?: boolean
+}
+
+/** Observable output of mounting a route manifest. */
+export interface MountResult {
+  /** Route names mounted for runtime dispatch. */
+  mounted: readonly string[]
+  /** Framework-owned files generated by a file-system adapter. */
+  generated: readonly string[]
+}
+
+/** Translation boundary implemented by a web framework adapter. */
+export interface Adapter<
+  TController = unknown,
+  TViewRef = ViewRef,
+  TNativeRequest = unknown,
+  TNativeResponse = unknown,
+> {
+  /** Human-readable adapter name. */
+  readonly name: string
+  /** Literal capabilities used by route generation and runtime wiring. */
+  readonly capabilities: {
+    /** Whether routes are materialized as framework-owned files. */
+    readonly fileSystemRouting: boolean
+    /** Whether write routes use generated server actions instead of ordinary HTTP requests. */
+    readonly serverActions: boolean
+    /** Whether the adapter accepts `StreamResult`; false prevents the kernel from emitting one. */
+    readonly streaming: boolean
+    /** Whether middleware may execute in an edge runtime. */
+    readonly edgeMiddleware: boolean
+  }
+  /** Generates or registers routes while delegating request execution to the supplied kernel. */
+  mount(
+    manifest: RouteManifest<TController>,
+    options: MountOptions<TController, TViewRef>,
+  ): Promise<MountResult>
+  /**
+   * Converts a native request. An unparseable body never causes this method to throw: `body` is
+   * null and kernel validation maps the failure to `Invalid`.
+   */
+  toRequest(native: TNativeRequest): Promise<HttpRequest>
+  /** Converts a kernel result into the framework's native response representation. */
+  toResponse(result: KernelResult<TViewRef>): Promise<TNativeResponse>
+}

package/src/drivers/ai.ts

@@ -0,0 +1,99 @@
+import type { CapabilityMembers, CapabilitySurface, DriverContract } from './common'
+
+/** Portable AI operation modes. */
+export type AiMode = 'completion' | 'embedding'
+
+/** Literal AI modes and streaming support declared by a driver. */
+export interface AiCapabilities<TMode extends AiMode = AiMode> {
+  /** Operation modes retained as a literal readonly list. */
+  readonly modes: readonly TMode[]
+  /** Whether completion output may be streamed. */
+  readonly streaming: boolean
+}
+
+/** One role-tagged message in a completion request. */
+export interface AiMessage {
+  /** Message author's role. */
+  role: 'system' | 'user' | 'assistant'
+  /** Message text. */
+  content: string
+}
+
+/** Portable completion request. */
+export interface CompletionRequest {
+  /** Model identifier understood by the configured driver. */
+  model: string
+  /** Ordered conversation messages. */
+  messages: readonly AiMessage[]
+  /** Sampling temperature when supported by the selected model. */
+  temperature?: number
+  /** Maximum generated tokens. */
+  maxTokens?: number
+}
+
+/** Completed text generation. */
+export interface CompletionResult {
+  /** Generated text. */
+  text: string
+  /** Input tokens counted by the driver. */
+  inputTokens?: number
+  /** Output tokens counted by the driver. */
+  outputTokens?: number
+}
+
+/** Increment emitted by a streaming completion. */
+export interface CompletionChunk {
+  /** Incremental generated text. */
+  text: string
+  /** Whether this is the terminal chunk. */
+  done: boolean
+}
+
+/** Embedding result preserving input order. */
+export interface EmbeddingResult {
+  /** Vector for each supplied input. */
+  embeddings: readonly (readonly number[])[]
+  /** Input tokens counted by the driver. */
+  inputTokens?: number
+}
+
+/** Base AI driver identity; operation methods are added only by literal mode capabilities. */
+export interface AiDriver<
+  TCapabilities extends AiCapabilities = AiCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {}
+
+/** Completion methods exposed only when completion mode is configured. */
+export interface CompletionAiSurface {
+  /** Generates one complete response. */
+  complete(request: CompletionRequest): Promise<CompletionResult>
+}
+
+/** Embedding methods exposed only when embedding mode is configured. */
+export interface EmbeddingAiSurface {
+  /** Embeds one or more text inputs. */
+  embed(model: string, input: string | readonly string[]): Promise<EmbeddingResult>
+}
+
+/** Streaming methods exposed only by completion drivers that support streaming. */
+export interface StreamingAiSurface {
+  /** Streams completion chunks in generation order. */
+  stream(request: CompletionRequest): AsyncIterable<CompletionChunk>
+}
+
+type HasMode<TCapabilities extends AiCapabilities, TMode extends AiMode> =
+  TMode extends CapabilityMembers<TCapabilities['modes']> ? true : false
+
+type StreamingFor<TCapabilities extends AiCapabilities> =
+  HasMode<TCapabilities, 'completion'> extends true
+    ? CapabilitySurface<TCapabilities['streaming'], StreamingAiSurface>
+    : object
+
+/** AI facade narrowed to literal operation modes and streaming support. */
+export type AI<TDriver extends AiDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'raw'
+> &
+  CapabilitySurface<HasMode<TDriver['capabilities'], 'completion'>, CompletionAiSurface> &
+  CapabilitySurface<HasMode<TDriver['capabilities'], 'embedding'>, EmbeddingAiSurface> &
+  StreamingFor<TDriver['capabilities']>

package/src/drivers/cache.ts

@@ -0,0 +1,48 @@
+import type { CapabilitySurface, DriverContract } from './common'
+
+/** Literal cache features used to narrow namespaced and locking operations. */
+export interface CacheCapabilities {
+  /** Whether entries may be grouped and invalidated by tag. */
+  readonly tags: boolean
+  /** Whether distributed or process-local locks are available. */
+  readonly locks: boolean
+}
+
+/** Common key-value operations returned by a tagged cache namespace. */
+export interface CacheStore {
+  /** Reads and decodes a value, returning null on a miss. */
+  get<TValue>(key: string): Promise<TValue | null>
+  /** Stores a value for an optional number of seconds. */
+  put<TValue>(key: string, value: TValue, ttlSeconds?: number): Promise<void>
+  /** Removes one key if it exists. */
+  forget(key: string): Promise<void>
+  /** Removes every entry in this cache namespace. */
+  flush(): Promise<void>
+}
+
+/** Base cache contract. */
+export interface CacheDriver<
+  TCapabilities extends CacheCapabilities = CacheCapabilities,
+  TRaw = unknown,
+>
+  extends DriverContract<TCapabilities, TRaw>, CacheStore {}
+
+/** Tag operations exposed only by caches that support tagged namespaces. */
+export interface TaggedCacheSurface {
+  /** Returns a cache namespace whose writes carry all supplied tags. */
+  tags(names: readonly string[]): CacheStore
+}
+
+/** Lock operations exposed only by lock-capable cache drivers. */
+export interface LockCacheSurface {
+  /** Runs a callback while holding a named lock for at most the requested duration. */
+  lock<TResult>(key: string, ttlSeconds: number, callback: () => Promise<TResult>): Promise<TResult>
+}
+
+/** Cache facade narrowed to tag and lock capabilities. */
+export type Cache<TDriver extends CacheDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'get' | 'put' | 'forget' | 'flush' | 'raw'
+> &
+  CapabilitySurface<TDriver['capabilities']['tags'], TaggedCacheSurface> &
+  CapabilitySurface<TDriver['capabilities']['locks'], LockCacheSurface>

package/src/drivers/common.ts

@@ -0,0 +1,29 @@
+/** Common identity and escape-hatch contract implemented by every driver. */
+export interface DriverContract<TCapabilities extends object = object, TRaw = unknown> {
+  /** Driver implementation name, independent of the configured instance. */
+  readonly name: string
+  /** Framework-level instance name such as `default`, `archive`, or `marketing`. */
+  readonly instance: string
+  /** Literal capability declaration used to narrow the configured facade. */
+  readonly capabilities: TCapabilities
+  /** Returns the typed underlying client for use in application driver extensions. */
+  raw(): TRaw
+}
+
+/** Extracts the literal capability shape declared by a driver. */
+export type DriverCapabilitiesOf<TDriver extends DriverContract> = TDriver['capabilities']
+
+/** Resolves to an operation surface only when its capability is literally true. */
+export type CapabilitySurface<TCapability, TSurface> = TCapability extends true ? TSurface : object
+
+/** Resolves to the literal members retained in a readonly capability spectrum. */
+export type CapabilityMembers<TValues extends readonly unknown[]> = TValues[number]
+
+/** Checks a capability key at runtime while rejecting misspelled keys at compile time. */
+export function supports<TCapabilities extends object, TKey extends keyof TCapabilities>(
+  driver: { readonly capabilities: TCapabilities },
+  capability: TKey,
+): boolean {
+  const value = driver.capabilities[capability]
+  return value === true || (Array.isArray(value) ? value.length > 0 : Boolean(value))
+}

package/src/drivers/database.ts

@@ -0,0 +1,160 @@
+import type { QueryIR } from '../query'
+import type { CapabilitySurface, DriverContract } from './common'
+
+/** Literal database features used by the query facade, compiler, and Bailiff. */
+export interface DatabaseCapabilities {
+  /** Whether multi-statement transactions are available. */
+  readonly transactions: boolean
+  /** Whether wards can be compiled to database row security. */
+  readonly rowSecurity: boolean
+  /** Maximum supported nested relation depth. */
+  readonly maxRelationDepth: number
+  /** Whether native full-text search is available. */
+  readonly fullTextSearch: boolean
+  /** Whether upsert queries are accepted. */
+  readonly upsert: boolean
+  /** Whether write queries may return rows. */
+  readonly returning: boolean
+  /**
+   * Whether driver-specific queries can execute window functions. Informational in v1; this gates
+   * no portable facade surface.
+   */
+  readonly windowFunctions: boolean
+  /**
+   * Whether driver-specific queries can filter or project JSON values. Informational in v1; this
+   * gates no portable facade surface.
+   */
+  readonly jsonOperators: boolean
+}
+
+/** Result of compiling and executing one query IR operation. */
+export interface QueryResult<TRow = Record<string, unknown>> {
+  /** Rows selected or returned by the operation. */
+  rows: readonly TRow[]
+  /** Number of rows affected by the operation. */
+  affected: number
+  /** Present only for `count` mode and absent for every other query mode. */
+  count?: number
+}
+
+/** Driver-owned migration plan ready for review or application. */
+export interface MigrationPlan {
+  /** Stable plan identifier. */
+  id: string
+  /** Ordered migration identifiers included in the plan. */
+  migrations: readonly string[]
+  /** Human-readable statements or steps for inspection. */
+  steps: readonly string[]
+}
+
+/** Current application state for one driver-owned migration. */
+export interface MigrationStatus {
+  /** Stable migration identifier. */
+  id: string
+  /** Whether the migration has been applied. */
+  applied: boolean
+  /** Application time when known. */
+  appliedAt?: Date
+}
+
+/** Base database contract available independently of optional capabilities. */
+export interface DatabaseDriver<
+  TCapabilities extends DatabaseCapabilities = DatabaseCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Compiles and executes a serializable query operation. */
+  execute<TRow = Record<string, unknown>>(query: QueryIR): Promise<QueryResult<TRow>>
+  /** Invokes a named database routine for operations outside the portable query IR. */
+  rpc<TResult = unknown>(routine: string, args: Readonly<Record<string, unknown>>): Promise<TResult>
+  /** Produces the pending driver-owned migration plan. */
+  plan(): Promise<MigrationPlan>
+  /** Applies pending driver-owned migrations. */
+  apply(): Promise<readonly MigrationStatus[]>
+  /** Rolls back the requested number of applied migration batches. */
+  rollback(steps?: number): Promise<readonly MigrationStatus[]>
+  /** Returns the status of every known migration. */
+  status(): Promise<readonly MigrationStatus[]>
+}
+
+/** Database operations available inside a transaction callback. */
+export interface DatabaseTransaction {
+  /** Compiles and executes a query in the current transaction. */
+  execute<TRow = Record<string, unknown>>(query: QueryIR): Promise<QueryResult<TRow>>
+  /** Invokes a named routine in the current transaction. */
+  rpc<TResult = unknown>(routine: string, args: Readonly<Record<string, unknown>>): Promise<TResult>
+}
+
+/** Transaction methods exposed only by transaction-capable drivers. */
+export interface TransactionSurface {
+  /** Runs a callback atomically and returns its result after commit. */
+  transaction<TResult>(
+    callback: (transaction: DatabaseTransaction) => Promise<TResult>,
+  ): Promise<TResult>
+}
+
+/** Row-security methods exposed only by drivers that compile wards. */
+export interface RowSecuritySurface {
+  /** Synchronizes compiled wards with the database's row-security policies. */
+  syncWards(): Promise<void>
+}
+
+/** Full-text methods exposed only by drivers with native search support. */
+export interface DatabaseFullTextSurface {
+  /** Searches a table's indexed text and returns matching rows. */
+  search<TRow = Record<string, unknown>>(
+    table: string,
+    query: string,
+    options?: { readonly columns?: readonly string[]; readonly limit?: number },
+  ): Promise<QueryResult<TRow>>
+}
+
+type DatabaseQuery<TCapabilities extends DatabaseCapabilities> = QueryIR &
+  (TCapabilities['upsert'] extends true
+    ? object
+    : { mode: Exclude<QueryIR['mode'], 'upsert'>; conflict?: never }) &
+  (TCapabilities['returning'] extends true ? object : { returning?: never })
+
+type DatabaseTransactionFor<TCapabilities extends DatabaseCapabilities> =
+  TCapabilities['transactions'] extends true ? TransactionSurface : object
+
+type DatabaseRowSecurityFor<TCapabilities extends DatabaseCapabilities> = CapabilitySurface<
+  TCapabilities['rowSecurity'],
+  RowSecuritySurface
+>
+
+type DatabaseFullTextFor<TCapabilities extends DatabaseCapabilities> = CapabilitySurface<
+  TCapabilities['fullTextSearch'],
+  DatabaseFullTextSurface
+>
+
+/** Always-available database facade methods with capability-restricted query input. */
+export interface DatabaseSurface<TDriver extends DatabaseDriver> {
+  /** Driver implementation name. */
+  readonly name: TDriver['name']
+  /** Configured connection name. */
+  readonly instance: TDriver['instance']
+  /** Driver's exact literal capability declaration. */
+  readonly capabilities: TDriver['capabilities']
+  /** Compiles and executes a query allowed by the configured capability declaration. */
+  execute<TRow = Record<string, unknown>>(
+    query: DatabaseQuery<TDriver['capabilities']>,
+  ): Promise<QueryResult<TRow>>
+  /** Invokes a named database routine. */
+  rpc<TResult = unknown>(routine: string, args: Readonly<Record<string, unknown>>): Promise<TResult>
+  /** Produces the pending migration plan. */
+  plan(): Promise<MigrationPlan>
+  /** Applies pending migrations. */
+  apply(): Promise<readonly MigrationStatus[]>
+  /** Rolls back applied migration batches. */
+  rollback(steps?: number): Promise<readonly MigrationStatus[]>
+  /** Returns all migration states. */
+  status(): Promise<readonly MigrationStatus[]>
+  /** Returns the driver's typed underlying client. */
+  raw(): ReturnType<TDriver['raw']>
+}
+
+/** Database facade narrowed to the exact capabilities of its configured driver. */
+export type Database<TDriver extends DatabaseDriver> = DatabaseSurface<TDriver> &
+  DatabaseTransactionFor<TDriver['capabilities']> &
+  DatabaseRowSecurityFor<TDriver['capabilities']> &
+  DatabaseFullTextFor<TDriver['capabilities']>

package/src/drivers/flags.ts

@@ -0,0 +1,50 @@
+import type { DriverContract } from './common'
+
+/** Literal feature-flag capabilities. */
+export interface FlagCapabilities {
+  /** Whether evaluations may use actor and request targeting context. */
+  readonly targeting: boolean
+}
+
+/** Explicit context supplied to a targeted feature-flag evaluation. */
+export interface FlagContext {
+  /** Stable actor identifier when evaluating for an actor. */
+  actorId?: string
+  /** Stable organization identifier when evaluating for an organization. */
+  organizationId?: string
+  /** Additional serializable targeting attributes. */
+  attributes?: Readonly<Record<string, string | number | boolean>>
+}
+
+/** Feature flag evaluation contract. */
+export interface FlagDriver<
+  TCapabilities extends FlagCapabilities = FlagCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Evaluates a flag and returns the supplied default when it is unknown. */
+  evaluate<TValue>(key: string, defaultValue: TValue, context?: FlagContext): Promise<TValue>
+}
+
+type FlagContextFor<TCapabilities extends FlagCapabilities> =
+  TCapabilities['targeting'] extends true ? FlagContext : never
+
+/** Feature-flag facade narrowed to its driver's targeting capability. */
+export interface FlagSurface<TDriver extends FlagDriver> {
+  /** Driver implementation name. */
+  readonly name: TDriver['name']
+  /** Configured flag connection name. */
+  readonly instance: TDriver['instance']
+  /** Exact flag capability declaration. */
+  readonly capabilities: TDriver['capabilities']
+  /** Evaluates a flag with optional context only when targeting is supported. */
+  evaluate<TValue>(
+    key: string,
+    defaultValue: TValue,
+    context?: FlagContextFor<TDriver['capabilities']>,
+  ): Promise<TValue>
+  /** Returns the driver's typed underlying client. */
+  raw(): ReturnType<TDriver['raw']>
+}
+
+/** Feature-flag facade narrowed to its driver's exact capabilities. */
+export type Flags<TDriver extends FlagDriver> = FlagSurface<TDriver>