@glasstrace/sdk 1.16.0 → 1.18.0

package/dist/{index.d-3-cJoY8y.d.cts → index.d-DhatN7mq.d.cts}

@@ -324,4 +324,4 @@ declare const SIDE_EFFECT_OPERATION_PHASES: readonly ["request", "post_response"
  */
 type SideEffectOperationPhase = (typeof SIDE_EFFECT_OPERATION_PHASES)[number];
 
-export { type AnonApiKey as A, type CaptureConfig as C, type GlasstraceEnvVars as G, type ImportGraphPayload as I, type SideEffectOperationKind as S, type SideEffectOperationStatus as a, type SideEffectOperationPhase as b, type SideEffectSemanticFieldKey as c, deriveSessionId as d, type SideEffectOmissionReason as e, type SideEffectSemanticFieldStableCoreKey as f, type SourceMapUploadResponse as g, type SourceMapManifestResponse as h, isSideEffectSemanticFieldKey as i, type SdkDiagnosticCode as j, type SessionId as k, type GlasstraceOptions as l, type SdkInitResponse as m, type SdkHealthReport as n };
+export { type AnonApiKey as A, type CaptureConfig as C, type GlasstraceEnvVars as G, type ImportGraphPayload as I, type SourceMapUploadResponse as S, type SourceMapManifestResponse as a, type SideEffectOperationKind as b, type SideEffectOperationStatus as c, deriveSessionId as d, type SideEffectOperationPhase as e, type SideEffectSemanticFieldKey as f, type SideEffectOmissionReason as g, type SideEffectSemanticFieldStableCoreKey as h, isSideEffectSemanticFieldKey as i, type SdkDiagnosticCode as j, type SessionId as k, type GlasstraceOptions as l, type SdkInitResponse as m, type SdkHealthReport as n };

package/dist/{index.d-3-cJoY8y.d.ts → index.d-DhatN7mq.d.ts}

@@ -324,4 +324,4 @@ declare const SIDE_EFFECT_OPERATION_PHASES: readonly ["request", "post_response"
  */
 type SideEffectOperationPhase = (typeof SIDE_EFFECT_OPERATION_PHASES)[number];
 
-export { type AnonApiKey as A, type CaptureConfig as C, type GlasstraceEnvVars as G, type ImportGraphPayload as I, type SideEffectOperationKind as S, type SideEffectOperationStatus as a, type SideEffectOperationPhase as b, type SideEffectSemanticFieldKey as c, deriveSessionId as d, type SideEffectOmissionReason as e, type SideEffectSemanticFieldStableCoreKey as f, type SourceMapUploadResponse as g, type SourceMapManifestResponse as h, isSideEffectSemanticFieldKey as i, type SdkDiagnosticCode as j, type SessionId as k, type GlasstraceOptions as l, type SdkInitResponse as m, type SdkHealthReport as n };
+export { type AnonApiKey as A, type CaptureConfig as C, type GlasstraceEnvVars as G, type ImportGraphPayload as I, type SourceMapUploadResponse as S, type SourceMapManifestResponse as a, type SideEffectOperationKind as b, type SideEffectOperationStatus as c, deriveSessionId as d, type SideEffectOperationPhase as e, type SideEffectSemanticFieldKey as f, type SideEffectOmissionReason as g, type SideEffectSemanticFieldStableCoreKey as h, isSideEffectSemanticFieldKey as i, type SdkDiagnosticCode as j, type SessionId as k, type GlasstraceOptions as l, type SdkInitResponse as m, type SdkHealthReport as n };

package/dist/index.d.cts

@@ -1,7 +1,8 @@
-export { C as CorrelationIdRequest, G as GlasstraceSpanProcessor, S as SdkError, a as SessionManager, c as captureCorrelationId, g as getDateString, b as getOrigin } from './correlation-id-CelUvw7j.cjs';
-export { F as FetchTarget, G as GlasstraceExporter, a as GlasstraceExporterOptions, I as InitClaimResult, R as ResolvedConfig, c as captureError, b as classifyFetchTarget, d as createGlasstraceSpanProcessor, g as getActiveConfig, e as getDiscoveryHandler, f as getLinkedAccountId, h as getOrCreateAnonKey, i as getStatus, j as isAnonymousMode, k as isProductionDisabled, l as isReady, m as loadCachedConfig, p as performInit, r as readAnonKey, n as readEnvVars, o as registerGlasstrace, q as resolveConfig, s as saveCachedConfig, t as sendInitRequest, w as waitForReady, u as withGlasstraceConfig } from './capture-error-B0txjNut.cjs';
-import { S as SideEffectOperationKind, a as SideEffectOperationStatus, b as SideEffectOperationPhase, c as SideEffectSemanticFieldKey } from './index.d-3-cJoY8y.cjs';
-export { e as SideEffectOmissionReason, f as SideEffectSemanticFieldStableCoreKey, d as deriveSessionId, i as isSideEffectSemanticFieldKey } from './index.d-3-cJoY8y.cjs';
+export { C as CorrelationIdRequest, G as GlasstraceSpanProcessor, S as SdkError, a as SessionManager, c as captureCorrelationId, g as getDateString, b as getOrigin } from './correlation-id-CClOq8Wn.cjs';
+export { F as FetchTarget, G as GlasstraceExporter, a as GlasstraceExporterOptions, I as InitClaimResult, R as ResolvedConfig, c as captureError, b as classifyFetchTarget, d as createGlasstraceSpanProcessor, g as getActiveConfig, e as getDiscoveryHandler, f as getLinkedAccountId, h as getOrCreateAnonKey, i as getStatus, j as isAnonymousMode, k as isProductionDisabled, l as isReady, m as loadCachedConfig, p as performInit, r as readAnonKey, n as readEnvVars, o as registerGlasstrace, q as resolveConfig, s as saveCachedConfig, t as sendInitRequest, w as waitForReady, u as withGlasstraceConfig } from './capture-error-B8qiXFeC.cjs';
+import { b as SideEffectOperationKind, c as SideEffectOperationStatus, e as SideEffectOperationPhase, f as SideEffectSemanticFieldKey } from './index.d-DhatN7mq.cjs';
+export { g as SideEffectOmissionReason, h as SideEffectSemanticFieldStableCoreKey, d as deriveSessionId, i as isSideEffectSemanticFieldKey } from './index.d-DhatN7mq.cjs';
+import { Span } from './trace/span';
 export { RequestMiddlewareFunction, TracedRequestMiddlewareOptions } from './middleware/index.cjs';
 export { WithAsyncCausalityOptions } from './async-context/index.cjs';
 import './export/ReadableSpan';
@@ -90,6 +91,20 @@ interface RecordSideEffectInput {
      * prefix), so a categorical and a scalar facet can share a name.
      */
     scalars?: Record<string, unknown>;
+    /**
+     * Optional producer-asserted boolean relations (invariants) emitted on
+     * the categorical field channel. Keys must be camelCase ending in
+     * `Holds` (e.g. `timezonePreservedHolds`); values are real `boolean`s,
+     * coerced to `"true"`/`"false"` on the wire. A non-`Holds` key, a
+     * non-boolean value, or a key already attached by `fields` (a
+     * same-channel collision — `fields` wins) is dropped with the matching
+     * omission counter. Relations count against the same product-side
+     * per-operation field budget as `fields` (enforced at projection).
+     *
+     * Use {@link invariant} / {@link isNullInvariant} to compute the
+     * boolean from a comparison.
+     */
+    relations?: Record<string, boolean>;
 }
 /**
  * Record allowlisted side-effect evidence on the current active OTel
@@ -143,4 +158,227 @@ interface RecordSideEffectInput {
  */
 declare function recordSideEffect(input: RecordSideEffectInput): void;
 
-export { type RecordSideEffectInput, SideEffectOperationKind, SideEffectOperationPhase, SideEffectOperationStatus, SideEffectSemanticFieldKey, recordSideEffect };
+/**
+ * Public value-capture primitive (L1 passive capture).
+ *
+ * {@link capture} emits a single allowlisted value-fidelity scalar onto a
+ * caller-**owned** OTel span. It is the counterpart to {@link
+ * recordSideEffect} for the case where the emitter owns the target span
+ * itself (e.g. a passive database adapter that opens a `db.<Model>.<op>`
+ * span) rather than attaching to the ambient active span.
+ *
+ * Why this exists: {@link recordSideEffect} is ambient-only — it resolves
+ * the active span via `getActiveSpan()`. A passive adapter cannot use it,
+ * because at its capture point the ambient span is the database client's
+ * own operation span, which has already ended and is non-recording. So the
+ * adapter must own a fresh recording span and emit onto it explicitly.
+ *
+ * The behavior contract mirrors {@link recordSideEffect}: observational
+ * only. `capture` never executes a side effect, never reads or mutates the
+ * captured value's source, and **never throws**. Every failure mode
+ * (capture-config disabled, ended / `NonRecordingSpan` target, allowlist
+ * rejection, OTel attribute-slot exhaustion) routes to a silent no-op or to
+ * an omission-counter increment that carries no rejected input.
+ *
+ * Capture is **strict-mode only**: timestamp-shaped and unhashed-identifier
+ * values are rejected at emit so they never reach the wire. The `full`
+ * fidelity relaxation is not reachable through this primitive.
+ */
+
+/** Options for {@link capture}. */
+interface CaptureOptions {
+    /**
+     * The caller-owned, recording span to attach the scalar to. `capture`
+     * writes only to this span; it never resolves or touches the ambient
+     * active span. The caller is responsible for `end()`-ing it.
+     */
+    span: Span;
+}
+/**
+ * Emit a single allowlisted value-fidelity scalar onto a caller-owned span.
+ *
+ * The scalar `name` must match the value-fidelity scalar key pattern
+ * (`*Ms` / `*Amount` / `*Bytes` / `*Ratio` / `*Id` / `*Value` / `*Flag`)
+ * and its value must match the suffix type — e.g. a `*Flag` key requires a
+ * `boolean`. Mismatches, timestamp-shaped values, and unhashed `*Id`s are
+ * rejected under strict mode and recorded as an omission count on the
+ * supplied span (never the active span).
+ *
+ * Edge cases (all silent no-ops, never throws):
+ *  - capture-config flag `sideEffectEvidence` is `false` ⇒ no-op, **no
+ *    counter** (mirrors {@link recordSideEffect}: with capture disabled the
+ *    SDK does no allowlist evaluation and writes nothing).
+ *  - the supplied span has already ended or is a `NonRecordingSpan` ⇒
+ *    no-op, **no counter** (its omission counter would itself be a dropped
+ *    span write). The owning adapter passes a fresh recording span, so this
+ *    is a caller-misuse guard.
+ *  - the value fails strict allowlist validation ⇒ an omission count is
+ *    recorded on the supplied span; the rejected value is never emitted.
+ *  - OTel attribute-slot exhaustion ⇒ the attribute write is silently
+ *    dropped.
+ *
+ * @example Project a boolean result field onto an owned database span
+ * ```ts
+ * import { capture } from "@glasstrace/sdk";
+ *
+ * const span = tracer.startSpan("db.Poll.findUnique");
+ * try {
+ *   const row = await query(args);
+ *   if (row) capture("mutedFlag", row.muted, { span });
+ *   return row;
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ */
+declare function capture(name: string, value: unknown, options: CaptureOptions): void;
+
+/**
+ * Passive Prisma value-capture adapter (L1 capture).
+ *
+ * `prismaAdapter({ allow })` returns a Prisma client extension that, for
+ * each allowlisted `(model, column)`, projects a boolean result field onto
+ * a Glasstrace value-fidelity scalar so an agent can read it back from the
+ * trace. It is **passive and observational**: it never executes a query
+ * itself, never reads or mutates the result, and never changes query
+ * behavior or errors.
+ *
+ * Apply it like any Prisma extension:
+ *
+ * ```ts
+ * import { prismaAdapter } from "@glasstrace/sdk";
+ *
+ * const prisma = new PrismaClient().$extends(
+ *   prismaAdapter({ allow: [{ model: "Poll", column: "muted" }] }),
+ * );
+ * ```
+ *
+ * Design:
+ *  - **OWN a span.** At the capture point the database client's own
+ *    operation span has already ended, so the adapter opens its own
+ *    recording `db.<Model>.<op>` span (parented under the active request
+ *    span) and emits onto it via {@link capture}.
+ *  - **Default-deny.** Nothing is captured unless an explicit `allow` entry
+ *    matches AND the server-pushed `sideEffectEvidence` capture flag is on.
+ *    An empty / unset `allow` captures nothing.
+ *  - **Boolean only.** This adapter projects boolean columns (the strict,
+ *    no-`captureFidelity:full` case). Non-boolean allowlisted columns route
+ *    to a safe omission counter, never a captured value.
+ *  - **Pure observer.** Capture work can never throw into the host query;
+ *    the owned span is always ended; the original query error is re-thrown
+ *    verbatim.
+ *  - **Bounded.** `findMany` / list operations are disabled (no per-row
+ *    capture). The adapter never widens the app's `select`.
+ *
+ * This module has **no dependency on `@prisma/client`** — it is typed
+ * structurally against Prisma's client-extension shape (mirroring the
+ * Drizzle adapter), so it adds no runtime dependency and ships on the edge-
+ * safe root barrel. On a runtime with no active request span (e.g. an edge
+ * runtime with no AsyncLocalStorage), it captures nothing.
+ */
+/** The arguments Prisma passes to a `$allOperations` query-extension callback. */
+interface PrismaAllOperationsArgs {
+    /** The Prisma model name (PascalCase, e.g. `Poll`), or `undefined` for raw ops. */
+    model?: string;
+    /** The Prisma operation (e.g. `findUnique`, `findMany`, `update`). */
+    operation: string;
+    /** The operation arguments, forwarded unchanged to `query`. */
+    args: unknown;
+    /** Executes the underlying operation. Called exactly once. */
+    query: (args: unknown) => Promise<unknown>;
+}
+/**
+ * A Prisma client extension — the object passed to `prisma.$extends(...)`.
+ * Structurally typed so the adapter needs no `@prisma/client` dependency.
+ */
+interface PrismaCaptureExtension {
+    name: string;
+    query: {
+        $allModels: {
+            $allOperations(args: PrismaAllOperationsArgs): Promise<unknown>;
+        };
+    };
+}
+/** A single allowlisted column to project. */
+interface PrismaCaptureColumn {
+    /** The Prisma model name, PascalCase, exactly as Prisma reports it (e.g. `Poll`). */
+    model: string;
+    /** The boolean result column to project (e.g. `muted`). */
+    column: string;
+}
+/** Options for {@link prismaAdapter}. */
+interface PrismaAdapterOptions {
+    /**
+     * The default-deny allowlist. Only `(model, column)` pairs listed here are
+     * eligible for capture; an empty or unset list captures nothing. The
+     * server-side per-tenant allowlist re-enforces this independently at
+     * ingestion.
+     */
+    allow?: ReadonlyArray<PrismaCaptureColumn>;
+}
+/**
+ * Build a passive Prisma value-capture extension. See the module doc for
+ * the full behavior contract.
+ */
+declare function prismaAdapter(options?: PrismaAdapterOptions): PrismaCaptureExtension;
+
+/**
+ * Producer-sugar for computing boolean relations to emit as `*Holds`
+ * side-effect evidence.
+ *
+ * These helpers turn a comparison into the boolean a producer passes to
+ * `recordSideEffect({ relations: { …Holds: invariant(a, "eq", b) } })`.
+ * They are pure (no I/O, no Node built-ins) and edge-safe, so they live
+ * on the root barrel. The operator set is intentionally minimal and
+ * fixed — six binary comparisons plus a separate unary null check — and
+ * is not a general expression DSL.
+ */
+/**
+ * The six supported binary comparison operators. `isNull` is **not** an
+ * operator here — use {@link isNullInvariant} for the unary case.
+ */
+type InvariantOp = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
+/**
+ * Evaluate a binary comparison invariant and return the boolean result.
+ *
+ * Both operands are constrained to the same primitive type. `eq`/`neq`
+ * use strict equality; the ordering operators (`lt`/`lte`/`gt`/`gte`)
+ * use the language relational operators (numeric for numbers/bigints,
+ * lexical for strings). Intended for producing a `*Holds` relation, e.g.
+ * `invariant(emittedDurationMinutes, "eq", declaredDurationMinutes)`.
+ *
+ * Operands should be comparable primitives. `NaN` follows IEEE-754
+ * (unequal to everything; all orderings `false`), so screen `NaN` before
+ * asserting a relation. Passing a non-primitive (e.g. a `Symbol`, or an
+ * object with a throwing `valueOf`) to an ordering operator throws per
+ * JS semantics — the type signature prevents this for typed callers.
+ *
+ * @param left - The left operand.
+ * @param op - One of the six {@link InvariantOp} comparisons.
+ * @param right - The right operand (same primitive type as `left`).
+ * @returns The boolean result of `left <op> right`.
+ *
+ * @example
+ * recordSideEffect({
+ *   kind: "calendar_link",
+ *   operation: "invite.create",
+ *   relations: {
+ *     durationMatchesHolds: invariant(emittedMinutes, "eq", declaredMinutes),
+ *   },
+ * });
+ */
+declare function invariant<T extends number | string | bigint | boolean>(left: T, op: InvariantOp, right: T): boolean;
+/**
+ * Unary null/undefined invariant — `true` when `value` is `null` or
+ * `undefined`. Kept separate from {@link invariant} because nullishness
+ * is a unary predicate, not a binary comparison (there is no `isNull`
+ * operator). Use for a `*Holds` relation asserting a value's absence,
+ * e.g. `relations: { recipientMissingHolds: isNullInvariant(recipient) }`.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is `null` or `undefined`, else `false`
+ *   (falsy-but-present values like `0`, `""`, `false`, `NaN` are `false`).
+ */
+declare function isNullInvariant(value: unknown): boolean;
+
+export { type CaptureOptions, type InvariantOp, type PrismaAdapterOptions, type PrismaCaptureColumn, type PrismaCaptureExtension, type RecordSideEffectInput, SideEffectOperationKind, SideEffectOperationPhase, SideEffectOperationStatus, SideEffectSemanticFieldKey, capture, invariant, isNullInvariant, prismaAdapter, recordSideEffect };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { C as CorrelationIdRequest, G as GlasstraceSpanProcessor, S as SdkError, a as SessionManager, c as captureCorrelationId, g as getDateString, b as getOrigin } from './correlation-id-B9YYmoZw.js';
-export { F as FetchTarget, G as GlasstraceExporter, a as GlasstraceExporterOptions, I as InitClaimResult, R as ResolvedConfig, c as captureError, b as classifyFetchTarget, d as createGlasstraceSpanProcessor, g as getActiveConfig, e as getDiscoveryHandler, f as getLinkedAccountId, h as getOrCreateAnonKey, i as getStatus, j as isAnonymousMode, k as isProductionDisabled, l as isReady, m as loadCachedConfig, p as performInit, r as readAnonKey, n as readEnvVars, o as registerGlasstrace, q as resolveConfig, s as saveCachedConfig, t as sendInitRequest, w as waitForReady, u as withGlasstraceConfig } from './capture-error-Dc01rYNR.js';
-import { S as SideEffectOperationKind, a as SideEffectOperationStatus, b as SideEffectOperationPhase, c as SideEffectSemanticFieldKey } from './index.d-3-cJoY8y.js';
-export { e as SideEffectOmissionReason, f as SideEffectSemanticFieldStableCoreKey, d as deriveSessionId, i as isSideEffectSemanticFieldKey } from './index.d-3-cJoY8y.js';
+export { C as CorrelationIdRequest, G as GlasstraceSpanProcessor, S as SdkError, a as SessionManager, c as captureCorrelationId, g as getDateString, b as getOrigin } from './correlation-id-Ct86Ug4s.js';
+export { F as FetchTarget, G as GlasstraceExporter, a as GlasstraceExporterOptions, I as InitClaimResult, R as ResolvedConfig, c as captureError, b as classifyFetchTarget, d as createGlasstraceSpanProcessor, g as getActiveConfig, e as getDiscoveryHandler, f as getLinkedAccountId, h as getOrCreateAnonKey, i as getStatus, j as isAnonymousMode, k as isProductionDisabled, l as isReady, m as loadCachedConfig, p as performInit, r as readAnonKey, n as readEnvVars, o as registerGlasstrace, q as resolveConfig, s as saveCachedConfig, t as sendInitRequest, w as waitForReady, u as withGlasstraceConfig } from './capture-error-BTI6mCH2.js';
+import { b as SideEffectOperationKind, c as SideEffectOperationStatus, e as SideEffectOperationPhase, f as SideEffectSemanticFieldKey } from './index.d-DhatN7mq.js';
+export { g as SideEffectOmissionReason, h as SideEffectSemanticFieldStableCoreKey, d as deriveSessionId, i as isSideEffectSemanticFieldKey } from './index.d-DhatN7mq.js';
+import { Span } from './trace/span';
 export { RequestMiddlewareFunction, TracedRequestMiddlewareOptions } from './middleware/index.js';
 export { WithAsyncCausalityOptions } from './async-context/index.js';
 import './export/ReadableSpan';
@@ -90,6 +91,20 @@ interface RecordSideEffectInput {
      * prefix), so a categorical and a scalar facet can share a name.
      */
     scalars?: Record<string, unknown>;
+    /**
+     * Optional producer-asserted boolean relations (invariants) emitted on
+     * the categorical field channel. Keys must be camelCase ending in
+     * `Holds` (e.g. `timezonePreservedHolds`); values are real `boolean`s,
+     * coerced to `"true"`/`"false"` on the wire. A non-`Holds` key, a
+     * non-boolean value, or a key already attached by `fields` (a
+     * same-channel collision — `fields` wins) is dropped with the matching
+     * omission counter. Relations count against the same product-side
+     * per-operation field budget as `fields` (enforced at projection).
+     *
+     * Use {@link invariant} / {@link isNullInvariant} to compute the
+     * boolean from a comparison.
+     */
+    relations?: Record<string, boolean>;
 }
 /**
  * Record allowlisted side-effect evidence on the current active OTel
@@ -143,4 +158,227 @@ interface RecordSideEffectInput {
  */
 declare function recordSideEffect(input: RecordSideEffectInput): void;
 
-export { type RecordSideEffectInput, SideEffectOperationKind, SideEffectOperationPhase, SideEffectOperationStatus, SideEffectSemanticFieldKey, recordSideEffect };
+/**
+ * Public value-capture primitive (L1 passive capture).
+ *
+ * {@link capture} emits a single allowlisted value-fidelity scalar onto a
+ * caller-**owned** OTel span. It is the counterpart to {@link
+ * recordSideEffect} for the case where the emitter owns the target span
+ * itself (e.g. a passive database adapter that opens a `db.<Model>.<op>`
+ * span) rather than attaching to the ambient active span.
+ *
+ * Why this exists: {@link recordSideEffect} is ambient-only — it resolves
+ * the active span via `getActiveSpan()`. A passive adapter cannot use it,
+ * because at its capture point the ambient span is the database client's
+ * own operation span, which has already ended and is non-recording. So the
+ * adapter must own a fresh recording span and emit onto it explicitly.
+ *
+ * The behavior contract mirrors {@link recordSideEffect}: observational
+ * only. `capture` never executes a side effect, never reads or mutates the
+ * captured value's source, and **never throws**. Every failure mode
+ * (capture-config disabled, ended / `NonRecordingSpan` target, allowlist
+ * rejection, OTel attribute-slot exhaustion) routes to a silent no-op or to
+ * an omission-counter increment that carries no rejected input.
+ *
+ * Capture is **strict-mode only**: timestamp-shaped and unhashed-identifier
+ * values are rejected at emit so they never reach the wire. The `full`
+ * fidelity relaxation is not reachable through this primitive.
+ */
+
+/** Options for {@link capture}. */
+interface CaptureOptions {
+    /**
+     * The caller-owned, recording span to attach the scalar to. `capture`
+     * writes only to this span; it never resolves or touches the ambient
+     * active span. The caller is responsible for `end()`-ing it.
+     */
+    span: Span;
+}
+/**
+ * Emit a single allowlisted value-fidelity scalar onto a caller-owned span.
+ *
+ * The scalar `name` must match the value-fidelity scalar key pattern
+ * (`*Ms` / `*Amount` / `*Bytes` / `*Ratio` / `*Id` / `*Value` / `*Flag`)
+ * and its value must match the suffix type — e.g. a `*Flag` key requires a
+ * `boolean`. Mismatches, timestamp-shaped values, and unhashed `*Id`s are
+ * rejected under strict mode and recorded as an omission count on the
+ * supplied span (never the active span).
+ *
+ * Edge cases (all silent no-ops, never throws):
+ *  - capture-config flag `sideEffectEvidence` is `false` ⇒ no-op, **no
+ *    counter** (mirrors {@link recordSideEffect}: with capture disabled the
+ *    SDK does no allowlist evaluation and writes nothing).
+ *  - the supplied span has already ended or is a `NonRecordingSpan` ⇒
+ *    no-op, **no counter** (its omission counter would itself be a dropped
+ *    span write). The owning adapter passes a fresh recording span, so this
+ *    is a caller-misuse guard.
+ *  - the value fails strict allowlist validation ⇒ an omission count is
+ *    recorded on the supplied span; the rejected value is never emitted.
+ *  - OTel attribute-slot exhaustion ⇒ the attribute write is silently
+ *    dropped.
+ *
+ * @example Project a boolean result field onto an owned database span
+ * ```ts
+ * import { capture } from "@glasstrace/sdk";
+ *
+ * const span = tracer.startSpan("db.Poll.findUnique");
+ * try {
+ *   const row = await query(args);
+ *   if (row) capture("mutedFlag", row.muted, { span });
+ *   return row;
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ */
+declare function capture(name: string, value: unknown, options: CaptureOptions): void;
+
+/**
+ * Passive Prisma value-capture adapter (L1 capture).
+ *
+ * `prismaAdapter({ allow })` returns a Prisma client extension that, for
+ * each allowlisted `(model, column)`, projects a boolean result field onto
+ * a Glasstrace value-fidelity scalar so an agent can read it back from the
+ * trace. It is **passive and observational**: it never executes a query
+ * itself, never reads or mutates the result, and never changes query
+ * behavior or errors.
+ *
+ * Apply it like any Prisma extension:
+ *
+ * ```ts
+ * import { prismaAdapter } from "@glasstrace/sdk";
+ *
+ * const prisma = new PrismaClient().$extends(
+ *   prismaAdapter({ allow: [{ model: "Poll", column: "muted" }] }),
+ * );
+ * ```
+ *
+ * Design:
+ *  - **OWN a span.** At the capture point the database client's own
+ *    operation span has already ended, so the adapter opens its own
+ *    recording `db.<Model>.<op>` span (parented under the active request
+ *    span) and emits onto it via {@link capture}.
+ *  - **Default-deny.** Nothing is captured unless an explicit `allow` entry
+ *    matches AND the server-pushed `sideEffectEvidence` capture flag is on.
+ *    An empty / unset `allow` captures nothing.
+ *  - **Boolean only.** This adapter projects boolean columns (the strict,
+ *    no-`captureFidelity:full` case). Non-boolean allowlisted columns route
+ *    to a safe omission counter, never a captured value.
+ *  - **Pure observer.** Capture work can never throw into the host query;
+ *    the owned span is always ended; the original query error is re-thrown
+ *    verbatim.
+ *  - **Bounded.** `findMany` / list operations are disabled (no per-row
+ *    capture). The adapter never widens the app's `select`.
+ *
+ * This module has **no dependency on `@prisma/client`** — it is typed
+ * structurally against Prisma's client-extension shape (mirroring the
+ * Drizzle adapter), so it adds no runtime dependency and ships on the edge-
+ * safe root barrel. On a runtime with no active request span (e.g. an edge
+ * runtime with no AsyncLocalStorage), it captures nothing.
+ */
+/** The arguments Prisma passes to a `$allOperations` query-extension callback. */
+interface PrismaAllOperationsArgs {
+    /** The Prisma model name (PascalCase, e.g. `Poll`), or `undefined` for raw ops. */
+    model?: string;
+    /** The Prisma operation (e.g. `findUnique`, `findMany`, `update`). */
+    operation: string;
+    /** The operation arguments, forwarded unchanged to `query`. */
+    args: unknown;
+    /** Executes the underlying operation. Called exactly once. */
+    query: (args: unknown) => Promise<unknown>;
+}
+/**
+ * A Prisma client extension — the object passed to `prisma.$extends(...)`.
+ * Structurally typed so the adapter needs no `@prisma/client` dependency.
+ */
+interface PrismaCaptureExtension {
+    name: string;
+    query: {
+        $allModels: {
+            $allOperations(args: PrismaAllOperationsArgs): Promise<unknown>;
+        };
+    };
+}
+/** A single allowlisted column to project. */
+interface PrismaCaptureColumn {
+    /** The Prisma model name, PascalCase, exactly as Prisma reports it (e.g. `Poll`). */
+    model: string;
+    /** The boolean result column to project (e.g. `muted`). */
+    column: string;
+}
+/** Options for {@link prismaAdapter}. */
+interface PrismaAdapterOptions {
+    /**
+     * The default-deny allowlist. Only `(model, column)` pairs listed here are
+     * eligible for capture; an empty or unset list captures nothing. The
+     * server-side per-tenant allowlist re-enforces this independently at
+     * ingestion.
+     */
+    allow?: ReadonlyArray<PrismaCaptureColumn>;
+}
+/**
+ * Build a passive Prisma value-capture extension. See the module doc for
+ * the full behavior contract.
+ */
+declare function prismaAdapter(options?: PrismaAdapterOptions): PrismaCaptureExtension;
+
+/**
+ * Producer-sugar for computing boolean relations to emit as `*Holds`
+ * side-effect evidence.
+ *
+ * These helpers turn a comparison into the boolean a producer passes to
+ * `recordSideEffect({ relations: { …Holds: invariant(a, "eq", b) } })`.
+ * They are pure (no I/O, no Node built-ins) and edge-safe, so they live
+ * on the root barrel. The operator set is intentionally minimal and
+ * fixed — six binary comparisons plus a separate unary null check — and
+ * is not a general expression DSL.
+ */
+/**
+ * The six supported binary comparison operators. `isNull` is **not** an
+ * operator here — use {@link isNullInvariant} for the unary case.
+ */
+type InvariantOp = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
+/**
+ * Evaluate a binary comparison invariant and return the boolean result.
+ *
+ * Both operands are constrained to the same primitive type. `eq`/`neq`
+ * use strict equality; the ordering operators (`lt`/`lte`/`gt`/`gte`)
+ * use the language relational operators (numeric for numbers/bigints,
+ * lexical for strings). Intended for producing a `*Holds` relation, e.g.
+ * `invariant(emittedDurationMinutes, "eq", declaredDurationMinutes)`.
+ *
+ * Operands should be comparable primitives. `NaN` follows IEEE-754
+ * (unequal to everything; all orderings `false`), so screen `NaN` before
+ * asserting a relation. Passing a non-primitive (e.g. a `Symbol`, or an
+ * object with a throwing `valueOf`) to an ordering operator throws per
+ * JS semantics — the type signature prevents this for typed callers.
+ *
+ * @param left - The left operand.
+ * @param op - One of the six {@link InvariantOp} comparisons.
+ * @param right - The right operand (same primitive type as `left`).
+ * @returns The boolean result of `left <op> right`.
+ *
+ * @example
+ * recordSideEffect({
+ *   kind: "calendar_link",
+ *   operation: "invite.create",
+ *   relations: {
+ *     durationMatchesHolds: invariant(emittedMinutes, "eq", declaredMinutes),
+ *   },
+ * });
+ */
+declare function invariant<T extends number | string | bigint | boolean>(left: T, op: InvariantOp, right: T): boolean;
+/**
+ * Unary null/undefined invariant — `true` when `value` is `null` or
+ * `undefined`. Kept separate from {@link invariant} because nullishness
+ * is a unary predicate, not a binary comparison (there is no `isNull`
+ * operator). Use for a `*Holds` relation asserting a value's absence,
+ * e.g. `relations: { recipientMissingHolds: isNullInvariant(recipient) }`.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is `null` or `undefined`, else `false`
+ *   (falsy-but-present values like `0`, `""`, `false`, `NaN` are `false`).
+ */
+declare function isNullInvariant(value: unknown): boolean;
+
+export { type CaptureOptions, type InvariantOp, type PrismaAdapterOptions, type PrismaCaptureColumn, type PrismaCaptureExtension, type RecordSideEffectInput, SideEffectOperationKind, SideEffectOperationPhase, SideEffectOperationStatus, SideEffectSemanticFieldKey, capture, invariant, isNullInvariant, prismaAdapter, recordSideEffect };