@vibeorm/runtime 2.0.0-alpha.8 → 2.0.0

package/dist/rls-context.d.ts

@@ -0,0 +1,14 @@
+import type { SchemaIR } from "@vibeorm/schema";
+import type { SqlDialect } from "@vibeorm/sql";
+/** Private, copied identity and its total transaction-settings transport. */
+export type BoundRlsContext = {
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly settings: Readonly<Record<string, string | null>>;
+};
+/** Validate before serialization; missing nullable slots are still missing keys. */
+export declare function bindRlsContext(params: {
+    schema: SchemaIR;
+    dialect: SqlDialect;
+    context: unknown;
+}): BoundRlsContext;
+//# sourceMappingURL=rls-context.d.ts.map

package/dist/rls-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rls-context.d.ts","sourceRoot":"","sources":["../src/rls-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAoB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;CAC5D,CAAC;AA0BF,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,eAAe,CA6CnH"}

package/dist/rls-readiness.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Native-RLS readiness — verify the ACTUAL runtime privileges and the ACTUAL
+ * policy state of the live database (plan contracts 9, 11, 12, 16).
+ *
+ * What this module refuses to do is as important as what it does:
+ *  - it never trusts a migration record, a policy NAME or a policy COMMENT
+ *    (lane 3S proved a rewritten comment can make a comment check green while
+ *    the policy itself is tampered);
+ *  - it compares policy expressions as PostgreSQL's OWN deparse of a probe
+ *    policy created on a same-named TEMP clone under an empty `search_path`
+ *    — never as normalized text. Only desired deparse is cached by the client;
+ *    live expressions and privileges are read again every transaction;
+ *  - a database that will not let it verify reports `"unavailable"`, which is
+ *    NOT ready. There is no path from "could not check" to "ready".
+ *
+ * Cost and blast radius: no DDL on any live table (only `pg_temp` clones, so
+ * the live table sees an AccessShareLock, never AccessExclusiveLock), no role
+ * switch, no context binding, no schema or role provisioning of any kind, and
+ * `search_path` saved and restored inside the probe's own savepoint. Nothing
+ * about live readiness is cached. Reconnect invalidates desired deparse too.
+ * Within one backend generation, desired deparse may be stale after privileged
+ * dependency changes that leave identical expression text; this is not an
+ * instantaneous-revocation guarantee. Standalone doctor checks never cache.
+ */
+import type { Provider, SchemaIR } from "@vibeorm/schema";
+import type { DatabaseAdapter } from "./adapter.ts";
+/** Stable identifier of one readiness check; callers branch on this, never on text. */
+export type NativeRlsCheckName = "runtime-role-identity" | "runtime-role-privileges" | "elevated-role-membership" | "schema-control" | "table-ownership" | "table-truncate-privilege" | "row-level-security-enabled" | "row-level-security-forced" | "managed-policy-present" | "managed-policy-shape" | "unexpected-policy" | "managed-policy-expression" | "unsafe-objects";
+/**
+ * `"unavailable"` means the database would not let this check run (no TEMP
+ * privilege, an unreadable catalog flag). It blocks readiness exactly like
+ * `"fail"` — the two differ only in what a human should do about them.
+ * `"warn"` is a reported limitation that does not block: the PGlite session
+ * role, and the presence of unsafe objects (contract 16 reports them).
+ */
+export type NativeRlsCheckStatus = "pass" | "warn" | "fail" | "unavailable";
+/** One verified fact about the live database. */
+export type NativeRlsCheck = {
+    readonly name: NativeRlsCheckName;
+    readonly status: NativeRlsCheckStatus;
+    readonly detail: string;
+    /** Offending tables, roles or objects — never a context or identity VALUE. */
+    readonly subjects: readonly string[];
+};
+/** An object that can execute with an authority other than the caller's. */
+export type NativeRlsUnsafeObject = {
+    readonly kind: "view" | "materializedView" | "securityDefinerRoutine" | "trigger";
+    /** `public.order_report`, `public.escalate`, `public.orders.audit_orders`. */
+    readonly name: string;
+    readonly owner: string;
+    readonly detail: string;
+};
+/** The full readiness verdict. Built fresh on every call — never cached. */
+export type NativeRlsReport = {
+    /** True only when every check is `"pass"` or `"warn"`. */
+    readonly ready: boolean;
+    readonly currentRole: string;
+    readonly sessionRole: string;
+    readonly provider: Provider;
+    readonly serverVersionNum: number | null;
+    /** Physical tables of every model carrying a rule other than `"unprotected"`. */
+    readonly tables: readonly string[];
+    readonly checks: readonly NativeRlsCheck[];
+    /** The `"fail"` / `"unavailable"` subset — what makes `ready` false. */
+    readonly problems: readonly NativeRlsCheck[];
+    readonly unsafeObjects: readonly NativeRlsUnsafeObject[];
+};
+export { RLS_READINESS_SQL, NATIVE_RLS_PROBE_POLICY } from "@vibeorm/sql";
+/**
+ * Verify readiness inside a transaction that is ALREADY bound — the role is
+ * bound (PGlite) or logged in (server), the context settings are set, and the
+ * caller's own statements will run in this same transaction.
+ *
+ * Binds nothing itself: no role switch, no context setting, and the
+ * `search_path` it needs is emptied and restored inside its own savepoint, so
+ * the caller's statements are unaffected. Safe to call twice in one
+ * transaction — the temp clones are dropped before it returns.
+ *
+ * @param runtimeRole Compared against `current_user` when supplied. NEVER used
+ *   to switch role: that binding belongs to the caller.
+ */
+export declare function inspectNativeRlsTransaction(params: {
+    adapter: DatabaseAdapter;
+    schema: SchemaIR;
+    runtimeRole?: string;
+    /** Client identity scopes desired-expression reuse; omit for a fresh doctor probe.
+     * Live facts are never cached. Reuse requires a readable backend pid/start time. */
+    cacheKey?: object;
+}): Promise<NativeRlsReport>;
+/**
+ * Verify readiness on an adapter that is not already inside a bound
+ * transaction — `vibeorm doctor`, or a one-off connection check. Opens one
+ * transaction and, on PGlite only, binds the configured runtime role as its
+ * first statement. A server connection is never switched: its login role IS
+ * the runtime role, and a supplied `runtimeRole` is only compared with it.
+ */
+export declare function inspectNativeRls(params: {
+    adapter: DatabaseAdapter;
+    schema: SchemaIR;
+    runtimeRole?: string;
+}): Promise<NativeRlsReport>;
+/**
+ * Refuse to proceed on a database that is not ready. `meta.checks` names every
+ * check that failed or could not be run — callers branch on those stable
+ * names, never on this message.
+ */
+export declare function assertNativeRlsReady(params: {
+    report: NativeRlsReport;
+}): void;
+/** One line per check plus one per unsafe object — `vibeorm doctor`'s output. */
+export declare function formatNativeRlsReport(params: {
+    report: NativeRlsReport;
+}): string[];
+//# sourceMappingURL=rls-readiness.d.ts.map

package/dist/rls-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rls-readiness.d.ts","sourceRoot":"","sources":["../src/rls-readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAW,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAIpD,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAC1B,uBAAuB,GACvB,yBAAyB,GACzB,0BAA0B,GAC1B,gBAAgB,GAChB,iBAAiB,GACjB,0BAA0B,GAC1B,4BAA4B,GAC5B,2BAA2B,GAC3B,wBAAwB,GACxB,sBAAsB,GACtB,mBAAmB,GACnB,2BAA2B,GAC3B,gBAAgB,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;AAE5E,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,wBAAwB,GAAG,SAAS,CAAC;IAClF,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC1D,CAAC;AAGF,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AA4hB1E;;;;;;;;;;;;GAYG;AACH,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;wFACoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,eAAe,CAAC,CA2H3B;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiB3B;AAgBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,eAAe,CAAA;CAAE,GAAG,IAAI,CAc9E;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,eAAe,CAAA;CAAE,GAAG,MAAM,EAAE,CAanF"}

package/dist/scoped.d.ts

@@ -0,0 +1,104 @@
+import type { RelationIR } from "@vibeorm/schema";
+import type { FieldMeta, RuntimeMeta } from "./model-meta.ts";
+import type { ClientRow, DynamicClient, ModelDelegate } from "./client.ts";
+/** Scope values a tenant column can carry (matches String / Int / BigInt columns). */
+export type ScopeValue = string | number | bigint;
+/**
+ * What happens when a scoped model appears as a CHILD inside another model's
+ * nested write: `"verify"` (default) rewrites reference verbs into
+ * tenant-verified lookups; `"refuse"` rejects every reference verb (nested
+ * `create` stays allowed under both — it is forced into the tenant).
+ */
+export type ScopedNestedMode = "verify" | "refuse";
+/** One model's classification in the tenancy map. */
+export type ScopedModelEntry = "none" | {
+    readonly column: string;
+    readonly nested?: ScopedNestedMode;
+} | {
+    readonly through: string;
+    readonly nested?: ScopedNestedMode;
+};
+/** The per-model tenancy map — must classify EVERY model (totality). */
+export type ScopedModelsMap = Readonly<Record<string, ScopedModelEntry>>;
+/** The `$scoped` argument. */
+export type ScopedClientConfig = {
+    readonly scope: ScopeValue | null;
+    readonly models: ScopedModelsMap;
+};
+type ResolvedEntry = {
+    readonly kind: "none";
+} | {
+    readonly kind: "column";
+    readonly field: FieldMeta;
+    readonly nested: ScopedNestedMode;
+} | {
+    readonly kind: "through";
+    readonly relation: RelationIR;
+    readonly targetModel: string;
+    readonly nested: ScopedNestedMode;
+};
+type ResolvedScopedModels = ReadonlyMap<string, ResolvedEntry>;
+/**
+ * Validate the models map against the runtime meta: totality, known
+ * columns/relations, scopeable column types, acyclic through-chains ending on
+ * a { column } model. Cached by (map, meta) object identity — the framework
+ * holds one map constant and calls `$scoped` per request.
+ */
+export declare function resolveScopedModels(params: {
+    meta: RuntimeMeta;
+    models: ScopedModelsMap;
+}): ResolvedScopedModels;
+/** A rewritten call: which base-delegate method to run, with which args. */
+export type RewrittenScopedCall = {
+    readonly model: string;
+    readonly method: string;
+    readonly args: ClientRow | undefined;
+};
+/** A validated, scope-bound rewriter — the pure core a binding's tests drive. */
+export type ScopeRewriter = {
+    readonly rewrite: (call: {
+        model: string;
+        method: string;
+        args?: ClientRow;
+    }) => RewrittenScopedCall;
+};
+/**
+ * Validate a models map + scope against the runtime meta and return the pure
+ * per-call rewriter (`ScopedQueryError` on refusals). This is `$scoped`'s
+ * engine without the client plumbing — conformance rewrite-vectors run here.
+ */
+export declare function createScopeRewriter(params: {
+    meta: RuntimeMeta;
+    models: ScopedModelsMap;
+    scope: ScopeValue | null;
+}): ScopeRewriter;
+/**
+ * Rewrite ONE delegate call for a scoped handle — pure: same inputs, same
+ * output; refusals throw `ScopedQueryError` before any SQL could run. This is
+ * the function the conformance rewrite-vectors pin.
+ */
+export declare function rewriteScopedCall(params: {
+    meta: RuntimeMeta;
+    resolved: ResolvedScopedModels;
+    scope: ScopeValue | null;
+    preds: ReadonlyMap<string, ClientRow | null>;
+    model: string;
+    method: string;
+    args: ClientRow | undefined;
+}): RewrittenScopedCall;
+/**
+ * Attach `$scoped` to a built client. Validation happens per call:
+ * `@@policy` schemas refuse (the two scoping layers do not combine), the
+ * models map is resolved against the schema (cached by object identity), and
+ * the scope value is type-checked against every scoped column.
+ */
+export declare function attachScoped(params: {
+    client: DynamicClient;
+    meta: RuntimeMeta;
+    wrapDelegate?: (params: {
+        model: string;
+        delegate: ModelDelegate;
+    }) => ModelDelegate;
+}): void;
+export {};
+//# sourceMappingURL=scoped.d.ts.map

package/dist/scoped.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped.d.ts","sourceRoot":"","sources":["../src/scoped.ts"],"names":[],"mappings":"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"}

package/dist/strict-args.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Strict argument handling (EPIC 2) — ON BY DEFAULT.
+ *
+ * Legacy (and Prisma's own default) semantics treat `where: { tenantId: undefined }`
+ * exactly like `where: {}`: the member vanishes and a bulk write silently widens
+ * to every row. That is the single most expensive footgun in an ORM argument
+ * object, and it is invisible in review because the *code* names the filter.
+ *
+ * So an explicit `undefined` anywhere in ORM argument SYNTAX is refused before a
+ * statement is built, and `SKIP` is the deliberate way to say "omit this
+ * property". `strictArguments: false` on the client opts out and restores the
+ * legacy behaviour; only that explicit `false` does — an options object that
+ * never mentions the flag stays strict.
+ *
+ * What is NOT argument syntax, and is therefore never inspected:
+ *   - anything under a `Json`-typed field (a JSON document's own keys are data,
+ *     exactly as `validators.ts` and the query builder already treat them);
+ *   - non-plain objects (`Date`, `Uint8Array`, `Decimal`, any class instance);
+ *   - symbol-keyed properties.
+ */
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+/**
+ * Omit a property deliberately: `{ where: { tenantId: SKIP } }` compiles exactly
+ * like `{ where: {} }`, in strict mode and in legacy mode alike.
+ *
+ * A globally registered symbol, so a consumer that cannot import the runtime
+ * (a generated-client-only app, a serialized argument builder) can name the very
+ * same value with `Symbol.for("vibeorm.skip")`.
+ *
+ * Named `SKIP`, not `skip`: `skip` is already a pagination argument, and
+ * `{ take: 10, skip: SKIP }` must not read as two meanings of one word.
+ */
+export declare const SKIP: unique symbol;
+/** The type of the {@link SKIP} sentinel. */
+export type Skip = typeof SKIP;
+/**
+ * Check one public call's arguments. Runs BEFORE any wrapper can discard an
+ * undefined member and before a statement is built, so a refused root operation
+ * dispatches nothing at all.
+ */
+export declare function checkStrictArguments(params: {
+    readonly meta: RuntimeMeta;
+    readonly model: ModelMeta;
+    readonly method: string;
+    readonly args: Record<string, unknown> | undefined;
+}): Record<string, unknown> | undefined;
+//# sourceMappingURL=strict-args.d.ts.map

package/dist/strict-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict-args.d.ts","sourceRoot":"","sources":["../src/strict-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAI9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,EAAE,OAAO,MAAkD,CAAC;AAE7E,6CAA6C;AAC7C,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC;AAsH/B;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACpD,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAMtC"}

package/dist/telemetry/collector.d.ts

@@ -0,0 +1,53 @@
+/**
+ * An in-memory collector — the ONLY exporter this repository ships.
+ *
+ * Its purpose is tests and local inspection: assert the emitted operation tree,
+ * the statement records and the database outcome together. It is deliberately
+ * not a monitoring integration; a real deployment writes its own exporter (or a
+ * future, separately decided OpenTelemetry bridge).
+ *
+ * `throwOn` makes it hostile on demand — the fixture that proves a throwing
+ * exporter cannot change a database outcome.
+ */
+import type { TelemetryDropEvent, TelemetryExportPhase, TelemetryExporter, TelemetryOperationEvent, TelemetryStatementEvent } from "./types.ts";
+/** One operation with the operations that ran inside it. */
+export type TelemetryOperationNode = {
+    readonly event: TelemetryOperationEvent;
+    readonly children: readonly TelemetryOperationNode[];
+};
+/** The collector handle: the exporter to pass to the client, plus what it saw. */
+export type TelemetryCollector = {
+    /** Pass this as `telemetry.exporter`. */
+    readonly exporter: TelemetryExporter;
+    readonly operations: readonly TelemetryOperationEvent[];
+    readonly statements: readonly TelemetryStatementEvent[];
+    readonly drops: readonly TelemetryDropEvent[];
+    readonly flushes: () => number;
+    readonly shutdowns: () => number;
+    readonly reset: () => void;
+    /** Operations as a parent/child tree, roots first, each level in emission order. */
+    readonly tree: () => readonly TelemetryOperationNode[];
+    /** Every operation whose `parentOperationId` is the given id, in emission order. */
+    readonly childrenOf: (params: {
+        operationId: string;
+    }) => readonly TelemetryOperationEvent[];
+    /** The single operation for a model method, or `undefined`; throws VIBE_VALIDATION when several match. */
+    readonly operationFor: (params: {
+        model?: string;
+        method: string;
+    }) => TelemetryOperationEvent | undefined;
+};
+/**
+ * Build a collector.
+ *
+ * @example
+ * const collector = createTelemetryCollector();
+ * const db = VibeClient({ adapter, telemetry: { exporter: collector.exporter } });
+ * await db.user.findMany();
+ * expect(collector.operations).toHaveLength(1);
+ */
+export declare function createTelemetryCollector(params?: {
+    /** Callbacks that inject VIBE_INTERNAL, to prove the database outcome does not depend on the exporter. */
+    readonly throwOn?: readonly TelemetryExportPhase[];
+}): TelemetryCollector;
+//# sourceMappingURL=collector.d.ts.map

package/dist/telemetry/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/telemetry/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,4DAA4D;AAC5D,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACtD,CAAC;AAEF,kFAAkF;AAClF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,SAAS,sBAAsB,EAAE,CAAC;IACvD,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,SAAS,uBAAuB,EAAE,CAAC;IAC7F,0GAA0G;IAC1G,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,uBAAuB,GAAG,SAAS,CAAC;CAC5G,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE;IAChD,0GAA0G;IAC1G,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACpD,GAAG,kBAAkB,CAyFrB"}

package/dist/telemetry/config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * THE telemetry config module (EPIC 1). Every threshold, limit and sampling
+ * default lives here and nowhere else — no magic literal for telemetry may
+ * appear in the recorder, the client or an adapter.
+ *
+ * Invalid configuration fails loudly at client construction with
+ * `VIBE_CONFIG`, not silently at the first query.
+ */
+import type { TelemetryDelivery, TelemetryOptions, TelemetrySamplerInput } from "./types.ts";
+/** Documented defaults. Privacy-conservative: nothing sensitive is captured unless asked for. */
+export type TelemetryDefaults = {
+    readonly captureSql: false;
+    readonly captureParameterValues: false;
+    readonly detailedTimings: false;
+    readonly sampleRate: 1;
+    readonly delivery: "immediate";
+    readonly maxBufferedOperations: 1024;
+    readonly maxStatementsPerOperation: 256;
+    readonly slowStatementMs: 200;
+    readonly slowOperationMs: 500;
+    /** Longest fingerprint kept; longer normalized text is truncated with a stable suffix. */
+    readonly maxFingerprintLength: 512;
+    /** Histogram bucket bounds in milliseconds (upper-inclusive), plus an overflow bucket. */
+    readonly latencyBucketsMs: readonly [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000];
+};
+export declare const TELEMETRY_DEFAULTS: TelemetryDefaults;
+/** Every option resolved to a concrete value — what the recorder reads. */
+export type ResolvedTelemetryConfig = {
+    readonly captureSql: boolean;
+    readonly captureParameterValues: boolean;
+    readonly detailedTimings: boolean;
+    readonly sampleRate: number;
+    readonly sampler?: (input: TelemetrySamplerInput) => boolean;
+    readonly context?: () => unknown;
+    readonly delivery: TelemetryDelivery;
+    readonly maxBufferedOperations: number;
+    readonly maxStatementsPerOperation: number;
+    readonly slowStatementMs: number;
+    readonly slowOperationMs: number;
+    readonly maxFingerprintLength: number;
+    readonly latencyBucketsMs: readonly number[];
+};
+/**
+ * Validate and resolve `ClientOptions.telemetry`.
+ *
+ * @throws VibeError VIBE_CONFIG when the exporter is missing, the sample rate is
+ * outside 0..1, a limit is not a positive integer, a threshold is negative, or
+ * `delivery` is not one of the two documented modes.
+ */
+export declare function resolveTelemetryConfig(params: {
+    options: TelemetryOptions;
+}): ResolvedTelemetryConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/telemetry/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/telemetry/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAI7F,iGAAiG;AACjG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;IAC3B,QAAQ,CAAC,sBAAsB,EAAE,KAAK,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,KAAK,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,qBAAqB,EAAE,IAAI,CAAC;IACrC,QAAQ,CAAC,yBAAyB,EAAE,GAAG,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC;IAC9B,0FAA0F;IAC1F,QAAQ,CAAC,oBAAoB,EAAE,GAAG,CAAC;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;CACzF,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,iBAc/B,CAAC;AAIH,2EAA2E;AAC3E,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,OAAO,CAAC;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C,CAAC;AA4BF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,gBAAgB,CAAA;CAAE,GAAG,uBAAuB,CA4CrG"}

package/dist/telemetry/fingerprint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Stable, normalized query fingerprints for grouping (EPIC 1).
+ *
+ * A fingerprint is what a metrics backend may safely use as a label: bounded in
+ * length, free of literals, free of identifiers that carry data (request ids,
+ * tenant ids, URLs), and identical across executions of the same query shape.
+ *
+ * ORM-rendered SQL is already literal-free (every value is a placeholder), so
+ * normalization exists mainly for raw SQL, where a caller may have inlined
+ * literals. Normalization removes them BEFORE hashing, so a fingerprint can
+ * never leak a value even when raw text is never captured.
+ */
+/**
+ * Reduce SQL text to its shape: comments removed, string and numeric literals
+ * replaced by `?`, placeholder numbering flattened, whitespace collapsed.
+ *
+ * @example
+ * normalizeSql({ text: `SELECT * FROM "User" WHERE id = 42 AND name = 'bob'` });
+ * // 'SELECT * FROM "User" WHERE id = ? AND name = ?'
+ */
+export declare function normalizeSql(params: {
+    text: string;
+}): string;
+/**
+ * Build the grouping key for one statement: `model.method#hash` (raw SQL uses
+ * `raw` as the model). Always bounded by `maxLength`.
+ *
+ * @example
+ * queryFingerprint({ model: "User", method: "findMany", text: sql, maxLength: 512 });
+ * // 'User.findMany#3d0a91b2'
+ */
+export declare function queryFingerprint(params: {
+    model: string | null;
+    method: string;
+    text: string;
+    maxLength: number;
+}): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/telemetry/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/telemetry/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAqD7D;AAcD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAQT"}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@vibeorm/runtime` telemetry — the vendor-neutral observability seam.
+ *
+ * This is the MODULE barrel for `src/telemetry/**`, not the package's root
+ * barrel. See the lane's hand-off note for the one-line addition that makes
+ * these types public from `@vibeorm/runtime` itself.
+ */
+export { TELEMETRY_DEFAULTS, resolveTelemetryConfig } from "./config.ts";
+export type { ResolvedTelemetryConfig, TelemetryDefaults } from "./config.ts";
+export { normalizeSql, queryFingerprint } from "./fingerprint.ts";
+export { createTelemetryRecorder } from "./recorder.ts";
+export type { TelemetryBeginInput, TelemetryOperationScope, TelemetryRecorder, TelemetrySettleInput, TelemetryStatementInput, } from "./recorder.ts";
+export { instrumentStatement } from "./statement.ts";
+export type { InstrumentStatementInput, StatementReport } from "./statement.ts";
+export { createTelemetryCollector } from "./collector.ts";
+export type { TelemetryCollector, TelemetryOperationNode } from "./collector.ts";
+export type { TelemetryDelivery, TelemetryDropEvent, TelemetryExportPhase, TelemetryExporter, TelemetryHandle, TelemetryHistogram, TelemetryMetricsSnapshot, TelemetryOperationEvent, TelemetryOperationKind, TelemetryOptions, TelemetryOutcome, TelemetryParentContext, TelemetrySamplerInput, TelemetryStage, TelemetryStatementEvent, TelemetryStatementKind, TelemetryTimingDetail, } from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAElE,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEjF,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,cAAc,EACd,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/telemetry/recorder.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The recorder: one per client, owning operation identity, sampling, bounded
+ * buffering, drop accounting, metrics and every guarded exporter call.
+ *
+ * Three invariants this module exists to hold:
+ *
+ *  1. **Exactly one terminal operation outcome.** `settle()` is idempotent —
+ *     success, refusal before dispatch, validation failure, adapter failure,
+ *     decode failure and commit/rollback failure all end in one event, and a
+ *     later duplicate settle is ignored rather than emitting a second span.
+ *  2. **The database never depends on the exporter.** Every exporter callback
+ *     runs inside a guard; a throw is reported to `onExporterError` (itself
+ *     guarded) and swallowed. No exporter can change a query's arguments, its
+ *     results or whether it committed.
+ *  3. **Nothing unknown is invented.** Absent row counts, absent durations and
+ *     absent timing subdivisions stay absent.
+ */
+import type { Dialect, Provider } from "@vibeorm/schema";
+import type { ResolvedTelemetryConfig } from "./config.ts";
+import type { TelemetryMetricsSnapshot, TelemetryOperationKind, TelemetryOptions, TelemetryOutcome, TelemetryStage, TelemetryStatementKind } from "./types.ts";
+/** What starting an operation needs to know. */
+export type TelemetryBeginInput = {
+    readonly kind: TelemetryOperationKind;
+    readonly model: string | null;
+    readonly method: string;
+    readonly dialect: Dialect;
+    readonly provider: Provider;
+    /** The enclosing transaction/extension operation, when there is one. */
+    readonly parentOperationId?: string;
+};
+/** One finished statement, reported by the execution path that ran it. */
+export type TelemetryStatementInput = {
+    readonly kind: TelemetryStatementKind;
+    readonly model: string | null;
+    readonly method: string;
+    readonly text: string;
+    readonly values: readonly unknown[];
+    readonly inTransaction: boolean;
+    readonly durationMs: number;
+    readonly outcome: TelemetryOutcome;
+    /** Absent when this path cannot know it. */
+    readonly rowCount?: number;
+    readonly error?: unknown;
+    /** Time spent rendering this statement, when measured. */
+    readonly renderMs?: number;
+};
+/** How an operation ended. */
+export type TelemetrySettleInput = {
+    readonly outcome: TelemetryOutcome;
+    /** Named only where the caller genuinely knows better than the derivation below. */
+    readonly stage?: TelemetryStage;
+    readonly error?: unknown;
+    /** Rows the operation is known to have produced or affected. */
+    readonly rowCount?: number;
+};
+/** The per-operation handle the client threads through its engine. */
+export type TelemetryOperationScope = {
+    readonly id: string;
+    /** False when sampling declined this operation: statements and the span are skipped, counters are not. */
+    readonly sampled: boolean;
+    /** Mark ACTUAL dispatch. Idempotent; the first call starts the operation clock. */
+    readonly dispatch: () => void;
+    /**
+     * Re-attach this operation to the parent that actually executes it. An array
+     * `$transaction` member is created in one context and executed by another;
+     * the executing transaction is the truthful parent.
+     */
+    readonly reparent: (params: {
+        parentOperationId: string;
+    }) => void;
+    readonly statement: (input: TelemetryStatementInput) => void;
+    /** Terminal outcome. Idempotent — only the first call emits. */
+    readonly settle: (input: TelemetrySettleInput) => void;
+};
+/** One client's telemetry. */
+export type TelemetryRecorder = {
+    readonly config: ResolvedTelemetryConfig;
+    readonly begin: (input: TelemetryBeginInput) => TelemetryOperationScope;
+    /** Drain buffered operations and ask the exporter to flush. Never shuts anything down. */
+    readonly flush: () => Promise<void>;
+    /** Host-owned: drains, then calls `exporter.shutdown`. The client never calls this. */
+    readonly shutdown: () => Promise<void>;
+    readonly metrics: () => TelemetryMetricsSnapshot;
+};
+/**
+ * Build a recorder from validated options.
+ *
+ * @throws VibeError VIBE_CONFIG when the options are invalid (see `resolveTelemetryConfig`).
+ */
+export declare function createTelemetryRecorder(params: {
+    options: TelemetryOptions;
+}): TelemetryRecorder;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/telemetry/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/telemetry/recorder.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/statement.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The single statement-instrumentation seam.
+ *
+ * Every SQL execution in the client goes through here so that the legacy
+ * `onQuery` / `$on("query")` contract and the new telemetry path are reported
+ * from ONE place with unchanged semantics:
+ *
+ *   - the legacy report still fires only after the adapter SUCCEEDS, before row
+ *     materialization, with the same payload it always had;
+ *   - telemetry additionally records FAILED statements, which the legacy path
+ *     has never seen;
+ *   - with neither observer present nothing is measured at all — no clock read,
+ *     no allocation.
+ */
+import type { TelemetryOperationScope } from "./recorder.ts";
+import type { TelemetryStatementKind } from "./types.ts";
+/**
+ * The legacy per-statement payload. Structurally identical to the client's
+ * `QueryEvent`; declared here so the telemetry module never imports the client
+ * (which imports this one).
+ */
+export type StatementReport = {
+    readonly model: string | null;
+    readonly method: string;
+    readonly text: string;
+    readonly values: readonly unknown[];
+    readonly durationMs: number;
+};
+/** What `instrumentStatement` needs; `run` is the adapter call itself. */
+export type InstrumentStatementInput<T> = {
+    readonly scope: TelemetryOperationScope | undefined;
+    /** Legacy `onQuery`/`$on` sink, or `undefined` when nobody is listening. */
+    readonly legacy: ((report: StatementReport) => void) | undefined;
+    readonly kind: TelemetryStatementKind;
+    readonly model: string | null;
+    readonly method: string;
+    readonly text: string;
+    readonly values: readonly unknown[];
+    readonly inTransaction: boolean;
+    /** Rendering time for this statement, when it was measured. */
+    readonly renderMs?: number;
+    /** Reads a known row count off the adapter result; return `undefined` when unknowable. */
+    readonly rowCount?: (value: T) => number | undefined;
+    readonly run: () => Promise<T>;
+};
+/**
+ * Run one statement with observation attached.
+ *
+ * The adapter's own result and its rejection are passed through untouched: an
+ * observer can never change what a query returns or whether it fails.
+ */
+export declare function instrumentStatement<T>(params: InstrumentStatementInput<T>): Promise<T>;
+//# sourceMappingURL=statement.d.ts.map

package/dist/telemetry/statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement.d.ts","sourceRoot":"","sources":["../../src/telemetry/statement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAA2B,MAAM,eAAe,CAAC;AACtF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI;IACxC,QAAQ,CAAC,KAAK,EAAE,uBAAuB,GAAG,SAAS,CAAC;IACpD,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAmD5F"}