okmodel 0.0.0 → 0.1.1

package/dist/dialects/pg/time.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Date and time columns. The timestamp codec is Temporal.
+ */
+import { type ColumnBuilder, type PlainFlags } from "./column.js";
+import { type TimeWithOffset } from "./temporal.js";
+/**
+ * Timestamp with time zone.
+ *
+ * @param precision - Fractional seconds, 0 through 6
+ * @returns A timestamptz column
+ */
+export declare function timestamptz(precision?: number): ColumnBuilder<Temporal.Instant, PlainFlags>;
+/**
+ * Timestamp without time zone.
+ *
+ * @param precision - Fractional seconds, 0 through 6
+ * @returns A timestamp column
+ */
+export declare function timestamp(precision?: number): ColumnBuilder<Temporal.PlainDateTime, PlainFlags>;
+/**
+ * Calendar date.
+ *
+ * @returns A date column
+ */
+export declare function date(): ColumnBuilder<Temporal.PlainDate, PlainFlags>;
+/**
+ * Time of day.
+ *
+ * @param precision - Fractional seconds, 0 through 6
+ * @returns A time column
+ */
+export declare function time(precision?: number): ColumnBuilder<Temporal.PlainTime, PlainFlags>;
+/**
+ * Time of day with a numeric offset.
+ *
+ * @param precision - Fractional seconds, 0 through 6
+ * @returns A timetz column
+ */
+export declare function timetz(precision?: number): ColumnBuilder<TimeWithOffset, PlainFlags>;
+/**
+ * Interval. `fields` selects a Postgres qualifier such as `day to second`.
+ *
+ * @param fields - Optional field qualifier
+ * @returns An interval column
+ */
+export declare function interval(fields?: string): ColumnBuilder<Temporal.Duration, PlainFlags>;

package/dist/okm.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./tooling/cli.js";

package/dist/okmodel.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./tooling/cli.js";

package/dist/runtime/client.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Connected client: plan cache, one endpoint, and the read methods.
+ *
+ * `connect()` starts the dialect and `requires` checks. Queries wait for them.
+ * The plan cache is per client and bounded.
+ */
+import type { DriverPool } from "../contracts/driver.js";
+import { type ErrorStatuses } from "../contracts/error.js";
+import type { QuerySchema } from "../dialects/pg/model.js";
+import { type Plan } from "./plan.js";
+import type { CatalogArtifact, Connected } from "./types.js";
+type Session = {
+    readonly schema: QuerySchema;
+    readonly pool: DriverPool;
+    readonly ownsPool: boolean;
+    readonly http: ErrorStatuses | undefined;
+    readonly includeValues: boolean;
+    readonly logger: {
+        error?(entry: {
+            readonly code: string;
+            readonly summary: string;
+        }): void;
+    } | undefined;
+    readonly connected: Promise<void>;
+    readonly cache: Map<string, Plan>;
+};
+/**
+ * Builds a client for one pool.
+ *
+ * @param schema - Caller schema
+ * @param pool - Endpoint pool
+ * @param options - Errors, logger, and whether `close` ends the pool
+ * @returns The typed client
+ */
+export declare function createClient<S extends QuerySchema>(schema: S, pool: DriverPool, options: {
+    readonly endpoint?: string;
+    readonly ownsPool: boolean;
+    readonly http?: ErrorStatuses | undefined;
+    readonly includeValues?: boolean | undefined;
+    readonly logger?: Session["logger"] | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly timeout?: number | undefined;
+    readonly catalog?: CatalogArtifact | undefined;
+    readonly catalogDir?: string | undefined;
+    readonly requireMeta?: boolean | undefined;
+}): Connected<S>;
+export {};

package/dist/runtime/conflict.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `onConflict` planning.
+ *
+ * Loaded only when a write passes `onConflict` other than `"error"`.
+ * A plain insert does not import this module.
+ */
+import type { ColumnModel } from "../dialects/pg/model.js";
+import { type Indexed } from "./plan.js";
+/** How a conflict should be written. `"error"` never reaches here. */
+export type ConflictPlan = {
+    readonly kind: "ignore" | "update" | "return";
+    readonly columns: readonly ColumnModel[];
+    readonly update: readonly ColumnModel[];
+};
+/**
+ * Reads `onConflict` and checks `on` against unique constraints (OKM1104).
+ *
+ * @param table - Target table
+ * @param value - The option the caller passed
+ * @returns The plan, or `undefined` for the default `"error"`
+ */
+export declare function readConflict(table: Indexed, value: unknown): ConflictPlan | undefined;
+/**
+ * Appends the conflict clause, or wraps a first-or-create insert.
+ *
+ * @param head - `insert into … values …` without `returning`
+ * @param returning - ` returning …`, including the leading space
+ * @param params - Insert parameters
+ * @param plan - Conflict plan
+ * @param table - Target table
+ * @param returningColumns - Columns in `returning`
+ * @param keys - Encoded conflict-key tuples, one per inserted row. Used by `return`
+ * @returns Statement text and parameters
+ */
+export declare function finishInsert(head: string, returning: string, params: readonly (string | null)[], plan: ConflictPlan, table: Indexed, returningColumns: readonly ColumnModel[], keys: readonly (readonly (string | null)[])[]): {
+    readonly text: string;
+    readonly params: (string | null)[];
+};

package/dist/runtime/drift-detail.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compatibility check used only when the catalog hashes differ.
+ *
+ * Ahead by expand is compatible. Ahead by a contract step, or behind, fails
+ * closed (OKM1520).
+ */
+import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
+/** One applied migration, in history order. */
+export type DriftMigration = {
+    readonly id: string;
+    readonly catalogHash: string;
+    /** True when every step is expand. */
+    readonly expand: boolean;
+};
+/**
+ * Classifies a hash mismatch.
+ *
+ * @param codeHash - Hash of the code's catalog
+ * @param recordedHash - Hash stored in `okm_meta`
+ * @param migrations - Applied migrations, oldest first
+ * @returns `ok` when the database is ahead by expand only
+ */
+export declare function driftVerdict(codeHash: string, recordedHash: string, migrations: readonly DriftMigration[]): "ok" | "behind" | "contract";
+/**
+ * Reads history and throws OKM1520 when the database is not expand-ahead.
+ *
+ * @param pool - The connection `connect` already opened
+ * @param codeHash - Hash of the code's catalog
+ * @param recordedHash - Hash from the startup query
+ * @param options - The call's cancellation and deadline
+ */
+export declare function assertDrift(pool: DriverPool, codeHash: string, recordedHash: string, options: ExecuteOptions | undefined): Promise<void>;

package/dist/runtime/drift.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Startup catalog check.
+ *
+ * The fast path compares two hashes. History, catalog JSON, and
+ * {@link loadTrustedCatalog} load only when those hashes differ.
+ */
+import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
+import type { QuerySchema } from "../dialects/pg/model.js";
+/** Build artifact `okm build` wrote. */
+export type CatalogArtifact = {
+    readonly text: string;
+    readonly hash: string;
+};
+/**
+ * Compares the code's catalog hash with the hash already read from `okm_meta`.
+ *
+ * Equal hashes return without reading history. A difference loads the
+ * compatibility check.
+ *
+ * @param pool - The pool `connect` is checking
+ * @param schema - The caller's schema. Its catalog is read only when no artifact hash is available
+ * @param recordedHash - Hash from the startup query
+ * @param source - Optional build artifact, or a directory that contains one
+ * @param options - Cancellation and deadline for the history query
+ */
+export declare function assertCompatible(pool: DriverPool, schema: QuerySchema, recordedHash: string, source: {
+    readonly catalog?: CatalogArtifact;
+    readonly catalogDir?: string;
+}, options: ExecuteOptions | undefined): Promise<void>;

package/dist/runtime/include.d.ts

@@ -0,0 +1,15 @@
+/**
+ * LATERAL include planner. Loaded on the first include.
+ */
+import { type IncludeHooks, type Plan } from "./plan.js";
+/**
+ * Decodes a result that has includes.
+ *
+ * @param plan - Compiled plan
+ * @param rows - Wire rows
+ * @param table - Table the call named
+ * @returns The call's value
+ */
+export declare function decodeIncluded(plan: Plan, rows: readonly (readonly (string | null)[])[], table: string): unknown;
+/** Hooks the read planner calls after this module has loaded. */
+export declare const includeHooks: IncludeHooks;

package/dist/runtime/pg/pglite.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `connect` for PGlite (`okmodel/pg/pglite`).
+ *
+ * Opening a database is async. An existing pool is reused and not closed.
+ */
+import type { DriverPool } from "../../contracts/driver.js";
+import type { QuerySchema } from "../../dialects/pg/model.js";
+import { type PgliteConfig } from "../../adapters/pg/pglite.js";
+import type { ConnectOptions, Connected } from "../types.js";
+export { open, type PgliteConfig } from "../../adapters/pg/pglite.js";
+export { capabilities, hasCapability, readCapability } from "../../adapters/pg/pglite.js";
+export { DriverError } from "../../adapters/error.js";
+/** A data directory, a pool from {@link open}, or omitted for memory. */
+export type PgliteTarget = string | DriverPool | undefined;
+/** Driver options `connect` forwards to {@link open}. */
+export type PgliteConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PgliteConfig, "dataDir">;
+/**
+ * Connects one PGlite endpoint and returns a client for `schema`.
+ *
+ * @typeParam S - Schema
+ * @param target - Data directory, existing pool, or omitted for memory
+ * @param options - Schema, errors, and logger
+ * @returns The client
+ */
+export declare function connect<const S extends QuerySchema>(target: PgliteTarget, options: PgliteConnectOptions<S>): Promise<Connected<S>>;

package/dist/runtime/pg/pglite.js

@@ -0,0 +1,48 @@
+import {
+  DriverError2
+} from "../../shared/hd293j9g.js";
+import {
+  open3
+} from "../../shared/fgqgsb5z.js";
+import {
+  createClient
+} from "../../shared/rgs0st28.js";
+import {
+  PGLITE_CAPABILITIES,
+  readCapability2,
+  hasCapability2
+} from "../../shared/xy79j5hq.js";
+
+// src/runtime/pg/pglite.ts
+async function connect(target, options) {
+  const shared = {
+    http: options.errors?.http,
+    includeValues: options.errors?.includeValues,
+    logger: options.logger,
+    signal: options.signal,
+    requireMeta: options.requireMeta,
+    timeout: options.timeout,
+    catalog: options.catalog,
+    catalogDir: options.catalogDir
+  };
+  if (isPool(target)) {
+    return createClient(options.schema, target, { ...shared, ownsPool: false });
+  }
+  const dataDir = target;
+  const pool = await open3({
+    ...dataDir !== undefined ? { dataDir } : {},
+    ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {}
+  });
+  return createClient(options.schema, pool, { ...shared, ownsPool: true });
+}
+function isPool(target) {
+  return typeof target === "object" && target !== null && "execute" in target && "capabilities" in target;
+}
+export {
+  DriverError2 as DriverError,
+  PGLITE_CAPABILITIES as capabilities,
+  connect,
+  hasCapability2 as hasCapability,
+  open3 as open,
+  readCapability2 as readCapability
+};

package/dist/runtime/pg/postgresjs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `connect` for postgres.js (`okmodel/pg/postgresjs`).
+ *
+ * One URL or an existing pool is one endpoint. The client is typed by the
+ * schema passed in, not by `Register`.
+ */
+import type { DriverPool } from "../../contracts/driver.js";
+import type { QuerySchema } from "../../dialects/pg/model.js";
+import { type PostgresJsConfig } from "../../adapters/pg/postgresjs.js";
+import type { ConnectOptions, Connected } from "../types.js";
+export { open, type PostgresJsConfig } from "../../adapters/pg/postgresjs.js";
+export { capabilities, hasCapability, readCapability } from "../../adapters/pg/postgresjs.js";
+export { DriverError } from "../../adapters/error.js";
+/** A connection string or a pool from {@link open}. */
+export type PostgresTarget = string | DriverPool;
+/** Driver options `connect` forwards to {@link open}. */
+export type PostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PostgresJsConfig, "url">;
+/**
+ * Connects one Postgres endpoint and returns a client for `schema`.
+ *
+ * Named prepared statements are off unless `prepared` is `"named"`.
+ * `prepared: "named"` is not for transaction-mode poolers.
+ *
+ * @typeParam S - Schema
+ * @param target - URL or an existing pool
+ * @param options - Schema, errors, logger, and driver options
+ * @returns The client. Await `connected` for the dialect check
+ */
+export declare function connect<const S extends QuerySchema>(target: PostgresTarget, options: PostgresConnectOptions<S>): Connected<S>;

package/dist/runtime/pg/postgresjs.js

@@ -0,0 +1,62 @@
+import {
+  DriverError2
+} from "../../shared/hd293j9g.js";
+import {
+  open2
+} from "../../shared/dkn3y60a.js";
+import {
+  createClient
+} from "../../shared/rgs0st28.js";
+import {
+  POSTGRESJS_CAPABILITIES,
+  readCapability2,
+  hasCapability2
+} from "../../shared/xy79j5hq.js";
+
+// src/runtime/pg/postgresjs.ts
+function connect(target, options) {
+  if (isPool(target)) {
+    return createClient(options.schema, target, {
+      ownsPool: false,
+      http: options.errors?.http,
+      includeValues: options.errors?.includeValues,
+      logger: options.logger,
+      signal: options.signal,
+      timeout: options.timeout,
+      catalog: options.catalog,
+      catalogDir: options.catalogDir,
+      requireMeta: options.requireMeta
+    });
+  }
+  const url = target;
+  const pool = open2({
+    url,
+    ...options.max !== undefined ? { max: options.max } : {},
+    ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {},
+    ...options.prepared !== undefined ? { prepared: options.prepared } : {},
+    ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {},
+    ...options.ssl !== undefined ? { ssl: options.ssl } : {}
+  });
+  return createClient(options.schema, pool, {
+    ownsPool: true,
+    http: options.errors?.http,
+    includeValues: options.errors?.includeValues,
+    logger: options.logger,
+    signal: options.signal,
+    timeout: options.timeout,
+    catalog: options.catalog,
+    catalogDir: options.catalogDir,
+    requireMeta: options.requireMeta
+  });
+}
+function isPool(target) {
+  return typeof target === "object" && "execute" in target && "capabilities" in target;
+}
+export {
+  DriverError2 as DriverError,
+  POSTGRESJS_CAPABILITIES as capabilities,
+  connect,
+  hasCapability2 as hasCapability,
+  open2 as open,
+  readCapability2 as readCapability
+};

package/dist/runtime/plan.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Read planning: logical shape, one Postgres statement, decode.
+ *
+ * A cache hit walks the call once to bind parameters. SQL is built on a miss.
+ * Identifiers come from the catalog model. Values are parameters.
+ */
+import { type QueryCode } from "../contracts/error.js";
+import { type ColumnModel, type QuerySchema, type RelationModel, type TableModel } from "../dialects/pg/model.js";
+/** A read the caller asked for. */
+export type ReadOp = "find" | "one" | "count" | "exists";
+/** Routing constraint chosen before execute. */
+export type RouteConstraint = "auto" | "primary" | "replica";
+/** One read call. `all` is the `.all(reason)` escape for an unbounded read. */
+export type ReadCall = {
+    readonly op: ReadOp;
+    readonly table: string;
+    readonly where?: unknown;
+    readonly select?: unknown;
+    readonly orderBy?: unknown;
+    readonly limit?: unknown;
+    readonly include?: unknown;
+    readonly all?: string;
+};
+/** Where a decoded value sits. */
+export type ScalarOut = {
+    readonly key: string;
+    readonly at: number;
+    readonly decode: ((wire: string) => unknown) | undefined;
+};
+/** A nested include. `at` is a root column for `one` and the JSON column for `many`. */
+export type IncludeOut = {
+    readonly name: string;
+    readonly kind: "one" | "many";
+    readonly at: number;
+    readonly fields: readonly ScalarOut[];
+    readonly nested: readonly IncludeOut[];
+};
+/** Columns and includes in statement order. */
+export type Outputs = {
+    readonly fields: readonly ScalarOut[];
+    readonly includes: readonly IncludeOut[];
+};
+/** Mutable outputs while a plan is compiled. */
+/** Lateral include compiler. Loaded on the first include, not on a plain read. */
+export type IncludeHooks = {
+    read(schema: QuerySchema, table: Indexed, include: unknown, all: string | undefined): readonly ParsedInclude[];
+    select(include: ParsedInclude, alias: string, sink: Sink, outputs: Built | undefined, column: number): number;
+    join(schema: QuerySchema, include: ParsedInclude, sink: Sink, parentAlias: string, alias: string, depth: number): void;
+};
+export type Built = {
+    fields: ScalarOut[];
+    includes: IncludeOut[];
+};
+/** A cached physical plan. Parameters are not stored. */
+export type Plan = {
+    readonly fingerprint: string;
+    readonly text: string;
+    readonly mode: ReadOp;
+    readonly outputs: Outputs;
+};
+/** Bound parameters plus the cache key for one call. */
+export type Bound = {
+    readonly key: string;
+    readonly params: readonly (string | null)[];
+};
+/** A rule recorded for inspection. Provenance names who added it. */
+export type AppliedRule = {
+    readonly rule: string;
+    readonly contribution: string;
+    readonly provenance: string;
+};
+export type Indexed = {
+    readonly model: TableModel;
+    readonly columns: ReadonlyMap<string, ColumnModel>;
+    readonly relations: ReadonlyMap<string, RelationModel>;
+    readonly names: readonly string[];
+};
+export type Sink = {
+    text(value: string): void;
+    param(encoded: string): void;
+    mark(token: string): void;
+};
+/**
+ * Rules the read path enforces before planning.
+ *
+ * P21 adds the rest of the final safety verification here.
+ *
+ * @param rules - Rules already checked for this call
+ */
+export declare function verifyRead(rules: readonly AppliedRule[]): void;
+/**
+ * Binds a call: shape key and parameters, no SQL.
+ *
+ * @param schema - Connected schema
+ * @param call - The read
+ * @returns The cache key and the wire parameters
+ */
+export declare function bindCall(schema: QuerySchema, call: ReadCall, hooks?: IncludeHooks): Bound;
+/**
+ * Compiles a call to one statement.
+ *
+ * @param schema - Connected schema
+ * @param call - The read
+ * @param key - Shape key from {@link bindCall}
+ * @returns The plan
+ */
+export declare function compileCall(schema: QuerySchema, call: ReadCall, key: string, hooks?: IncludeHooks): Plan;
+/**
+ * Decodes driver rows into plain objects.
+ *
+ * @param plan - Compiled plan
+ * @param rows - Wire rows
+ * @param table - Table name, for `not_unique`
+ * @returns Rows, one row or null, a count, or a boolean
+ */
+export declare function decodeResult(plan: Plan, rows: readonly (readonly (string | null)[])[], table: string, rowOf?: (outputs: Outputs, row: readonly (string | null)[]) => Record<string, unknown>): unknown;
+/**
+ * Logical intent for inspection. Operators become plain tags.
+ *
+ * @param call - The read
+ * @returns A JSON-safe description, without a fingerprint
+ */
+export declare function logicalIntent(call: ReadCall): {
+    readonly op: ReadOp;
+    readonly table: string;
+    readonly where: unknown;
+    readonly select: unknown;
+    readonly orderBy: unknown;
+    readonly limit: unknown;
+    readonly include: unknown;
+    readonly all: string | undefined;
+};
+/**
+ * Rules for inspection, including the caller filter when one was passed.
+ *
+ * @param call - The read
+ * @returns Provenance-tagged rules
+ */
+export declare function appliedRules(call: ReadCall): readonly AppliedRule[];
+export declare function emitJoin(sink: Sink, parent: string, child: string, relation: RelationModel): void;
+export declare function emitWhere(schema: QuerySchema, table: Indexed, where: unknown, sink: Sink, alias: string, depth: number, appended?: boolean): void;
+export declare function emitOrder(table: Indexed, orderBy: unknown, sink: Sink, alias: string): void;
+export declare function emitPrimaryOrder(table: Indexed, sink: Sink, alias: string): void;
+export type ParsedInclude = {
+    readonly name: string;
+    readonly relation: RelationModel;
+    readonly where: unknown;
+    readonly orderBy: unknown;
+    readonly limit: number | undefined;
+    readonly columns: readonly ColumnModel[];
+    readonly presence: ColumnModel | undefined;
+    /** Index in the projected list that is null when the related row is missing. */
+    readonly anchor: number;
+    readonly nested: readonly ParsedInclude[];
+};
+export declare function selectedColumns(table: Indexed, select: unknown): readonly ColumnModel[];
+export declare function rejectKeys(value: Readonly<Record<string, unknown>>, accepted: readonly string[], where: string): void;
+export declare function readLimit(value: unknown): number;
+export declare function projectExpr(sql: string, dataType: string): string;
+export declare function jsonExpr(sql: string, dataType: string): string;
+export declare function decodeRow(outputs: Outputs, row: readonly (string | null)[]): Record<string, unknown>;
+export declare function cell(value: string | null | undefined, decode: ((wire: string) => unknown) | undefined): unknown;
+export declare function indexes(schema: QuerySchema): ReadonlyMap<string, Indexed>;
+export declare function quote(name: string): string;
+export declare function list(names: readonly string[]): string;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function fail(code: QueryCode, message: string): never;

package/dist/runtime/tx.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal transaction runner for multi-statement writes.
+ *
+ * One statement uses the pool. Several statements use `batch`, which reserves
+ * a connection, begins, and commits. Inside an open transaction, `batch` is a
+ * savepoint and does not commit the outer transaction (D124). A connection
+ * lost at commit is `outcome_unknown`. Public `tx` is P29.
+ */
+import type { DriverConnection, DriverPool, ExecuteOptions, ExecuteResult, Statement } from "../contracts/driver.js";
+/**
+ * Runs write statements as one atomic unit.
+ *
+ * @param pool - Endpoint pool
+ * @param statements - Statements in order
+ * @param options - Signal and timeout for the whole unit
+ * @returns One result per statement
+ */
+export declare function runWrite(pool: DriverPool, statements: readonly Statement[], options: ExecuteOptions | undefined): Promise<readonly ExecuteResult[]>;
+/**
+ * Runs statements on a connection the caller already reserved.
+ *
+ * An open transaction makes this a savepoint. The caller commits.
+ *
+ * @param connection - Reserved connection
+ * @param statements - Statements in order
+ * @param options - Signal and timeout
+ * @returns One result per statement
+ */
+export declare function runWriteOn(connection: DriverConnection, statements: readonly Statement[], options: ExecuteOptions | undefined): Promise<readonly ExecuteResult[]>;