@prisma-next/framework-components 0.7.0 → 0.8.0

package/dist/runtime.d.mts

@@ -1,6 +1,236 @@
 import { o as CodecCallContext } from "./codec-DcjlJbcO.mjs";
 import { PlanMeta } from "@prisma-next/contract/types";
 
+//#region src/annotations.d.ts
+/**
+ * The kinds of operations an annotation may apply to.
+ *
+ * - `'read'` — `SELECT` / `find` / `first` / `all` / `count` / aggregates.
+ * - `'write'` — `INSERT` / `UPDATE` / `DELETE` / `create` / `update` / `delete` / `upsert`.
+ *
+ * Annotations declare which kinds they apply to via `defineAnnotation`'s
+ * `applicableTo` option; lane terminals enforce the constraint at both the
+ * type level (via `ValidAnnotations`) and at runtime (via
+ * `assertAnnotationsApplicable`).
+ *
+ * Finer-grained kinds (`'select' | 'insert' | 'update' | 'delete' | 'upsert'`)
+ * are deliberately deferred. The binary covers the common case (the cache
+ * middleware applies to reads; an audit annotation would apply to writes;
+ * tracing/OTel applies to both). When a real annotation surfaces that needs
+ * a finer split, the union widens and existing handles remain typecheckable.
+ */
+type OperationKind = 'read' | 'write';
+/**
+ * An applied annotation. Carries the namespace, the typed payload, and the
+ * `applicableTo` set the underlying handle declared. The `__annotation`
+ * brand lets `read` distinguish branded user annotations from arbitrary
+ * data that may happen to live under the same namespace key in
+ * `plan.meta.annotations` (e.g. framework-internal metadata such as
+ * `meta.annotations.codecs`).
+ *
+ * Constructed by calling an `AnnotationHandle` directly (e.g.
+ * `cacheAnnotation({ ttl: 60 })`); never instantiated by hand.
+ */
+interface AnnotationValue<Payload, Kinds extends OperationKind> {
+  readonly __annotation: true;
+  readonly namespace: string;
+  readonly value: Payload;
+  readonly applicableTo: ReadonlySet<Kinds>;
+}
+/**
+ * Handle returned by `defineAnnotation`. The handle is **callable**: the
+ * call signature wraps a `Payload` into an `AnnotationValue` ready to
+ * pass to a lane terminal's variadic `annotations` argument. The handle
+ * also carries static metadata as own properties:
+ *
+ * - `namespace` — the namespace string the handle was declared with.
+ * - `applicableTo` — the frozen `ReadonlySet<Kinds>` consumed by both
+ *   the type-level `ValidAnnotations` gate and the runtime
+ *   `assertAnnotationsApplicable` gate.
+ * - `read(plan)` — extract the `Payload` from a plan's `meta.annotations`
+ *   if a value was previously written under this handle's namespace.
+ *   Returns `undefined` when the annotation is absent or when the stored
+ *   value is not a branded `AnnotationValue` (e.g. framework-internal
+ *   metadata under the same namespace key).
+ *
+ * Handles are the only supported public entry point for reading and
+ * writing annotations. Direct mutation of `plan.meta.annotations` is not
+ * part of the public API.
+ *
+ * ```typescript
+ * const cacheAnnotation = defineAnnotation<{ ttl: number }>()({
+ *   namespace: 'cache',
+ *   applicableTo: ['read'],
+ * });
+ *
+ * // Call the handle to construct a value:
+ * const applied = cacheAnnotation({ ttl: 60 });
+ *
+ * // Read a stored value off a plan:
+ * const payload = cacheAnnotation.read(plan);
+ * ```
+ *
+ * Note on the inherited `Function.prototype.apply`: because the handle is
+ * a function, the property name `apply` resolves to JavaScript's built-in
+ * `Function.prototype.apply` (which lets you invoke a function with an
+ * array of arguments). This is **not** the construction entry point — to
+ * build an `AnnotationValue`, call the handle directly. The
+ * `AnnotationHandle` interface deliberately does not declare an `apply`
+ * member of its own.
+ */
+interface AnnotationHandle<Payload, Kinds extends OperationKind> {
+  (value: Payload): AnnotationValue<Payload, Kinds>;
+  readonly namespace: string;
+  readonly applicableTo: ReadonlySet<Kinds>;
+  read(plan: {
+    readonly meta: {
+      readonly annotations?: Record<string, unknown>;
+    };
+  }): Payload | undefined;
+}
+/**
+ * Options accepted by `defineAnnotation`.
+ *
+ * `namespace` is the string key under which the annotation is stored in
+ * `plan.meta.annotations`. **Reserved namespaces** include framework-
+ * internal metadata keys; user handles must not use them:
+ *
+ * - `codecs` — used by the SQL emitter to record per-alias codec ids
+ *   (`meta.annotations.codecs[alias] = 'pg/text@1'`); the SQL runtime's
+ *   `decodeRow` reads from this key. A user `defineAnnotation('codecs')`
+ *   handle is not structurally prevented, but its behavior with the
+ *   emitter and the runtime is undefined and we make no compatibility
+ *   guarantees about it.
+ * - Target-specific keys such as `pg` (and equivalents on other
+ *   targets) are similarly reserved for adapter / target use.
+ *
+ * `applicableTo` declares which operation kinds the annotation may attach
+ * to. The lane terminals' type-level `ValidAnnotations<K, As>` gate rejects
+ * annotations whose `Kinds` does not include the terminal's `K`; the
+ * runtime helper `assertAnnotationsApplicable` does the equivalent at
+ * runtime so casts and `any` cannot bypass the gate.
+ */
+interface DefineAnnotationOptions<Kinds extends OperationKind> {
+  readonly namespace: string;
+  readonly applicableTo: readonly Kinds[];
+}
+/**
+ * Defines a typed annotation handle.
+ *
+ * Two-step call form. The first step takes the `Payload` type argument
+ * (TypeScript cannot infer `Payload` from anything in the options, so it
+ * must be supplied explicitly); the second step takes the runtime options
+ * and infers `Kinds` from the `applicableTo` array via a `const` type
+ * parameter, so the operation kinds appear exactly once at the call site.
+ *
+ * @example
+ * ```typescript
+ * // Read-only annotation. Lane terminals like `db.User.first(...)` accept
+ * // it; `db.User.create(...)` rejects it at the type level.
+ * const cacheAnnotation = defineAnnotation<{ ttl?: number; skip?: boolean }>()({
+ *   namespace: 'cache',
+ *   applicableTo: ['read'],
+ * }); // Kinds inferred as 'read'
+ *
+ * // Write-only annotation. Mirror image.
+ * const auditAnnotation = defineAnnotation<{ actor: string }>()({
+ *   namespace: 'audit',
+ *   applicableTo: ['write'],
+ * }); // Kinds inferred as 'write'
+ *
+ * // Annotation applicable to both kinds (e.g. tracing).
+ * const otelAnnotation = defineAnnotation<{ traceId: string }>()({
+ *   namespace: 'otel',
+ *   applicableTo: ['read', 'write'],
+ * }); // Kinds inferred as 'read' | 'write'
+ * ```
+ *
+ * **Reserved namespaces.** See `DefineAnnotationOptions.namespace` for the
+ * list of framework-internal namespaces (`codecs`, target-specific keys).
+ * `defineAnnotation` does not structurally prevent a user from naming a
+ * reserved namespace, but the framework makes no compatibility guarantee
+ * about handles that do.
+ */
+declare function defineAnnotation<Payload>(): <const Kinds extends OperationKind>(options: DefineAnnotationOptions<Kinds>) => AnnotationHandle<Payload, Kinds>;
+/**
+ * Type-level applicability gate consumed by lane terminals.
+ *
+ * Maps a tuple of `AnnotationValue`s to a tuple where each element either
+ * keeps its annotation type (when the annotation's declared `Kinds`
+ * includes the terminal's operation kind `K`) or resolves to `never`
+ * (when the kinds are incompatible). A `never` element makes the entire
+ * tuple unassignable, surfacing the mismatch as a type error at the call
+ * site of the terminal.
+ *
+ * The SQL DSL builders constrain their variadic `...annotations`
+ * parameter via `As & ValidAnnotations<K, As>`. **The intersection is
+ * load-bearing** — see the note below. The ORM terminals deliberately
+ * sidestep this trick by taking one annotation per `meta.annotate(...)`
+ * call (no variadic-tuple inference involved), so `ValidAnnotations` is
+ * consumed only by the SQL DSL today.
+ *
+ * @example
+ * ```typescript
+ * class SelectQuery<Row> {
+ *   annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(
+ *     ...annotations: As & ValidAnnotations<'read', As>
+ *   ): SelectQuery<Row>;
+ * }
+ *
+ * class InsertQuery<Row> {
+ *   annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(
+ *     ...annotations: As & ValidAnnotations<'write', As>
+ *   ): InsertQuery<Row>;
+ * }
+ *
+ * db.users.select('id').annotate(cacheAnnotation({ ttl: 60 }));
+ * // ✓ cacheAnnotation declares 'read'; SelectQuery.annotate requires 'read'.
+ *
+ * db.users.insert({ name: 'Alice' }).annotate(cacheAnnotation({ ttl: 60 }));
+ * // ✗ cacheAnnotation declares 'read'; InsertQuery.annotate requires 'write'.
+ * //   Element resolves to `never` → tuple unassignable → type error.
+ * ```
+ *
+ * **Why `As & ValidAnnotations<K, As>` and not `ValidAnnotations<K, As>`
+ * alone.** TypeScript's variadic-tuple inference is too forgiving when
+ * the parameter type refers to `As` only through `ValidAnnotations`: it
+ * will pick an `As` that makes the call valid even when the gated tuple
+ * would contain `never` for an inapplicable element. The intersection
+ * pins `As` to the actual call-site tuple AND requires it to be
+ * assignable to the gated form. A `never` element in the gated tuple
+ * then collapses the corresponding intersection position to `never`,
+ * and the inapplicable argument fails to assign — surfacing the mismatch
+ * as a type error at the call site.
+ *
+ * The runtime helper `assertAnnotationsApplicable` covers the equivalent
+ * check at runtime so casts and `any` cannot bypass this gate.
+ */
+type ValidAnnotations<K extends OperationKind, As extends readonly AnnotationValue<unknown, OperationKind>[]> = { readonly [I in keyof As]: As[I] extends AnnotationValue<infer P, infer Kinds> ? K extends Kinds ? AnnotationValue<P, Kinds> : never : never };
+/**
+ * Runtime applicability gate. Throws `RUNTIME.ANNOTATION_INAPPLICABLE` if
+ * any annotation in `annotations` declares an `applicableTo` set that does
+ * not include `kind`. Used by lane terminals (SQL DSL builders' `.build()`,
+ * ORM `Collection` terminals) to fail closed when the type-level
+ * `ValidAnnotations` gate is bypassed via cast / `any` / dynamic
+ * invocation.
+ *
+ * Passes silently on:
+ *  - empty arrays
+ *  - annotations whose `applicableTo` includes `kind`
+ *
+ * Throws on:
+ *  - any annotation whose `applicableTo` does not include `kind`. The
+ *    error names the offending annotation's `namespace` and the
+ *    `terminalName` so users can locate the misuse.
+ *
+ * @example
+ * ```typescript
+ * // Inside an ORM read terminal:
+ * assertAnnotationsApplicable(annotations, 'read', 'first');
+ * ```
+ */
+declare function assertAnnotationsApplicable(annotations: readonly AnnotationValue<unknown, OperationKind>[], kind: OperationKind, terminalName: string): void;
+//#endregion
 //#region src/execution/async-iterable-result.d.ts
 declare class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLike<Row[]> {
   private readonly generator;
@@ -120,6 +350,27 @@ interface RuntimeMiddlewareContext {
    * cancels.
    */
   readonly signal?: AbortSignal;
+  /**
+   * Identifies the queryable scope this execution is running under.
+   *
+   * - `'runtime'` — top-level `runtime.execute(plan)`. The default scope
+   *   used by the standard read/write paths.
+   * - `'connection'` — `connection.execute(plan)` after
+   *   `runtime.connection()` checked out a connection from the pool.
+   * - `'transaction'` — `transaction.execute(plan)` inside an explicit
+   *   transaction, or a query routed through `withTransaction`.
+   *
+   * Middleware that should only act at the top level read this field to
+   * bypass non-runtime scopes. The cache middleware uses it to skip
+   * caching inside transactions (where read-after-write coherence is the
+   * caller's expectation) and dedicated connections (where the user has
+   * explicitly stepped outside the shared cache surface). Observers that
+   * don't care about the scope can ignore the field.
+   *
+   * Family runtimes populate this at context-construction time per
+   * scope. Existing middleware that ignore the field are unaffected.
+   */
+  readonly scope: 'runtime' | 'connection' | 'transaction';
 }
 interface AfterExecuteResult {
   readonly rowCount: number;
@@ -249,6 +500,31 @@ interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan, TMutator extend
   onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
   afterExecute?(plan: TPlan, result: AfterExecuteResult, ctx: RuntimeMiddlewareContext): Promise<void>;
 }
+/**
+ * Cross-family middleware — one that doesn't constrain `familyId` or
+ * `targetId` and is therefore compatible with any family runtime's
+ * middleware array (`SqlMiddleware[]`, `MongoMiddleware[]`, etc.).
+ *
+ * The intersection `RuntimeMiddleware & { familyId?: undefined; targetId?: undefined }`
+ * pins both optional properties to exactly `undefined` (intersecting
+ * `string | undefined` with `undefined` collapses to `undefined`). Under
+ * `exactOptionalPropertyTypes: true`, the plain `RuntimeMiddleware` shape
+ * — with `familyId?: string` — is *not* assignable to `SqlMiddleware`
+ * (which narrows `familyId?: 'sql'`) because `string` is wider than
+ * `'sql'`. Pinning the property to `undefined` makes the value a subtype
+ * of every narrowed variant: `undefined` extends both `'sql' | undefined`
+ * and `'mongo' | undefined`, so a `CrossFamilyMiddleware` value drops
+ * into a SQL or Mongo middleware slot without a cast.
+ *
+ * Cross-family middleware factories (`createCacheMiddleware`, future
+ * `audit` / OTel middleware) declare this as their return type so the
+ * cross-family typing is named once rather than re-spelled at every call
+ * site.
+ */
+type CrossFamilyMiddleware<TPlan extends QueryPlan = QueryPlan> = RuntimeMiddleware<TPlan> & {
+  readonly familyId?: undefined;
+  readonly targetId?: undefined;
+};
 /**
  * Optional per-`execute` options accepted by every family runtime.
  *
@@ -260,6 +536,7 @@ interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan, TMutator extend
  */
 interface RuntimeExecuteOptions {
   readonly signal?: AbortSignal;
+  readonly scope?: 'runtime' | 'connection' | 'transaction';
 }
 /**
  * Cross-family SPI for any runtime that can execute plans and be shut down.
@@ -549,5 +826,63 @@ declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends Execut
   }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
 }
 //#endregion
-export { type AfterExecuteResult, AsyncIterableResult, type ExecutionPlan, type InterceptResult, type ParamRefMutator, type QueryPlan, RUNTIME_ABORTED, type ResultType, type RuntimeAbortedPhase, RuntimeCore, type RuntimeCoreOptions, type RuntimeErrorEnvelope, type RuntimeExecuteOptions, type RuntimeExecutor, type RuntimeLog, type RuntimeMiddleware, type RuntimeMiddlewareContext, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runBeforeExecuteChain, runWithMiddleware, runtimeAborted, runtimeError };
+//#region src/meta-builder.d.ts
+/**
+ * Per-terminal meta configurator handed to user callbacks. The terminal's
+ * operation kind `K` is fixed by the terminal that constructed the builder;
+ * `annotate(...)` accepts only annotations whose declared `Kinds` include
+ * `K`.
+ *
+ * The conditional parameter type
+ * `K extends Kinds ? AnnotationValue<P, Kinds> : never` collapses to `never`
+ * for inapplicable annotations, surfacing the mismatch as a type error at
+ * the call site of `meta.annotate(...)`. No variadic-tuple inference is
+ * involved — TypeScript infers `Kinds` from the annotation argument and
+ * checks the conditional directly.
+ *
+ * The runtime gate inside `annotate` (via
+ * `assertAnnotationsApplicable`) catches cast / `any` / dynamic bypasses
+ * and throws `RUNTIME.ANNOTATION_INAPPLICABLE`.
+ *
+ * `annotate` returns the builder for chaining; the return value of the
+ * configurator callback is unused, so both block-body and expression-body
+ * callbacks compile.
+ *
+ * @example
+ * ```typescript
+ * await db.User.find({ id }, (meta) => meta.annotate(cacheAnnotation({ ttl: 60 })));
+ * await db.User.create(input, (meta) => {
+ *   meta.annotate(auditAnnotation({ actor: 'system' }));
+ *   meta.annotate(otelAnnotation({ traceId }));
+ * });
+ * ```
+ */
+interface MetaBuilder<K extends OperationKind> {
+  annotate<P, Kinds extends OperationKind>(annotation: K extends Kinds ? AnnotationValue<P, Kinds> : never): this;
+}
+/**
+ * Lane-side view of a meta builder. Extends the public `MetaBuilder<K>`
+ * surface with `annotations` so lane terminals can read the recorded map
+ * after invoking the user configurator.
+ *
+ * Lane terminals construct one of these via `createMetaBuilder(kind, terminalName)`,
+ * pass it to the user callback as `MetaBuilder<K>` (the narrower public
+ * view), then read `meta.annotations` to thread the recorded values into
+ * `plan.meta.annotations`.
+ */
+interface LaneMetaBuilder<K extends OperationKind> extends MetaBuilder<K> {
+  readonly annotations: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>>;
+}
+/**
+ * Construct a lane-side meta builder for a terminal of operation kind `K`.
+ *
+ * Lane terminals call this with their `kind` (`'read'` or `'write'`) and a
+ * `terminalName` for error messages, hand the resulting builder to the
+ * user-supplied configurator callback (typed as `MetaBuilder<K>`, the
+ * narrower public view), and read `meta.annotations` afterwards to thread
+ * the recorded values into `plan.meta.annotations`.
+ */
+declare function createMetaBuilder<K extends OperationKind>(kind: K, terminalName: string): LaneMetaBuilder<K>;
+//#endregion
+export { type AfterExecuteResult, type AnnotationHandle, type AnnotationValue, AsyncIterableResult, type CrossFamilyMiddleware, type DefineAnnotationOptions, type ExecutionPlan, type InterceptResult, type LaneMetaBuilder, type MetaBuilder, type OperationKind, type ParamRefMutator, type QueryPlan, RUNTIME_ABORTED, type ResultType, type RuntimeAbortedPhase, RuntimeCore, type RuntimeCoreOptions, type RuntimeErrorEnvelope, type RuntimeExecuteOptions, type RuntimeExecutor, type RuntimeLog, type RuntimeMiddleware, type RuntimeMiddlewareContext, type ValidAnnotations, assertAnnotationsApplicable, checkAborted, checkMiddlewareCompatibility, createMetaBuilder, defineAnnotation, isRuntimeError, raceAgainstAbort, runBeforeExecuteChain, runWithMiddleware, runtimeAborted, runtimeError };
 //# sourceMappingURL=runtime.d.mts.map

package/dist/runtime.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/execution/async-iterable-result.ts","../src/execution/query-plan.ts","../src/execution/runtime-middleware.ts","../src/execution/before-execute-chain.ts","../src/execution/runtime-error.ts","../src/execution/race-against-abort.ts","../src/execution/run-with-middleware.ts","../src/execution/runtime-core.ts"],"mappings":"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"}
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/annotations.ts","../src/execution/async-iterable-result.ts","../src/execution/query-plan.ts","../src/execution/runtime-middleware.ts","../src/execution/before-execute-chain.ts","../src/execution/runtime-error.ts","../src/execution/race-against-abort.ts","../src/execution/run-with-middleware.ts","../src/execution/runtime-core.ts","../src/meta-builder.ts"],"mappings":"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"}

package/dist/runtime.mjs

@@ -61,6 +61,113 @@ function runtimeAborted(phase, cause) {
 	return Object.assign(envelope, { cause });
 }
 //#endregion
+//#region src/annotations.ts
+/**
+* Defines a typed annotation handle.
+*
+* Two-step call form. The first step takes the `Payload` type argument
+* (TypeScript cannot infer `Payload` from anything in the options, so it
+* must be supplied explicitly); the second step takes the runtime options
+* and infers `Kinds` from the `applicableTo` array via a `const` type
+* parameter, so the operation kinds appear exactly once at the call site.
+*
+* @example
+* ```typescript
+* // Read-only annotation. Lane terminals like `db.User.first(...)` accept
+* // it; `db.User.create(...)` rejects it at the type level.
+* const cacheAnnotation = defineAnnotation<{ ttl?: number; skip?: boolean }>()({
+*   namespace: 'cache',
+*   applicableTo: ['read'],
+* }); // Kinds inferred as 'read'
+*
+* // Write-only annotation. Mirror image.
+* const auditAnnotation = defineAnnotation<{ actor: string }>()({
+*   namespace: 'audit',
+*   applicableTo: ['write'],
+* }); // Kinds inferred as 'write'
+*
+* // Annotation applicable to both kinds (e.g. tracing).
+* const otelAnnotation = defineAnnotation<{ traceId: string }>()({
+*   namespace: 'otel',
+*   applicableTo: ['read', 'write'],
+* }); // Kinds inferred as 'read' | 'write'
+* ```
+*
+* **Reserved namespaces.** See `DefineAnnotationOptions.namespace` for the
+* list of framework-internal namespaces (`codecs`, target-specific keys).
+* `defineAnnotation` does not structurally prevent a user from naming a
+* reserved namespace, but the framework makes no compatibility guarantee
+* about handles that do.
+*/
+function defineAnnotation() {
+	return (options) => {
+		const namespace = options.namespace;
+		const applicableTo = Object.freeze(new Set(options.applicableTo));
+		function handle(value) {
+			return Object.freeze({
+				__annotation: true,
+				namespace,
+				value,
+				applicableTo
+			});
+		}
+		function read(plan) {
+			const stored = plan.meta.annotations?.[namespace];
+			if (!isAnnotationValue(stored)) return;
+			if (stored.namespace !== namespace) return;
+			return stored.value;
+		}
+		return Object.freeze(Object.assign(handle, {
+			namespace,
+			applicableTo,
+			read
+		}));
+	};
+}
+/**
+* Runtime applicability gate. Throws `RUNTIME.ANNOTATION_INAPPLICABLE` if
+* any annotation in `annotations` declares an `applicableTo` set that does
+* not include `kind`. Used by lane terminals (SQL DSL builders' `.build()`,
+* ORM `Collection` terminals) to fail closed when the type-level
+* `ValidAnnotations` gate is bypassed via cast / `any` / dynamic
+* invocation.
+*
+* Passes silently on:
+*  - empty arrays
+*  - annotations whose `applicableTo` includes `kind`
+*
+* Throws on:
+*  - any annotation whose `applicableTo` does not include `kind`. The
+*    error names the offending annotation's `namespace` and the
+*    `terminalName` so users can locate the misuse.
+*
+* @example
+* ```typescript
+* // Inside an ORM read terminal:
+* assertAnnotationsApplicable(annotations, 'read', 'first');
+* ```
+*/
+function assertAnnotationsApplicable(annotations, kind, terminalName) {
+	for (const annotation of annotations) if (!annotation.applicableTo.has(kind)) throw runtimeError("RUNTIME.ANNOTATION_INAPPLICABLE", `Annotation '${annotation.namespace}' is not applicable to '${kind}' operations (terminal: '${terminalName}'). The annotation declares applicableTo = [${Array.from(annotation.applicableTo).map((k) => `'${k}'`).join(", ")}].`, {
+		namespace: annotation.namespace,
+		terminalName,
+		kind,
+		applicableTo: Array.from(annotation.applicableTo)
+	});
+}
+/**
+* Type guard for branded annotation values stored in `plan.meta.annotations`.
+*
+* Internal — used by `AnnotationHandle.read` to distinguish user
+* annotations (created by calling a handle returned from
+* `defineAnnotation(...)`) from framework-internal metadata that may
+* happen to live under the same namespace key.
+*/
+function isAnnotationValue(value) {
+	if (value === null || typeof value !== "object") return false;
+	return value.__annotation === true;
+}
+//#endregion
 //#region src/execution/async-iterable-result.ts
 var AsyncIterableResult = class {
 	generator;
@@ -416,6 +523,38 @@ function checkMiddlewareCompatibility(middleware, runtimeFamilyId, runtimeTarget
 	});
 }
 //#endregion
-export { AsyncIterableResult, RUNTIME_ABORTED, RuntimeCore, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runBeforeExecuteChain, runWithMiddleware, runtimeAborted, runtimeError };
+//#region src/meta-builder.ts
+var MetaBuilderImpl = class {
+	#kind;
+	#terminalName;
+	#annotations = /* @__PURE__ */ new Map();
+	constructor(kind, terminalName) {
+		this.#kind = kind;
+		this.#terminalName = terminalName;
+	}
+	get annotations() {
+		return this.#annotations;
+	}
+	annotate(annotation) {
+		const value = annotation;
+		assertAnnotationsApplicable([value], this.#kind, this.#terminalName);
+		this.#annotations.set(value.namespace, value);
+		return this;
+	}
+};
+/**
+* Construct a lane-side meta builder for a terminal of operation kind `K`.
+*
+* Lane terminals call this with their `kind` (`'read'` or `'write'`) and a
+* `terminalName` for error messages, hand the resulting builder to the
+* user-supplied configurator callback (typed as `MetaBuilder<K>`, the
+* narrower public view), and read `meta.annotations` afterwards to thread
+* the recorded values into `plan.meta.annotations`.
+*/
+function createMetaBuilder(kind, terminalName) {
+	return new MetaBuilderImpl(kind, terminalName);
+}
+//#endregion
+export { AsyncIterableResult, RUNTIME_ABORTED, RuntimeCore, assertAnnotationsApplicable, checkAborted, checkMiddlewareCompatibility, createMetaBuilder, defineAnnotation, isRuntimeError, raceAgainstAbort, runBeforeExecuteChain, runWithMiddleware, runtimeAborted, runtimeError };
 
 //# sourceMappingURL=runtime.mjs.map