@vibeorm/runtime 2.0.0-alpha.9 → 2.0.1

package/dist/relation-plan.d.ts

@@ -10,7 +10,9 @@
  * - `select: { rel: … }` and `include: { rel: … }` both load; `include` wins
  *   when both name the same relation.
  * - `_count` uses the v1 shape: `include._count: true | { select: { rel: true } }`
- *   (or under `select`), counts LIST relations only, and supports no `where`.
+ *   (or under `select`) and counts LIST relations only. A count entry may also
+ *   be `{ where: … }` (EPIC 4): the filter is carried on the resolved node and
+ *   compiled by the loader through the ordinary where compiler.
  * - Implicit many-to-many resolves through the ONE shared join-table rule
  *   (`implicitJoinTable` in @vibeorm/schema) — never re-derived here.
  */
@@ -31,10 +33,15 @@ export type RelationLink = {
     readonly kind: RelationKind;
     readonly relation: RelationIR;
     readonly target: ModelMeta;
-    /** Field on the PARENT whose values correlate the two sides. */
-    readonly parentKey: FieldMeta;
-    /** Field on the CHILD whose values match `parentKey`'s. */
-    readonly childKey: FieldMeta;
+    /**
+     * ORDERED parent-side correlation fields — index `i` pairs with
+     * `childKeys[i]`. A composite foreign key carries every column here; there is
+     * deliberately no singular accessor, so no call site can truncate a tuple to
+     * its first member.
+     */
+    readonly parentKeys: readonly FieldMeta[];
+    /** ORDERED child-side correlation fields, positionally paired with {@link parentKeys}. */
+    readonly childKeys: readonly FieldMeta[];
     /** Join-table wiring; `null` unless kind is `manyToMany`. */
     readonly join: {
         readonly tableName: string;
@@ -65,11 +72,42 @@ export type RelationTreeNode = {
     readonly link: RelationLink;
     readonly args: RelationArgs;
 };
+/**
+ * One relation counted into `_count`, with the filter that narrows it.
+ *
+ * The link is resolved HERE, once, so no later consumer has to re-derive a
+ * relation's ordered key tuples just to count through them.
+ */
+export type RelationCountNode = {
+    /** List-relation field name on the parent (`posts`). */
+    readonly name: string;
+    /** Structural link the count correlates and groups on. */
+    readonly link: RelationLink;
+    /**
+     * Validated `where` narrowing the counted children, or `undefined` for
+     * "count every child". The loader compiles it with `compileWhere` — the same
+     * centralized compiler and codecs an ordinary query where goes through.
+     */
+    readonly where: Record<string, unknown> | undefined;
+};
 /** Everything relation-shaped one query level asked for. */
 export type RelationSelection = {
     readonly relations: readonly RelationTreeNode[];
-    /** List-relation names to count into `_count`. */
-    readonly counts: readonly string[];
+    /** List relations to count into `_count`, each with its own filter. */
+    readonly counts: readonly RelationCountNode[];
+};
+/**
+ * The ONE correlation pair of an arity-1 link, for the paths that are single-key
+ * by construction (implicit many-to-many, whose join table has one column per
+ * side). Refuses a composite link with a typed capability error BEFORE any
+ * statement runs — never truncates.
+ */
+export declare function singleKeyPair(params: {
+    link: RelationLink;
+    what: string;
+}): {
+    readonly parent: FieldMeta;
+    readonly child: FieldMeta;
 };
 /** Resolve how one relation is physically wired. */
 export declare function resolveRelationLink(params: {

package/dist/relation-plan.d.ts.map

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

package/dist/render-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-cache.d.ts","sourceRoot":"","sources":["../src/render-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAMV,aAAa,EAEb,UAAU,EAEV,YAAY,EAGb,MAAM,cAAc,CAAC;AAItB,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;CACnD,CAAC;AAEF,2EAA2E;AAC3E,KAAK,SAAS,GAAG,UAAU,GAAG,IAAI,CAAC;AAInC,8EAA8E;AAC9E,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEtC;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAKtC;CACF;AA0cD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,YAAY,CAAC;IACxB,KAAK,EAAE,oBAAoB,CAAC;CAC7B,GAAG,aAAa,CAoBhB"}
+{"version":3,"file":"render-cache.d.ts","sourceRoot":"","sources":["../src/render-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,KAAK,EAMV,aAAa,EAEb,UAAU,EAEV,YAAY,EAGb,MAAM,cAAc,CAAC;AAItB,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;CACnD,CAAC;AAEF,2EAA2E;AAC3E,KAAK,SAAS,GAAG,UAAU,GAAG,IAAI,CAAC;AAInC,8EAA8E;AAC9E,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEtC;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAKtC;CACF;AA2fD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,YAAY,CAAC;IACxB,KAAK,EAAE,oBAAoB,CAAC;CAC7B,GAAG,aAAa,CAoBhB"}

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

@@ -1,37 +1,6 @@
-/**
- * Tenant scoping — `$scoped` (framework handoff: one scoped handle per request).
- *
- * A CALLER-CONFIGURED row-scoping layer: the base client plus a total
- * per-model tenancy map plus a scope value produce a NEW handle whose every
- * query is structurally confined to that tenant. Complements `@@policy`
- * (schema-declared, fail-closed) — the two do NOT combine: `$scoped` refuses
- * on a client whose schema declares any `@@policy`.
- *
- * Implemented as PURE args rewriting over the built delegates (the views.ts /
- * policy.ts pattern — ZERO query-builder edits; every emitted statement is a
- * shape the catalogs already pin). The rewrite relies on three verified
- * builder properties:
- *   1. findUnique/connect wheres compile their FULL where object — extra
- *      fields and `AND` groups become filters (query-builder findUnique,
- *      nested-writes resolveTargetKey), so injecting the tenant predicate
- *      into a unique where IS the verified lookup, inside whatever
- *      transaction the write already runs.
- *   2. A guard field beyond the conflict target forces upsert onto the
- *      transactional find-then-write fallback (PG-2), whose probe honors the
- *      full where — so an injected upsert can never fire ON CONFLICT against
- *      another tenant's row.
- *   3. Cursors compile from caller-supplied values only (no row lookup), so
- *      cursor pagination needs no rewrite to stay leak-free.
- *
- * Deny-by-default: every argument node that touches a scoped model either
- * gets the predicate injected where semantics allow, or the call REFUSES with
- * a typed `ScopedQueryError { model, path, reason }` before any SQL runs.
- * Raw SQL is absent from the scoped surface; the deliberate escape is the
- * BASE client, which this layer never mutates.
- */
 import type { RelationIR } from "@vibeorm/schema";
 import type { FieldMeta, RuntimeMeta } from "./model-meta.ts";
-import type { ClientRow, DynamicClient } from "./client.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;
 /**
@@ -126,6 +95,10 @@ export declare function rewriteScopedCall(params: {
 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

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