@vibeorm/runtime 1.3.0 → 2.0.0-alpha.10

package/dist/telemetry/types.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The vendor-neutral observability contract (EPIC 1).
+ *
+ * An OPERATION is one public ORM call (`user.findMany()`, `$queryRaw`, one
+ * `$transaction`, one extension mount call). A STATEMENT is one SQL execution
+ * inside it. VibeORM emits operations and statements to an exporter the HOST
+ * owns; it never owns a tracer, never starts a provider, and never shuts one
+ * down.
+ *
+ * Privacy defaults, deliberately conservative:
+ *   - parameter VALUES are redacted (only `parameterCount` is reported),
+ *   - rendered SQL text is not captured (it can embed literals and secrets),
+ *   - error CAUSES are never serialized into attributes — only the stable
+ *     `VibeError.code` travels.
+ * Both captures are separate opt-ins.
+ *
+ * Honesty rules encoded in these types: anything unknown or unavailable is
+ * ABSENT, never invented as zero. `rowCount`, `durationMs`, `statementDurationMs`
+ * and every `detail` subdivision are optional for that reason.
+ */
+import type { Dialect, Provider, VibeErrorCode } from "@vibeorm/schema";
+/** What kind of public call an operation represents. */
+export type TelemetryOperationKind = "model" | "raw" | "transaction" | "extension";
+/** Which execution path ran a statement. */
+export type TelemetryStatementKind = "rows" | "affected" | "raw" | "extension";
+/** Terminal result of an operation or statement. */
+export type TelemetryOutcome = "success" | "failure";
+/**
+ * Where an operation ended. `completed` is the only success stage; the rest name
+ * the phase that failed, so a consumer can tell a refusal before any SQL from a
+ * rollback failure after every statement succeeded.
+ */
+export type TelemetryStage = 
+/** Never dispatched: refused before it could run (array-$transaction claim refusal, expired handle). */
+"refused"
+/** Failed before any SQL was sent: argument validation, planning, capability refusal. */
+ | "validation"
+/** A statement failed at the adapter. */
+ | "statement"
+/**
+ * Statements succeeded; the ORM failed while producing the result — row
+ * decoding, relation loading, computed fields, or an `OrThrow` miss.
+ */
+ | "decode"
+/** Statements succeeded; the surrounding transaction failed to commit or roll back. */
+ | "transaction"
+/** Everything succeeded. */
+ | "completed"
+/** Failure that could not be attributed to a phase. */
+ | "unknown";
+/** Which exporter callback a throw came out of. */
+export type TelemetryExportPhase = "operation" | "statement" | "drop" | "flush" | "shutdown" | "sampler" | "context";
+/**
+ * The host's parent context, captured SYNCHRONOUSLY at call time and carried
+ * back on the operation event. Opaque on purpose: an OpenTelemetry `Context`, a
+ * request object, a trace id — VibeORM never inspects it, never serializes it
+ * and never uses it as a metric label.
+ */
+export type TelemetryParentContext = unknown;
+/** One SQL execution inside an operation. */
+export type TelemetryStatementEvent = {
+    readonly operationId: string;
+    /** 0-based position inside its operation. */
+    readonly index: number;
+    readonly kind: TelemetryStatementKind;
+    /** `null` for raw SQL, which has no model. */
+    readonly model: string | null;
+    readonly method: string;
+    readonly dialect: Dialect;
+    readonly provider: Provider;
+    /** Stable normalized grouping key — bounded, literal-free, safe as a metric label. */
+    readonly fingerprint: string;
+    readonly outcome: TelemetryOutcome;
+    /**
+     * Elapsed time of the adapter call. This includes networking and may include
+     * pool wait and driver-side decoding — it is NOT pure server execution time.
+     */
+    readonly durationMs: number;
+    /** How many bound parameters the statement carried. Values are not reported. */
+    readonly parameterCount: number;
+    readonly inTransaction: boolean;
+    /** Absent when this path cannot know the row count. */
+    readonly rowCount?: number;
+    /** Stable code of the failure; message text and cause are never attached. */
+    readonly errorCode?: VibeErrorCode;
+    /** True when `durationMs` crossed the configured slow-statement threshold. */
+    readonly slow?: boolean;
+    /** Rendered SQL — only with `captureSql: true`. */
+    readonly sql?: string;
+    /** Parameter values — only with `captureParameterValues: true`. */
+    readonly parameters?: readonly unknown[];
+};
+/** Optional timing subdivision; every member is absent when unavailable. */
+export type TelemetryTimingDetail = {
+    /** Statement rendering (cache hit or real render) inside this operation. */
+    readonly renderMs?: number;
+    /** Summed adapter-call elapsed time — networking and possibly pool wait included. */
+    readonly adapterMs?: number;
+    /** Operation time not spent in the adapter: planning, decoding, relations, computed fields. */
+    readonly processingMs?: number;
+};
+/** One public ORM call, start to terminal outcome. Emitted exactly once. */
+export type TelemetryOperationEvent = {
+    readonly operationId: string;
+    /** The enclosing transaction/extension operation, when there is one. */
+    readonly parentOperationId?: string;
+    /** The host context captured at call time, handed straight back. */
+    readonly context?: TelemetryParentContext;
+    readonly kind: TelemetryOperationKind;
+    readonly model: string | null;
+    readonly method: string;
+    readonly dialect: Dialect;
+    readonly provider: Provider;
+    readonly outcome: TelemetryOutcome;
+    readonly stage: TelemetryStage;
+    /** False when the operation was refused before it ever ran. */
+    readonly dispatched: boolean;
+    /** Epoch milliseconds at ACTUAL dispatch. Absent when never dispatched. */
+    readonly startedAt?: number;
+    /** Dispatch to terminal outcome. Absent when never dispatched. */
+    readonly durationMs?: number;
+    /**
+     * Creation to dispatch — the deferred-dispatch queue delay. Labelled
+     * separately and never folded into `durationMs`.
+     */
+    readonly queueWaitMs?: number;
+    readonly statementCount: number;
+    /** Summed statement elapsed time. Absent when no statement ran. */
+    readonly statementDurationMs?: number;
+    /** Rows the operation is known to have produced or affected. Absent when unknown. */
+    readonly rowCount?: number;
+    readonly errorCode?: VibeErrorCode;
+    readonly detail?: TelemetryTimingDetail;
+    readonly statements: readonly TelemetryStatementEvent[];
+    /** Statements observed beyond `maxStatementsPerOperation` (counted, not kept). */
+    readonly droppedStatements?: number;
+    /** True when `durationMs` crossed the configured slow-operation threshold. */
+    readonly slow?: boolean;
+    /** An emitted span is by definition a sampled span — see the metrics snapshot for totals. */
+    readonly sampled: true;
+};
+/** Something was counted but not delivered. */
+export type TelemetryDropEvent = {
+    readonly reason: "buffer_full" | "statement_limit";
+    readonly count: number;
+};
+/**
+ * Where events go. Every callback is invoked inside a guard: a throw is routed
+ * to `onExporterError` and can never change a database outcome, a query's
+ * arguments or its results.
+ *
+ * `shutdown` is NEVER called by the client — `$disconnect()` flushes only,
+ * because the provider behind a shared exporter belongs to the host.
+ */
+export type TelemetryExporter = {
+    readonly onOperation?: (event: TelemetryOperationEvent) => void;
+    readonly onStatement?: (event: TelemetryStatementEvent) => void;
+    readonly onDrop?: (event: TelemetryDropEvent) => void;
+    readonly flush?: () => void | Promise<void>;
+    readonly shutdown?: () => void | Promise<void>;
+};
+/** What a sampler is told, before any work is done. */
+export type TelemetrySamplerInput = {
+    readonly kind: TelemetryOperationKind;
+    readonly model: string | null;
+    readonly method: string;
+    readonly context?: TelemetryParentContext;
+};
+/** How exported operations reach the exporter. */
+export type TelemetryDelivery = "immediate" | "buffered";
+/**
+ * The host's handle on this client's telemetry: complete counters (spans may be
+ * sampled, these are not) and EXPLICIT lifecycle. `shutdown` exists here and
+ * only here — the client itself never calls it.
+ */
+export type TelemetryHandle = {
+    readonly metrics: () => TelemetryMetricsSnapshot;
+    readonly flush: () => Promise<void>;
+    readonly shutdown: () => Promise<void>;
+};
+/** Telemetry configuration — the single `ClientOptions.telemetry` value. */
+export type TelemetryOptions = {
+    /** Where events go. Required. */
+    readonly exporter: TelemetryExporter;
+    /** Attach rendered SQL text to statement events. Default FALSE: raw text can embed secrets. */
+    readonly captureSql?: boolean;
+    /** Attach parameter VALUES. Default FALSE: values are redacted, only the count is reported. */
+    readonly captureParameterValues?: boolean;
+    /** Split render / adapter / processing time on the operation event. Default FALSE. */
+    readonly detailedTimings?: boolean;
+    /** Probability a span is kept, 0..1 (default 1). Counters still count every execution. */
+    readonly sampleRate?: number;
+    /** Deterministic sampling decision; takes precedence over `sampleRate`. */
+    readonly sampler?: (input: TelemetrySamplerInput) => boolean;
+    /**
+     * Read the host's current parent context. Called SYNCHRONOUSLY when the ORM
+     * call is created — before the deferred dispatch — so an application span
+     * survives the async boundary between call and execution.
+     */
+    readonly context?: () => TelemetryParentContext;
+    /** `"immediate"` (default) exports at settle; `"buffered"` holds until `flush()`. */
+    readonly delivery?: TelemetryDelivery;
+    /** Buffered-delivery ceiling; the oldest entries are dropped and counted. */
+    readonly maxBufferedOperations?: number;
+    /** Statements kept per operation; the rest are counted in `droppedStatements`. */
+    readonly maxStatementsPerOperation?: number;
+    /** `slow` marker threshold for a statement, in milliseconds. */
+    readonly slowStatementMs?: number;
+    /** `slow` marker threshold for an operation, in milliseconds. */
+    readonly slowOperationMs?: number;
+    /** Told when an exporter callback throws. Itself guarded; never rethrows into the query. */
+    readonly onExporterError?: (params: {
+        error: unknown;
+        phase: TelemetryExportPhase;
+    }) => void;
+    /**
+     * Called ONCE, synchronously, while the client is being built, with the
+     * handle that owns metrics and lifecycle. Take it if you want complete
+     * counters under sampling, or if you want to flush/shut down deliberately.
+     */
+    readonly onReady?: (handle: TelemetryHandle) => void;
+};
+/** A fixed-bucket latency histogram. */
+export type TelemetryHistogram = {
+    /** Upper bucket bounds in milliseconds; the implicit last bucket is unbounded. */
+    readonly bounds: readonly number[];
+    /** One count per bound plus one overflow bucket. */
+    readonly counts: readonly number[];
+    readonly sum: number;
+    readonly count: number;
+};
+/**
+ * Counters and histograms.
+ *
+ * `countsRepresent: "all"` is a promise, not decoration: counters and histograms
+ * are updated for EVERY execution regardless of sampling, so they never pretend
+ * sampled spans are complete query counts. `sampledOperations` says how many of
+ * those also produced a span.
+ */
+export type TelemetryMetricsSnapshot = {
+    readonly countsRepresent: "all";
+    readonly sampleRate: number;
+    readonly sampledOperations: number;
+    readonly operations: {
+        readonly total: number;
+        readonly failed: number;
+        readonly refused: number;
+    };
+    readonly statements: {
+        readonly total: number;
+        readonly failed: number;
+    };
+    /** `known` = operations whose row count was knowable; `total` = the sum of those. */
+    readonly rows: {
+        readonly known: number;
+        readonly total: number;
+    };
+    readonly operationLatencyMs: TelemetryHistogram;
+    readonly statementLatencyMs: TelemetryHistogram;
+    readonly dropped: {
+        readonly operations: number;
+        readonly statements: number;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/validators.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Opt-in write-boundary validation (EPIC 3) — Standard-Schema validators
+ * mounted per model × field, run on every write path (nested creates
+ * included) BEFORE the data reaches the encoder. Decode-side is deliberately
+ * untouched: validation taxes writes the caller opted into, never every row
+ * materialization (rule 8; board #30).
+ *
+ * The interface is the published Standard Schema contract
+ * (https://standardschema.dev) — zod, valibot and arktype all implement it —
+ * vendored as a minimal type so the runtime takes no dependency.
+ */
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+/** One validation issue as Standard Schema defines it. */
+export type StandardIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }>;
+};
+/** The Standard Schema v1 contract — the only surface the runtime touches. */
+export type StandardSchemaV1<Input = unknown, Output = Input> = {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            value: Output;
+            issues?: undefined;
+        } | {
+            issues: readonly StandardIssue[];
+        } | Promise<unknown>;
+    };
+};
+/** Per-model, per-field validator config: `{ User: { settings: zodSchema } }`. */
+export type WriteValidators = {
+    readonly [model: string]: {
+        readonly [field: string]: StandardSchemaV1;
+    };
+};
+/**
+ * Validate one data row (create/update shape) for `model`, recursing into
+ * every nested write body on every related model. Returns the (possibly
+ * transformed) data — Standard Schema allows coercion.
+ *
+ * Traversal is UNCONDITIONAL (F09): it does not stop at a related model that
+ * configures no validators of its own, because a model further down may.
+ */
+export declare function validateWriteData(params: {
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    data: Record<string, unknown>;
+    validators: WriteValidators;
+}): Record<string, unknown>;
+/** Rewrite a write method's args through the validators; non-write args pass through untouched. */
+export declare function applyWriteValidators(params: {
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    method: string;
+    args: Record<string, unknown>;
+    validators: WriteValidators;
+}): Record<string, unknown>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAI9D,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;CAC5E,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK,IAAI;IAC9D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,KACX;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,SAAS,CAAA;SAAE,GAAG;YAAE,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;SAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;KACtG,CAAC;CACH,CAAC;AAEF,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAA;KAAE,CAAC;CAC1E,CAAC;AAmEF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,UAAU,EAAE,eAAe,CAAC;CAC7B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgC1B;AA8CD,mGAAmG;AACnG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,UAAU,EAAE,eAAe,CAAC;CAC7B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsB1B"}

package/dist/views.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Field-masking views — the v1 `db.defineView()` surface ported to v2
+ * (board #11), renamed `$defineView` per v2's $-prefixed client-name rule.
+ *
+ * A view is a READ-ONLY scoped client over the models named in its definition.
+ * Rows come back as `ViewResult` instances that expose only the definition's
+ * fields; `reveal: { field: true }` makes an extra field readable as a
+ * property while `JSON.stringify` still excludes it, and `$unsafe()` returns
+ * everything. Relations load normally: when the related model is ALSO in the
+ * definition its rows are masked recursively; when it is not, they pass
+ * through untouched (v1 semantics).
+ *
+ * Isolated by design: this module wraps the public delegate surface
+ * (`client.$models`) and never reaches into the query builder — the same SQL
+ * runs, the ARGS are rewritten (definition fields become a `select`) and the
+ * RESULT objects are wrapped.
+ *
+ * v1 → v2 deltas (documented in apps/tests/parity-fragments/views.md):
+ *  - `defineView` → `$defineView`; errors are `VibeError` codes, not strings.
+ *  - The definition is validated eagerly (unknown model / unknown field /
+ *    empty field set throw `VIBE_VALIDATION` at definition time).
+ *  - Write verbs exist on the view delegate but throw `VIBE_VALIDATION`
+ *    (mirroring v2's database-view read-only contract) — v1 left them
+ *    `undefined`.
+ *  - A nested `include` under a masked relation stays masked (v1 dropped the
+ *    restriction one level down); `omit` on a view query is refused loudly
+ *    (v1 stripped it silently).
+ */
+import type { ClientRow, ModelDelegate } from "./client.ts";
+import type { RuntimeMeta } from "./model-meta.ts";
+/**
+ * A view definition: client-name model keys → the set of visible fields.
+ * Example: `{ user: { id: true, name: true }, post: { id: true, title: true } }`.
+ */
+export type ViewDefinition = Record<string, Record<string, boolean | undefined>>;
+/** The read surface of one model under a view — writes throw `VIBE_VALIDATION`. */
+export type ViewModelDelegate = {
+    readonly findMany: (args?: ClientRow) => Promise<ViewResult[]>;
+    readonly findFirst: (args?: ClientRow) => Promise<ViewResult | null>;
+    readonly findFirstOrThrow: (args?: ClientRow) => Promise<ViewResult>;
+    readonly findUnique: (args: ClientRow) => Promise<ViewResult | null>;
+    readonly findUniqueOrThrow: (args: ClientRow) => Promise<ViewResult>;
+    readonly count: (args?: ClientRow) => Promise<number | Record<string, number>>;
+    readonly aggregate: (args: ClientRow) => Promise<ClientRow>;
+    readonly groupBy: (args: ClientRow) => Promise<ClientRow[]>;
+} & Record<string, unknown>;
+/** What `$defineView` returns at the runtime level — the generated d.ts narrows it. */
+export type ViewClientShape = Record<string, ViewModelDelegate>;
+/** The `$defineView` client method (runtime-level shape). */
+export type DefineViewFn = (options: {
+    readonly name: string;
+    readonly definition: ViewDefinition;
+}) => ViewClientShape;
+/**
+ * A masked row: visible + revealed fields are enumerable own properties,
+ * `toJSON()` (used by `JSON.stringify`) drops revealed fields recursively,
+ * `$unsafe()` returns a plain object with everything. Class methods are
+ * prototype members, so they never show up in `Object.keys` / spread.
+ */
+export declare class ViewResult {
+    /** Dynamic property access for view/revealed/relation fields. */
+    [key: string]: unknown;
+    /** @internal Field names revealed on this row (non-enumerable). */
+    readonly _revealed: ReadonlySet<string>;
+    constructor(params: {
+        record: Readonly<Record<string, unknown>>;
+        /** Every key to expose as a property (fields + revealed + relations). */
+        expose: ReadonlySet<string>;
+        revealed: ReadonlySet<string>;
+    });
+    /** Plain object WITHOUT revealed fields (what `JSON.stringify` sees), recursively. */
+    toJSON(): Record<string, unknown>;
+    /** Plain object with ALL fields (view + revealed), recursively — the escape hatch. */
+    $unsafe(): Record<string, unknown>;
+}
+/**
+ * Build a field-masking view client over an existing client's delegates.
+ *
+ * @throws VibeError `VIBE_VALIDATION` on an invalid definition (unknown model,
+ * unknown or relation field, empty field set).
+ */
+export declare function createView(params: {
+    meta: RuntimeMeta;
+    models: Readonly<Record<string, ModelDelegate>>;
+    name: string;
+    definition: ViewDefinition;
+}): ViewClientShape;
+/**
+ * Attach `$defineView` to a built client (called by `buildClient`; transaction
+ * clients get their own attachment because `$transaction` rebuilds the client).
+ */
+export declare function attachDefineView(params: {
+    client: object;
+    meta: RuntimeMeta;
+    models: Readonly<Record<string, ModelDelegate>>;
+}): void;
+//# sourceMappingURL=views.d.ts.map

package/dist/views.d.ts.map

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

package/dist/write-scope.d.ts

@@ -0,0 +1,14 @@
+import type { VibeError } from "@vibeorm/schema";
+/** Carry a protected field's required value through nested-write rewriting. */
+export declare function protectWriteScope(params: {
+    data: Record<string, unknown>;
+    field: string;
+    value: unknown;
+    error: VibeError;
+}): Record<string, unknown>;
+/** Refuse a relation-derived assignment before it can overwrite a protected field. */
+export declare function assertWriteScope(params: {
+    data: Record<string, unknown>;
+    assignments: Record<string, unknown>;
+}): void;
+//# sourceMappingURL=write-scope.d.ts.map

package/dist/write-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-scope.d.ts","sourceRoot":"","sources":["../src/write-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAWjD,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;CAClB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG1B;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,GAAG,IAAI,CAIP"}

package/package.json

@@ -1,45 +1,52 @@
 {
   "name": "@vibeorm/runtime",
-  "version": "1.3.0",
-  "description": "Driver-agnostic query engine and client runtime for VibeORM",
-  "license": "MIT",
+  "version": "2.0.0-alpha.10",
+  "description": "Driver-agnostic query engine and client runtime for VibeORM v2",
   "keywords": [
     "orm",
-    "runtime",
-    "query-builder",
-    "bun",
     "typescript",
-    "postgresql"
+    "sql",
+    "database",
+    "bun",
+    "type-safe",
+    "query-builder",
+    "client",
+    "adapter",
+    "relations"
   ],
-  "type": "module",
-  "exports": {
-    ".": {
-      "default": "./src/index.ts",
-      "types": "./src/index.ts"
-    }
+  "homepage": "https://github.com/vibeorm/vibeorm/tree/master/packages/runtime#readme",
+  "bugs": {
+    "url": "https://github.com/vibeorm/vibeorm/issues"
   },
-  "files": [
-    "src"
-  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/vibeorm/vibeorm.git",
     "directory": "packages/runtime"
   },
-  "homepage": "https://github.com/vibeorm/vibeorm/tree/master/packages/runtime",
-  "bugs": {
-    "url": "https://github.com/vibeorm/vibeorm/issues"
+  "license": "MIT",
+  "author": "VibeORM contributors",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "engines": {
-    "bun": ">=1.1.0"
+    "node": ">=18",
+    "bun": ">=1.2.0"
   },
-  "peerDependencies": {
-    "zod": ">=4"
+  "dependencies": {
+    "@vibeorm/schema": "2.0.0-alpha.8",
+    "@vibeorm/sql": "2.0.0-alpha.8"
   },
-  "peerDependenciesMeta": {
-    "zod": {
-      "optional": true
-    }
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.4",
+    "@vibeorm/scoped-conformance": "0.1.0-alpha.0"
   },
   "publishConfig": {
     "access": "public"