@vibeorm/runtime 1.3.0 → 2.0.0-alpha.10

package/dist/codecs.d.ts.map

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

package/dist/computed.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Runtime side of computed fields (config-declared derived result properties).
+ *
+ * The runtime stays config-AGNOSTIC the same way it is extension-agnostic:
+ * `createClient({ computed })` receives the live spec object plus the baked
+ * manifest from the generated client, verifies them against each other
+ * (VIBE_STALE_CLIENT before the first query), folds the specs into the model
+ * metadata, and `applyComputedFields` runs the compute functions at every row
+ * materialization point — top-level rows, mutation returns, and relation-loaded
+ * children on BOTH strategies (the codec lesson from LEARNINGS, applied to
+ * computes).
+ */
+import type { ComputedConfig, ComputedManifestEntry } from "@vibeorm/schema";
+import type { ModelMeta } from "./model-meta.ts";
+/** Computed-field wiring accepted by `createClient`. */
+export type ClientComputedOptions = {
+    /** The live spec object (`vibeorm.config.ts`'s `computed`) — provides the compute functions. */
+    readonly specs?: ComputedConfig;
+    /** Manifest baked by the generator — presence turns on the staleness check. */
+    readonly manifest?: readonly ComputedManifestEntry[];
+};
+/**
+ * Compare the generated client's baked computed manifest against the live
+ * config. Any drift — missing, added, type or needs change — throws
+ * `VIBE_STALE_CLIENT` at construction instead of an untyped (or missing)
+ * property surprise at query time.
+ */
+export declare function assertComputedManifest(params: {
+    manifest: readonly ComputedManifestEntry[];
+    specs: ComputedConfig | undefined;
+}): void;
+/**
+ * Attach the named computed fields to each row, in place. Runs BEFORE
+ * projection narrows rows to `resultFields`, so `needs` scalars are present
+ * even when the caller did not select them. `names` is always a concrete list
+ * (the builder resolves "all" at plan time); `null` means nothing to do.
+ */
+export declare function applyComputedFields(params: {
+    model: ModelMeta;
+    rows: readonly Record<string, unknown>[];
+    names: readonly string[] | null;
+}): void;
+//# sourceMappingURL=computed.d.ts.map

package/dist/computed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../src/computed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAAG;IAClC,gGAAgG;IAChG,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACtD,CAAC;AAWF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3C,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC;CACnC,GAAG,IAAI,CAqCP;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACzC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACjC,GAAG,IAAI,CAWP"}

package/dist/db-now.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `dbNow()` — the DATABASE clock as a value.
+ *
+ * Leases, TTLs and expiry comparisons must trust the database's clock, never
+ * the process's ("a process that slept past its own expiry cannot argue with
+ * this comparison"). The sentinel rides DateTime positions:
+ *
+ * - create/update data values: `data: { expiresAt: dbNow({ plusSeconds: 30 }) }`
+ * - DateTime filters: `where: { expiresAt: { lt: dbNow() } }`
+ *
+ * and compiles to the dialect's own expression (`now()`, `NOW(6)`, an
+ * ISO-8601 `strftime` on sqlite) — the offset binds as a parameter, the
+ * expression is never string-built from caller input.
+ *
+ * Deliberately NOT a generic SQL escape hatch: the closed shape keeps every
+ * rendering reviewable in the SQL catalog (constitution rule 3).
+ */
+/** The database-clock sentinel produced by {@link dbNow}. */
+export type DbNow = {
+    readonly __vibeDbNow: true;
+    /** Seconds added to the database's now() (fractional OK; negative = past). */
+    readonly offsetSeconds: number;
+};
+/**
+ * Build a database-clock sentinel for DateTime data values and filters.
+ *
+ * @example Lease acquisition on the database's clock
+ * ```ts
+ * await tx.lease.update({
+ *   where: { id },
+ *   data: { expiresAt: dbNow({ plusSeconds: 30 }) },
+ * });
+ * const expired = await db.lease.findMany({ where: { expiresAt: { lt: dbNow() } } });
+ * ```
+ */
+export declare function dbNow(options?: {
+    readonly plusSeconds?: number;
+}): DbNow;
+/** Narrow a value to the {@link dbNow} sentinel (exact two-key shape). */
+export declare function isDbNow(value: unknown): value is DbNow;
+//# sourceMappingURL=db-now.d.ts.map

package/dist/db-now.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-now.d.ts","sourceRoot":"","sources":["../src/db-now.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,6DAA6D;AAC7D,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAUxE;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAYtD"}

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@vibeorm/runtime` diagnostics (EPIC 5): SQL preview, PostgreSQL plan
+ * inspection, read-only workload statistics and deterministic evidence reading.
+ *
+ * Module barrel — the package's root barrel re-exports from here.
+ */
+export { parameterTypeTag, previewOperation } from "./preview.ts";
+export { PLAN_DEFAULTS, explainOperation, explainSql, parsePostgresPlan } from "./plan.ts";
+export { readWorkloadStatistics } from "./workload.ts";
+export { DIAGNOSTIC_THRESHOLDS, analyzeOperationTelemetry, recommendFromPlan } from "./insight.ts";
+export type { DiagnosticFinding, DiagnosticFindingCode, ExplainMode, IndexCandidate, IndexFacts, OperationPreview, ParsedPlan, PlanContext, PlanNode, PreviewLimitation, PreviewLimitationCode, PreviewStatement, QueryPlanReport, SlowOperation, SuspectedPattern, TableFacts, TelemetryDiagnosticReport, WorkloadAvailability, WorkloadReport, WorkloadStatement, } from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/diagnostics/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC3F,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnG,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,yBAAyB,EACzB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/diagnostics/insight.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Deterministic reading of evidence (EPIC 5): repeated-statement patterns from
+ * EPIC 1's operation telemetry, and plan findings from an actual plan.
+ *
+ * Every claim here is bounded, reproducible and traceable to a number that was
+ * measured. What it deliberately does NOT do:
+ *
+ *  - it never calls a repeated statement an N+1 defect. Repetition is a
+ *    SUSPECTED pattern; a deliberate batch is normal work, and one batched
+ *    statement with a big `IN` list is never flagged.
+ *  - it never calls a sequential scan an index defect on its own. On a small
+ *    table a sequential scan is the correct plan, and it says so.
+ *  - it never claims to explain a pool wait or a lock wait. Neither is visible
+ *    in a plan, estimated or actual.
+ *  - it never creates, ranks or auto-applies an index. A missing-index note is
+ *    a CANDIDATE, carrying the predicate context, the indexes that already
+ *    exist and the write/storage cost a human has to weigh.
+ */
+import type { TelemetryOperationEvent } from "../telemetry/types.ts";
+import type { DiagnosticFinding, IndexFacts, QueryPlanReport, TableFacts, TelemetryDiagnosticReport } from "./types.ts";
+/** Every window and threshold, in one frozen table. All are bounded. */
+export declare const DIAGNOSTIC_THRESHOLDS: {
+    readonly repeatThreshold: number;
+    readonly minRepeatThreshold: number;
+    readonly maxRepeatThreshold: number;
+    readonly slowOperationMs: number;
+    readonly maxOperations: number;
+    readonly maxFindings: number;
+    readonly smallTableRows: number;
+    readonly filterDiscardRatio: number;
+    readonly estimateErrorFactor: number;
+    readonly highLoopCount: number;
+};
+/**
+ * Read a bounded window of operation events for repeated statements and slow
+ * operations. Findings are labelled SUSPECTED — this is evidence for a human,
+ * not a verdict.
+ *
+ * @example
+ * analyzeOperationTelemetry({ operations: collector.operations, repeatThreshold: 5 });
+ */
+export declare function analyzeOperationTelemetry(params: {
+    operations: readonly TelemetryOperationEvent[];
+    repeatThreshold?: number;
+    slowOperationMs?: number;
+    maxOperations?: number;
+    maxFindings?: number;
+}): TelemetryDiagnosticReport;
+/**
+ * Turn one plan (plus the table facts a plan cannot supply) into deterministic
+ * findings. Order is the plan's own walk order, so the same plan always
+ * produces the same list.
+ *
+ * @example
+ * recommendFromPlan({ report, tables: [{ table: "User", estimatedRows: 5_000_000 }], indexes });
+ */
+export declare function recommendFromPlan(params: {
+    report: QueryPlanReport;
+    tables?: readonly TableFacts[];
+    indexes?: readonly IndexFacts[];
+    maxFindings?: number;
+}): readonly DiagnosticFinding[];
+//# sourceMappingURL=insight.d.ts.map

package/dist/diagnostics/insight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight.d.ts","sourceRoot":"","sources":["../../src/diagnostics/insight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EAEV,eAAe,EAGf,UAAU,EACV,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAIpB,wEAAwE;AACxE,eAAO,MAAM,qBAAqB,EAAE;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAY/B,CAAC;AAiBH;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,yBAAyB,CA6F5B;AAkBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,SAAS,iBAAiB,EAAE,CAwI/B"}

package/dist/diagnostics/plan.d.ts

@@ -0,0 +1,88 @@
+/**
+ * PostgreSQL plan inspection (EPIC 5).
+ *
+ * Two modes, deliberately far apart:
+ *
+ *  - `estimate` renders `EXPLAIN (FORMAT JSON)`, which does NOT run the
+ *    statement. It still takes planning locks and still parses and plans, so it
+ *    is not free and it is not zero-risk on a busy table.
+ *  - `analyze` renders `EXPLAIN (ANALYZE, FORMAT JSON, BUFFERS)`, which RUNS
+ *    the statement. It is gated behind an explicit confirmation and trusted
+ *    input, refuses writes and multi-statement text, and runs inside a
+ *    read-only transaction. None of that is a proof of safety: a SELECT can
+ *    call a function with side effects, and a keyword check cannot see that.
+ *    Never point it at production, and never replay a slow production query
+ *    automatically.
+ *
+ * The plan's own numbers are kept in their own units: planner cost units are
+ * not milliseconds, and estimated rows are not observed rows.
+ */
+import type { Dialect, SchemaIR } from "@vibeorm/schema";
+import type { SqlExecutor } from "../adapter.ts";
+import type { BuilderClientOptions, QueryMethod, RelationStrategy } from "../query-builder.ts";
+import type { ExplainMode, ParsedPlan, QueryPlanReport } from "./types.ts";
+/** Defaults for plan inspection; every one of them is a bound, not a preference. */
+export declare const PLAN_DEFAULTS: {
+    readonly maxNodes: number;
+    readonly maxConditionLength: number;
+};
+/**
+ * Parse one `EXPLAIN (FORMAT JSON)` payload into a bounded node tree.
+ *
+ * Accepts what the drivers actually hand back: a parsed array, a single object,
+ * or the JSON text (bun:sql and pglite differ from node-postgres here).
+ */
+export declare function parsePostgresPlan(params: {
+    payload: unknown;
+    mode: ExplainMode;
+    maxNodes?: number;
+    includeLiterals?: boolean;
+}): ParsedPlan;
+/**
+ * Take a plan for already-rendered SQL.
+ *
+ * @example
+ * await explainSql({ executor, dialect: "postgres",
+ *                    sql: { text: 'SELECT "id" FROM "User" WHERE "email" = $1', values: ["a@b.test"] } });
+ */
+export declare function explainSql(params: {
+    executor: SqlExecutor;
+    dialect: Dialect;
+    sql: {
+        readonly text: string;
+        readonly values: readonly unknown[];
+    };
+    mode?: ExplainMode;
+    /** REQUIRED for `analyze`: that mode executes the statement. */
+    confirmExecute?: boolean;
+    /** REQUIRED for `analyze`: the caller vouches that this SQL is its own, not a user's. */
+    trustedInput?: boolean;
+    /** Transaction-local settings, bound exactly as the client binds them. */
+    rlsContext?: Readonly<Record<string, unknown>>;
+    /** Refuse instead of labelling when the role is not representative. */
+    requireRepresentativeContext?: boolean;
+    maxNodes?: number;
+    includeLiterals?: boolean;
+}): Promise<QueryPlanReport>;
+/**
+ * Take a plan for one ORM operation, built through the same pure planning path
+ * `previewOperation` uses. Multi-statement and data-dependent flows are refused
+ * in the executing mode rather than half-explained.
+ */
+export declare function explainOperation(params: {
+    executor: SqlExecutor;
+    schema: SchemaIR;
+    dialect: Dialect;
+    model: string;
+    method: QueryMethod;
+    args?: Record<string, unknown>;
+    mode?: ExplainMode;
+    confirmExecute?: boolean;
+    rlsContext?: Readonly<Record<string, unknown>>;
+    requireRepresentativeContext?: boolean;
+    relationStrategy?: RelationStrategy;
+    clientOptions?: BuilderClientOptions;
+    maxNodes?: number;
+    includeLiterals?: boolean;
+}): Promise<QueryPlanReport>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/diagnostics/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/diagnostics/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG/F,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAyB,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlG,oFAAoF;AACpF,eAAO,MAAM,aAAa,EAAE;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACwB,CAAC;AAyD/D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,UAAU,CA+Eb;AA4ED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE;IACvC,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;KAAE,CAAC;IACpE,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yFAAyF;IACzF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,uEAAuE;IACvE,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,eAAe,CAAC,CAuG3B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,eAAe,CAAC,CAkC3B"}

package/dist/diagnostics/preview.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SQL preview: what an operation WOULD send, without sending it (EPIC 5).
+ *
+ * Preview takes an explicit `{ schema, model, method, args }` input and runs
+ * the pure planning path (`buildQuery` → `renderStatement`). It never touches a
+ * delegate, so there is no lazy query promise to start, and it needs no
+ * database, no adapter and no connection.
+ *
+ * What it refuses to do: invent a parameter it does not have, or present one
+ * statement as the whole operation. A flow whose later statements depend on
+ * rows that do not exist yet is REPORTED as such, with the statements that are
+ * knowable shown in full and the rest named as a limitation.
+ */
+import type { Dialect, SchemaIR } from "@vibeorm/schema";
+import type { BuilderClientOptions, QueryMethod, RelationStrategy } from "../query-builder.ts";
+import type { OperationPreview } from "./types.ts";
+/**
+ * A redacted description of one parameter: its transport shape, never its
+ * value. `previewOperation({ includeParameterValues: true })` opts out.
+ */
+export declare function parameterTypeTag(params: {
+    value: unknown;
+}): string;
+/**
+ * Describe the SQL of one operation without executing anything.
+ *
+ * @example
+ * previewOperation({ schema, dialect: "postgres", model: "User", method: "findMany",
+ *                    args: { where: { email: "a@b.test" } } });
+ * // → one SELECT with `$1`, parameters reported as ["string"]
+ */
+export declare function previewOperation(params: {
+    schema: SchemaIR;
+    dialect: Dialect;
+    model: string;
+    method: QueryMethod;
+    args?: Record<string, unknown>;
+    relationStrategy?: RelationStrategy;
+    clientOptions?: BuilderClientOptions;
+    /** Show real parameter values. OFF by default: a preview is not public telemetry. */
+    includeParameterValues?: boolean;
+}): OperationPreview;
+//# sourceMappingURL=preview.d.ts.map

package/dist/diagnostics/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/diagnostics/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAa,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK1G,OAAO,KAAK,EAAE,gBAAgB,EAAuC,MAAM,YAAY,CAAC;AAKxF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CASnE;AA4CD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,qFAAqF;IACrF,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GAAG,gBAAgB,CA6HnB"}

package/dist/diagnostics/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Public shapes for SQL preview and PostgreSQL query diagnostics (EPIC 5).
+ *
+ * Two invariants run through every type here:
+ *
+ *  - **Cost units are not milliseconds.** `estimatedTotalCost` is the planner's
+ *    own abstract cost; `actualTotalTimeMs`, `planningTimeMs` and
+ *    `executionTimeMs` are milliseconds and exist only where the server
+ *    measured them. Estimated rows and observed rows are likewise separate
+ *    fields, never merged.
+ *  - **Nothing here is public telemetry.** Parameters are type tags unless the
+ *    caller asks for values, and plan conditions are redacted by default —
+ *    PostgreSQL substitutes literal values into `Index Cond` and `Filter` even
+ *    when the statement was parameterized.
+ */
+import type { Dialect } from "@vibeorm/schema";
+import type { QueryMethod, RelationStrategy } from "../query-builder.ts";
+/** Why a preview cannot claim to be the whole operation. */
+export type PreviewLimitationCode = "relation-statements-data-dependent" | "nested-writes-data-dependent" | "upsert-fallback-flow" | "batched-statements" | "client-side-post-processing";
+/** One named limitation, with the reason spelled out for a human. */
+export type PreviewLimitation = {
+    readonly code: PreviewLimitationCode;
+    readonly message: string;
+};
+/** One statement a preview can show in full. */
+export type PreviewStatement = {
+    readonly index: number;
+    /** `primary` is the statement the operation leads with; `batch` are its known siblings. */
+    readonly role: "primary" | "batch";
+    readonly kind: string;
+    readonly sql: string;
+    readonly parameterCount: number;
+    /** Redacted type tags (`"string"`, `"date"`, …) unless values were explicitly requested. */
+    readonly parameters: readonly string[];
+    /** EPIC 1's `queryFingerprint` — the same grouping key telemetry reports. */
+    readonly fingerprint: string;
+};
+/** What an operation would send, and what about it cannot be known without data. */
+export type OperationPreview = {
+    readonly model: string;
+    readonly method: QueryMethod;
+    readonly dialect: Dialect;
+    readonly statements: readonly PreviewStatement[];
+    /** False ⇒ further statements run whose shape or count only the data decides. */
+    readonly complete: boolean;
+    readonly limitations: readonly PreviewLimitation[];
+    readonly relationStrategy: RelationStrategy | null;
+    /** Relations this operation loads with their own follow-up statements. */
+    readonly relationsLoadedSeparately: readonly string[];
+};
+/** `estimate` is non-executing `EXPLAIN`; `analyze` EXECUTES the statement. */
+export type ExplainMode = "estimate" | "analyze";
+/** One node of a PostgreSQL plan, with estimates and observations kept apart. */
+export type PlanNode = {
+    readonly nodeType: string;
+    readonly relation?: string;
+    readonly alias?: string;
+    readonly indexName?: string;
+    readonly parentRelationship?: string;
+    /** Planner cost units — NOT milliseconds and not comparable across servers. */
+    readonly estimatedStartupCost: number;
+    readonly estimatedTotalCost: number;
+    readonly estimatedRows: number;
+    readonly planWidth: number;
+    /** Observed, `analyze` only. */
+    readonly actualTotalTimeMs?: number;
+    readonly actualRows?: number;
+    readonly actualLoops?: number;
+    readonly rowsRemovedByFilter?: number;
+    readonly sharedBlocksHit?: number;
+    readonly sharedBlocksRead?: number;
+    readonly tempBlocksRead?: number;
+    readonly tempBlocksWritten?: number;
+    readonly sortMethod?: string;
+    /** `Index Cond`, `Filter`, `Sort Key`… — redacted unless literals were requested. */
+    readonly conditions: Readonly<Record<string, string>>;
+    readonly children: readonly PlanNode[];
+};
+/** The parse result of one `EXPLAIN (FORMAT JSON)` payload. */
+export type ParsedPlan = {
+    readonly root: PlanNode;
+    readonly nodeCount: number;
+    readonly truncated: boolean;
+    readonly planningTimeMs?: number;
+    readonly executionTimeMs?: number;
+};
+/** The identity a plan was taken under — the difference between a plan and a representative plan. */
+export type PlanContext = {
+    readonly currentUser: string;
+    readonly sessionUser: string;
+    readonly superuser: boolean;
+    readonly bypassRls: boolean;
+    readonly serverVersionNum: number;
+    /** Keys of the row-level-security context bound for this plan (never the values). */
+    readonly rlsContextKeys: readonly string[];
+    /** False ⇒ this plan is not what a runtime role would see. */
+    readonly representative: boolean;
+    readonly reason?: string;
+};
+/** A parsed plan plus the context and caveats a reader needs to judge it. */
+export type QueryPlanReport = {
+    readonly mode: ExplainMode;
+    readonly root: PlanNode;
+    readonly nodeCount: number;
+    readonly truncated: boolean;
+    /** Planner cost units for the whole plan. Never milliseconds. */
+    readonly estimatedTotalCostUnits: number;
+    readonly planningTimeMs?: number;
+    readonly executionTimeMs?: number;
+    readonly literalsRedacted: boolean;
+    readonly context: PlanContext;
+    readonly warnings: readonly string[];
+};
+/** Whether `pg_stat_statements` can be read at all, and by whom. */
+export type WorkloadAvailability = {
+    readonly available: boolean;
+    readonly installed: boolean;
+    readonly schema: string | null;
+    readonly installedVersion: string | null;
+    readonly serverVersionNum: number;
+    /** False ⇒ other roles' statement text reads as `<insufficient privilege>`. */
+    readonly readAllStats: boolean;
+    readonly reason?: string;
+};
+/** One statement shape's cumulative totals since the collection window opened. */
+export type WorkloadStatement = {
+    /** PostgreSQL's own query id. NOT an application fingerprint. */
+    readonly queryId: string | null;
+    readonly statement: string;
+    readonly redacted: boolean;
+    readonly calls: number;
+    readonly totalExecTimeMs: number;
+    readonly meanExecTimeMs: number;
+    readonly minExecTimeMs: number;
+    readonly maxExecTimeMs: number;
+    readonly rows: number;
+    readonly sharedBlocksHit: number;
+    readonly sharedBlocksRead: number;
+    readonly tempBlocksRead: number;
+    readonly tempBlocksWritten: number;
+};
+/** A read-only workload snapshot and everything it cannot tell you. */
+export type WorkloadReport = {
+    readonly source: "pg_stat_statements";
+    readonly availability: WorkloadAvailability;
+    readonly collectionWindow: {
+        readonly statsReset: string | null;
+        readonly known: boolean;
+    };
+    readonly statements: readonly WorkloadStatement[];
+    /** Always `"none"`: no verified correlation between a query id and a fingerprint. */
+    readonly correlation: "none";
+    readonly notes: readonly string[];
+};
+/** A repeated-statement observation. Suspected, never asserted. */
+export type SuspectedPattern = {
+    readonly kind: "suspected-n-plus-one" | "repeated-statement";
+    readonly fingerprint: string;
+    readonly count: number;
+    readonly operationId: string;
+    readonly model: string | null;
+    readonly method: string;
+    readonly totalDurationMs: number;
+    readonly evidence: string;
+    readonly suspected: true;
+};
+/** One slow operation, straight from EPIC 1's operation events. */
+export type SlowOperation = {
+    readonly operationId: string;
+    readonly model: string | null;
+    readonly method: string;
+    readonly durationMs: number;
+    readonly statementCount: number;
+};
+/** What a bounded window of operation telemetry suggests. */
+export type TelemetryDiagnosticReport = {
+    readonly window: {
+        readonly operations: number;
+        readonly statements: number;
+        readonly bounded: boolean;
+    };
+    readonly slowOperations: readonly SlowOperation[];
+    readonly repeatedStatements: readonly SuspectedPattern[];
+    readonly suspectedNPlusOne: readonly SuspectedPattern[];
+};
+/** Facts about one table that a plan alone cannot supply. */
+export type TableFacts = {
+    readonly table: string;
+    readonly estimatedRows: number;
+    readonly tableBytes?: number;
+    readonly rlsEnabled?: boolean;
+    readonly lastAnalyze?: string | null;
+};
+/** One index that already exists. */
+export type IndexFacts = {
+    readonly table: string;
+    readonly index: string;
+    readonly definition?: string;
+    readonly unique?: boolean;
+    readonly primary?: boolean;
+};
+/** The closed set of things the analysis is prepared to claim. */
+export type DiagnosticFindingCode = "sequential-scan-on-large-table" | "sequential-scan-on-small-table-not-a-defect" | "row-estimate-off" | "expensive-sort-spilled-to-disk" | "nested-loop-high-loop-count" | "filter-discards-most-rows" | "cannot-explain-waits";
+/** An index a HUMAN may want to review. Never created, never ranked. */
+export type IndexCandidate = {
+    readonly table: string;
+    readonly predicateContext: string;
+    readonly orderContext?: string;
+    readonly existingIndexes: readonly string[];
+    readonly tradeoff: string;
+};
+/** One deterministic finding, with the measurement it came from. */
+export type DiagnosticFinding = {
+    readonly code: DiagnosticFindingCode;
+    readonly severity: "info" | "warn";
+    readonly node: string;
+    readonly relation: string | null;
+    readonly evidence: string;
+    /** True ⇒ a suggestion for human review, not a conclusion. */
+    readonly candidate: boolean;
+    readonly indexCandidate?: IndexCandidate;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/diagnostics/types.d.ts.map

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

package/dist/diagnostics/workload.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Optional PostgreSQL workload statistics from `pg_stat_statements` (EPIC 5).
+ *
+ * Strictly read-only and strictly gated. This module cannot install the
+ * extension, cannot change a server setting, cannot restart anything and cannot
+ * reset statistics — the SQL to do any of that does not exist in
+ * `@vibeorm/sql`. An absent extension is REPORTED, never provisioned.
+ *
+ * What this source is not: it has no per-call percentiles (its totals are
+ * cumulative since the last reset — percentiles come from EPIC 1's operation
+ * histograms), and its `queryid` is PostgreSQL's own normalization, which is
+ * NOT the application fingerprint. The two are reported side by side with the
+ * uncertainty stated, never joined.
+ */
+import type { Dialect } from "@vibeorm/schema";
+import type { SqlExecutor } from "../adapter.ts";
+import type { WorkloadReport } from "./types.ts";
+/**
+ * Read a bounded, read-only snapshot of the database's statement workload.
+ *
+ * @example
+ * const report = await readWorkloadStatistics({ executor, dialect: "postgres", limit: 20 });
+ * report.availability.installed; // false ⇒ statements is [] and the reason says why
+ */
+export declare function readWorkloadStatistics(params: {
+    executor: SqlExecutor;
+    dialect: Dialect;
+    limit?: number;
+    /** Include statement text (still normalized). Off by default. */
+    includeStatementText?: boolean;
+}): Promise<WorkloadReport>;
+//# sourceMappingURL=workload.d.ts.map

package/dist/diagnostics/workload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workload.d.ts","sourceRoot":"","sources":["../../src/diagnostics/workload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAwB,cAAc,EAAqB,MAAM,YAAY,CAAC;AA+C1F;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,GAAG,OAAO,CAAC,cAAc,CAAC,CAkF1B"}