okmodel 0.1.1 → 0.3.0

package/dist/dialects/pg/view/index.js

@@ -0,0 +1,289 @@
+import {
+  viewObject,
+  materializedViewObject,
+  materializedViewIndex
+} from "../../../shared/y005b761.js";
+import {
+  encodeUuid,
+  decodeUuid
+} from "../../../shared/dyj86cmj.js";
+import {
+  snakeCase
+} from "../../../shared/6w5j844a.js";
+import {
+  encodeText,
+  decodeText
+} from "../../../shared/4m9fn52z.js";
+import {
+  staticNamespace2
+} from "../../../shared/t4tbsy9h.js";
+import {
+  OkmError2
+} from "../../../shared/52szzakm.js";
+
+// src/dialects/pg/view/client.ts
+function viewClient(name, columns, query, tenancy) {
+  const field = camelCase(name);
+  const marked = readGlobal(name, tenancy);
+  return {
+    field,
+    install(model, scope, tables, casing, scoped) {
+      if (Object.hasOwn(model, field)) {
+        throw new OkmError2("OKM1023", `View ${name} uses the client name ${field}.`, {
+          fix: { summary: "Give the view a name that no table uses." }
+        });
+      }
+      const exposes = exposesKey(columns, scope);
+      if (scope !== undefined && readsTenant(query, tables, casing, scoped)) {
+        if (!exposes && marked === undefined) {
+          throw new OkmError2("OKM1820", `View ${name} reads a tenant table and does not expose ${scope.key}.`, {
+            fix: {
+              summary: "Expose the tenant key so the predicate can be applied, or declare global(reason)."
+            }
+          });
+        }
+        if (exposes) {
+          scope.scopeView(field);
+          scoped.add(name);
+        }
+      }
+      model[field] = {
+        name: field,
+        sql: name,
+        primary: [],
+        uniques: [],
+        columns: columnModels(columns, scope),
+        relations: []
+      };
+    },
+    hook(target, ctx) {
+      publish(field, target, ctx);
+    }
+  };
+}
+function publish(field, target, ctx) {
+  if (ctx.tables === undefined || ctx.table !== undefined)
+    return;
+  const handle = ctx.tables[field];
+  if (typeof handle !== "object" || handle === null)
+    return;
+  const source = handle;
+  const views = target.views;
+  const map = typeof views === "object" && views !== null ? views : {};
+  map[field] = {
+    find: source.find,
+    one: source.one,
+    count: source.count,
+    exists: source.exists
+  };
+  target.views = map;
+  delete ctx.tables[field];
+  delete target[field];
+}
+function columnModels(columns, tenancy) {
+  const seen = new Set;
+  const models = [];
+  for (const column of columns) {
+    const field = fieldName(column.name, tenancy);
+    if (seen.has(field)) {
+      throw new OkmError2("OKM1020", `View column ${column.name} repeats ${field}.`, {
+        fix: { summary: "Declare each output column once." }
+      });
+    }
+    seen.add(field);
+    const uuid = column.type.toLowerCase() === "uuid";
+    const key = tenancy !== undefined && field === tenancy.key;
+    models.push({
+      field,
+      sql: column.name,
+      dataType: column.type,
+      encode: uuid ? (value) => encodeUuid(textValue(value)) : (value) => encodeText(textValue(value)),
+      decode: uuid ? decodeUuid : decodeText,
+      hidden: false,
+      sensitive: false,
+      guarded: key,
+      writable: false,
+      guardUpdate: false
+    });
+  }
+  return models;
+}
+function exposesKey(columns, tenancy) {
+  if (tenancy === undefined)
+    return false;
+  return columns.some((column) => fieldName(column.name, tenancy) === tenancy.key);
+}
+function readsTenant(query, tables, casing, scoped) {
+  for (const name of scoped) {
+    if (mentions(query, name))
+      return true;
+  }
+  for (const table of tables) {
+    const mark = table.options?.tenancy;
+    if (isGlobalMark(mark))
+      continue;
+    const sql = casing === "snake" ? snakeCase(table.name) : table.name;
+    if (mentions(query, sql) || mentions(query, table.name))
+      return true;
+  }
+  return false;
+}
+function readGlobal(name, tenancy) {
+  if (tenancy === undefined)
+    return;
+  if (!isGlobalMark(tenancy)) {
+    throw new OkmError2("OKM1020", `View ${name} tenancy must be global("reason").`, {
+      fix: { summary: 'Pass global("reason") from okmodel/tenancy, or omit tenancy.' }
+    });
+  }
+  return tenancy.reason;
+}
+function isGlobalMark(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const record = value;
+  return record.kind === "global" && typeof record.reason === "string" && record.reason.trim().length > 0;
+}
+function fieldName(column, tenancy) {
+  const field = camelCase(column);
+  if (tenancy !== undefined && (column === tenancy.key || field === tenancy.key))
+    return tenancy.key;
+  return field;
+}
+function camelCase(name) {
+  let out = "";
+  let upper = false;
+  for (const char of name) {
+    if (char === "_") {
+      upper = out.length > 0;
+      continue;
+    }
+    out += upper ? char.toUpperCase() : char;
+    upper = false;
+  }
+  return out;
+}
+function mentions(query, name) {
+  let pattern = '(^|[^A-Za-z0-9_])"?';
+  for (const char of name) {
+    if ("\\^$[]().*+?|{}".includes(char))
+      pattern += "\\";
+    pattern += char;
+  }
+  pattern += '"?(?![A-Za-z0-9_])';
+  return new RegExp(pattern).test(query);
+}
+function textValue(value) {
+  if (typeof value !== "string") {
+    throw new OkmError2("OKM1121", "A view column value must be text.", {
+      fix: { summary: "Pass a string." }
+    });
+  }
+  return value;
+}
+
+// src/dialects/pg/view/index.ts
+function view(name, options) {
+  const schema = options.schema ?? "public";
+  const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
+  const query = bodyText(options.query);
+  const bound = viewClient(name, options.columns, query, options.tenancy);
+  return {
+    name,
+    schema,
+    install: bound.install,
+    hook: bound.hook,
+    contribute(peers, built) {
+      assertPeers(peers);
+      assertNoTable(built, name);
+      const provenance = { origin: "file", name };
+      return [
+        viewObject({
+          namespace: staticNamespace2(schema),
+          name,
+          columns,
+          query,
+          provenance
+        })
+      ];
+    }
+  };
+}
+function materializedView(name, options) {
+  const schema = options.schema ?? "public";
+  const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
+  const query = bodyText(options.query);
+  const bound = viewClient(name, options.columns, query, options.tenancy);
+  const indexes = options.indexes ?? [];
+  if (options.refresh === "concurrently" && !indexes.some((index) => index.unique === true)) {
+    throw new OkmError2("OKM1822", `Materialized view ${name} refreshes concurrently and has no unique index.`, { fix: { summary: "Add a unique index, or refresh without CONCURRENTLY." } });
+  }
+  const columnNames = new Set(columns.map((column) => column.name));
+  for (const index of indexes) {
+    for (const column of index.columns) {
+      if (!columnNames.has(column)) {
+        throw new OkmError2("OKM1020", `Index on ${name} names column ${column}, which the materialized view does not have.`, { fix: { summary: "Name a column of the materialized view." } });
+      }
+    }
+  }
+  return {
+    name,
+    schema,
+    install: bound.install,
+    hook: bound.hook,
+    contribute(peers, built) {
+      assertPeers(peers);
+      assertNoTable(built, name);
+      const namespace = staticNamespace2(schema);
+      const provenance = { origin: "file", name };
+      const parent = { namespace, name };
+      return [
+        materializedViewObject({
+          namespace,
+          name,
+          columns,
+          query,
+          provenance,
+          ...options.refresh === "concurrently" ? { refresh: "concurrently" } : {}
+        }),
+        ...indexes.map((index) => materializedViewIndex({
+          parent,
+          ...index.name !== undefined ? { name: index.name } : {},
+          columns: index.columns,
+          ...index.unique === true ? { unique: true } : {},
+          provenance
+        }))
+      ];
+    }
+  };
+}
+function bodyText(body) {
+  return typeof body === "string" ? body : body.text;
+}
+function assertPeers(peers) {
+  if (!Array.isArray(peers)) {
+    throw new OkmError2("OKM1020", "schema({ views }) must be a list.", {
+      fix: { summary: "Pass an array to schema({ views })." }
+    });
+  }
+}
+function assertNoTable(built, name) {
+  if (!Array.isArray(built))
+    return;
+  for (const object of built) {
+    if (!isRecord(object) || object.kind !== "table" || !isRecord(object.identity))
+      continue;
+    if (object.identity.name === name) {
+      throw new OkmError2("OKM1023", `View ${name} uses the name of a table.`, {
+        fix: { summary: "Give the view a name that no table uses." }
+      });
+    }
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  materializedView,
+  view
+};

package/dist/dialects/pg/view/scratch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Verifies declared views on a scratch schema.
+ *
+ * Tables from the catalog are created there, then each view. `pg_get_viewdef`
+ * replaces the author query and `pg_depend` supplies column edges (D117).
+ * The scratch schema is dropped before this returns. Plans never use it.
+ */
+import type { Catalog } from "../../../contracts/catalog/types.js";
+import type { CatalogQuery } from "../introspect.js";
+/**
+ * Reads dependencies and reprints for every view in `source`.
+ *
+ * The returned catalog matches what introspection prints for those views
+ * when the same query is applied. A declared column list that disagrees
+ * with the database is OKM1020.
+ *
+ * @param runner - Database connection. Statements share its session
+ * @param source - Catalog whose views are still author SQL
+ * @returns A catalog whose views carry the reprint and `pg_depend` edges
+ */
+export declare function sealViews(runner: CatalogQuery, source: Catalog): Promise<Catalog>;

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

@@ -0,0 +1,37 @@
+/**
+ * Where-value types shared by the client and by presets.
+ *
+ * They sit in the dialect layer so `table({ presets })` can type a preset's
+ * `where` without importing the client types. `runtime/types.ts` re-exports
+ * the two names callers use.
+ */
+import type { Between, Compare, Containment, Eq, HasAnyKey, HasKey, InList, Matches, Trigram, Not, NotIn, Overlaps, Path, Pattern, RawPattern } from "./operators.js";
+import type { Range } from "./range.js";
+export type IsObject<V> = V extends object ? V extends readonly unknown[] ? false : null extends V ? false : true : false;
+/** Text patterns, including substring `contains`. `matches` is for tsvector, which is also `string`. */
+type TextOps = Pattern<"startsWith"> | Pattern<"contains"> | Pattern<"endsWith"> | RawPattern<"like"> | RawPattern<"ilike"> | Matches | Trigram<"similar"> | Trigram<"wordSimilar">;
+/** Array, jsonb, or range containment, plus overlap where that operator fits. */
+type StructuredOps<V> = Containment<"contains" | "containedBy", V> | Overlaps<V>;
+/** A JSON fragment. Containment matches part of a document, not the whole column type. */
+type JsonFragment = string | number | boolean | null | readonly JsonFragment[] | {
+    readonly [key: string]: JsonFragment;
+};
+/** jsonb and json filters. `hasKey` is rejected at runtime on json. */
+type JsonOps = Containment<"contains" | "containedBy", JsonFragment> | HasKey | HasAnyKey | Path<string> | Path<number> | Path<boolean>;
+/**
+ * A plain object that can be json or jsonb.
+ *
+ * Arrays, ranges, and bytea are not json. Timestamp values are objects too, and
+ * the Temporal declarations are structural, so a timestamp column is rejected
+ * at runtime (OKM1124) rather than here.
+ */
+export type IsJsonObject<V> = V extends readonly unknown[] ? false : V extends Range<unknown> ? false : V extends Uint8Array ? false : IsObject<V>;
+/** Operators the column value type can accept. `unknown` keeps every family and the runtime decides. */
+type TypedOps<V> = [unknown] extends [V] ? TextOps | StructuredOps<V> | JsonOps : (V extends string ? TextOps : never) | (V extends readonly unknown[] ? StructuredOps<V> : never) | (V extends Range<unknown> ? StructuredOps<V> : never) | (IsJsonObject<V> extends true ? JsonOps : never);
+/** A where operand. Object columns take `eq`, not a bare object. */
+export type WhereValue<V> = V extends unknown ? (IsObject<V> extends true ? never : V) | null | Eq<V> | Compare<"lt", V> | Compare<"lte", V> | Compare<"gt", V> | Compare<"gte", V> | Between<V> | InList<V> | NotIn<V> | Not<V | null | TextOps | InList<V>> | TypedOps<V> : never;
+/** Field filters. Relation filters are one level, so the type does not cycle. */
+export type FieldWhere<Row> = {
+    readonly [K in keyof Row]?: WhereValue<Row[K]> | undefined;
+};
+export {};

package/dist/runtime/aggregate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Grouped aggregates (spec section 10).
+ *
+ * `count`, `sum`, `avg`, `min`, and `max` over the rows a `where` selects, per
+ * `groupBy` group. The statement is written here and the `where` is written by
+ * the planner's `emitWhere`, so the tenant and active-set predicates apply to
+ * every aggregate exactly as they apply to a `find`. This module loads on the
+ * first `aggregate()`.
+ *
+ * Not here: `having`, `bucket`, and ordering by an aggregate. A hidden column
+ * cannot be grouped or aggregated, so an aggregate never shows what a read hides.
+ */
+import { type Mods, type Session } from "./client.js";
+import { type ArchiveView } from "./plan.js";
+/**
+ * Builds the handle for one `aggregate()` call.
+ *
+ * @param session - Client session
+ * @param table - Table name
+ * @param options - `where`, `groupBy`, the aggregates, `orderBy`, and `limit`
+ * @param mods - `.all` reason, signal, and timeout
+ * @param view - Archive visibility
+ * @returns A handle that resolves to the grouped rows
+ */
+export declare function build(session: Session, table: string, options: object, mods: Mods, view: ArchiveView | undefined): Promise<unknown> & Record<string, unknown>;

package/dist/runtime/archive-handle.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Table methods `archivable()` adds through the shared client hook.
+ *
+ * Core does not name `archive` or `restore`. A failed import of the statement
+ * chunk rejects the call. The active-set predicate stays in the planner.
+ */
+import type { SchemaHookCtx } from "../dialects/pg/model.js";
+/**
+ * Adds `archive`, `restore`, `withArchived`, and `onlyArchived` to one table.
+ *
+ * A table that is not archivable still receives the methods when the schema
+ * imported the trait, and a call throws OKM1052. The throw for a missing model
+ * is repeated by the statement chunk if execution reaches it.
+ *
+ * @param target - The table handle being built
+ * @param ctx - Table name, visibility, and the session
+ */
+export declare function attachArchive(target: Record<string, unknown>, ctx: SchemaHookCtx): void;

package/dist/runtime/archive-rules.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Phrases the archive safety rule reads.
+ *
+ * Installed by `archivable()`. A schema that does not use the trait does not
+ * load this file, and reads record nothing.
+ */
+/**
+ * Installs the phrase recorder on the planner.
+ *
+ * Safe to call more than once. The recorder replaces the previous one.
+ */
+export declare function installArchiveContributions(): void;

package/dist/runtime/archive.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `archive` and `restore`.
+ *
+ * Loaded on the first call. A failed import fails that call. The active-set
+ * predicate stays in the planner, so a failed import does not show archived rows.
+ */
+import type { QuerySchema } from "../dialects/pg/model.js";
+import { type CallScope } from "./plan.js";
+import { type RunHost } from "./tx.js";
+import type { PreparedWrite } from "./write.js";
+type LifecycleOp = "archive" | "restore";
+type Mods = {
+    readonly all?: string;
+    readonly expect?: number;
+    /** Filters the chained presets added. The archive handle resolves them. */
+    readonly presets?: readonly unknown[];
+};
+type Host = RunHost & {
+    readonly schema: QuerySchema;
+};
+/**
+ * Archives or restores matching rows.
+ *
+ * One statement. Cascaded children share the `archiveId`. A restore whose
+ * parent is still archived changes nothing and fails.
+ *
+ * @param host - Schema and pool
+ * @param op - `archive` or `restore`
+ * @param table - Table name
+ * @param input - `{ where }` or, for restore, `{ archiveId }`
+ * @param options - `expect`, signal, and timeout
+ * @param mods - `.all` and `.expect`
+ * @param scope - Tenant value, when the schema has tenancy
+ * @returns `{ count, archiveId }` or `{ count }`
+ */
+export declare function executeArchive(host: Host, op: LifecycleOp, table: string, input: unknown, options: object, mods: Mods, scope: CallScope | undefined): Promise<{
+    readonly count: number;
+    readonly archiveId?: string;
+}>;
+/**
+ * Plans archive or restore and returns its statement and the function that decodes the result.
+ *
+ * `batch` runs the statement with those of other operations.
+ *
+ * @param schema - Connected schema
+ * @param op - `archive` or `restore`
+ * @param table - Table name
+ * @param input - `{ where }` or `{ archiveId }`
+ * @param options - `expect`, signal, and timeout
+ * @param mods - `.all` and `.expect`
+ * @param scope - Tenant value, when the schema has tenancy
+ * @returns The statement, the call options, and `finish`
+ */
+export declare function prepareArchive(schema: QuerySchema, op: LifecycleOp, table: string, input: unknown, options: object, mods: Mods, scope: CallScope | undefined): PreparedWrite;
+/**
+ * Plans archive or restore and does not run it.
+ *
+ * @param schema - Connected schema
+ * @param op - `archive` or `restore`
+ * @param table - Table name
+ * @param input - `{ where }` or `{ archiveId }`
+ * @param options - `expect`, signal, and timeout
+ * @param mods - `.all` and `.expect`
+ * @param scope - Tenant value, when the schema has tenancy
+ * @returns The statement
+ */
+export declare function explainArchive(schema: QuerySchema, op: LifecycleOp, table: string, input: unknown, options: object, mods: Mods, scope: CallScope | undefined): {
+    readonly statements: readonly {
+        readonly text: string;
+        readonly params: readonly (string | null)[];
+    }[];
+};
+export {};

package/dist/runtime/batch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Public `batch` (spec §15, batch contract).
+ *
+ * Plans each operation, joins their statements, and runs them as one atomic
+ * unit on the primary. Results come back in the order given. A failure rolls
+ * everything back and the error carries `batchIndex`, the failing operation,
+ * or `null` when the commit failed. Inside `tx()` the unit is a savepoint, so
+ * the transaction survives. Loaded the first time a batch is awaited.
+ */
+import { type Session } from "./client.js";
+/**
+ * Runs write handles as one atomic unit.
+ *
+ * @param session - Client session
+ * @param ops - Write handles: `insert`, `update`, `delete`, `archive`. A `restore`, or a write with `expect`, is OKM1121 (D183)
+ * @param options - `signal` and `timeout` for the whole batch
+ * @param replica - Set by `.replica()`. A batch needs the primary (OKM1840)
+ * @returns One result per operation, in order
+ */
+export declare function batch(session: Session, ops: unknown, options: object | undefined, replica: true | undefined): Promise<readonly unknown[]>;

package/dist/runtime/client.d.ts

@@ -5,11 +5,13 @@
  * 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 = {
+import type { IdGenerators } from "../contracts/generator.js";
+import { OkmError, type ErrorStatuses, type OkmErrorOptions } from "../contracts/error.js";
+import type { PresetUse, QuerySchema } from "../dialects/pg/model.js";
+import { type ArchiveView, type Plan, type ReadCall, type CallScope, type ReadOp } from "./plan.js";
+import type { CatalogArtifact, Connected, Hookm, Timeouts } from "./types.js";
+/** A client's connection state. The lazy read modules take it. */
+export type Session = {
     readonly schema: QuerySchema;
     readonly pool: DriverPool;
     readonly ownsPool: boolean;
@@ -23,6 +25,29 @@ type Session = {
     } | undefined;
     readonly connected: Promise<void>;
     readonly cache: Map<string, Plan>;
+    readonly generators: IdGenerators | undefined;
+    /** Ceilings from `connect({ timeouts })`. */
+    readonly timeouts: Timeouts | undefined;
+    /** Observers from `connect({ hookm })`. */
+    readonly hookm: readonly Hookm[] | undefined;
+    /** Set on the client a transaction hands out. `extras` are the methods only that client has. */
+    readonly tx?: {
+        readonly extras: object;
+        readonly depth: number;
+    };
+    /** Tenant value or an unscoped reason. Absent on the root client. */
+    readonly scope?: CallScope;
+    /** Shared close. `for()` and `unscoped()` reuse the same promise. */
+    readonly closing: {
+        current: Promise<void> | undefined;
+    };
+};
+/** Per-call modifiers of a read. */
+export type Mods = {
+    readonly all?: string;
+    readonly required?: boolean;
+    /** Presets chained on the handle. The presets module resolves them on first use. */
+    readonly uses?: PresetUse | undefined;
 };
 /**
  * Builds a client for one pool.
@@ -40,8 +65,92 @@ export declare function createClient<S extends QuerySchema>(schema: S, pool: Dri
     readonly logger?: Session["logger"] | undefined;
     readonly signal?: AbortSignal | undefined;
     readonly timeout?: number | undefined;
+    readonly timeouts?: Timeouts | undefined;
+    readonly hookm?: readonly Hookm[] | undefined;
     readonly catalog?: CatalogArtifact | undefined;
     readonly catalogDir?: string | undefined;
     readonly requireMeta?: boolean | undefined;
+    readonly generators?: IdGenerators | undefined;
 }): Connected<S>;
+export declare function openClient<S extends QuerySchema>(session: Session): Connected<S>;
+/**
+ * A query handle that starts its work once, the first time it is awaited.
+ *
+ * @param run - The work. Called at most once
+ * @param extra - Methods that stay on the handle beside `then`
+ * @returns The handle
+ */
+export declare function queryHandle<T extends object>(run: () => Promise<unknown>, extra: T): Promise<unknown> & T;
+/** A bound plan and its wire parameters. */
+type Prepared = {
+    readonly plan: Plan;
+    readonly params: readonly (string | null)[];
+};
+/** Rows as the driver returns them. */
+type Rows = readonly (readonly (string | null)[])[];
+/**
+ * Decodes the rows of a prepared read, with includes when the plan has them.
+ *
+ * @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 decodeRows(plan: Plan, rows: Rows, table: string): Promise<unknown>;
+/**
+ * A lazy read handle for one planned call.
+ *
+ * `find`, `one`, `count`, and `exists` use it, and so do the lazy `page` and
+ * `aggregate` modules. It plans once, caches the plan per client, maps the
+ * error, and offers `inspect` and `sql`.
+ *
+ * @param session - Client session
+ * @param table - Table name
+ * @param call - The read
+ * @param mods - Signal and timeout
+ * @param decode - Turns the wire rows into the result
+ * @param extra - Methods that belong to this read, given the memoised prepare
+ * @returns The handle
+ */
+export declare function readHandle(session: Session, table: string, call: ReadCall, mods: Mods, decode: (plan: Plan, rows: Rows) => unknown, extra?: (prepare: () => Promise<Prepared>) => Record<string, unknown>): Promise<unknown> & Record<string, unknown>;
+/**
+ * Builds the logical read from caller options.
+ *
+ * @param op - Read kind
+ * @param table - Table name
+ * @param options - `where`, `select`, `orderBy`, `limit`, `include`
+ * @param all - Reason given to `.all`
+ * @param scope - Tenant scope, when the client has one
+ * @param model - Table model
+ * @param schema - Connected schema
+ * @param view - Archive visibility
+ * @returns The call the planner binds
+ */
+export declare function readCall(op: ReadOp, table: string, options: object, all: string | undefined, scope: CallScope | undefined, model: QuerySchema["model"][string] | undefined, schema: QuerySchema, view?: ArchiveView): ReadCall;
+/**
+ * Attaches connect's HTTP statuses to options for one {@link OkmError}.
+ *
+ * @param http - Statuses from `connect({ errors })`
+ * @param options - Error options that do not yet name a status map
+ * @returns Options `toHttp()` can read
+ */
+export declare function withHttp(http: ErrorStatuses | undefined, options: OkmErrorOptions): OkmErrorOptions;
+/**
+ * Copies `error` so {@link OkmError.toHttp} uses the statuses from `connect`.
+ *
+ * @param http - Statuses from `connect({ errors })`. Omitted, `error` is returned
+ * @param error - Failure that did not carry those statuses
+ * @returns The error `toHttp()` reads
+ */
+export declare function attachHttp(http: ErrorStatuses | undefined, error: OkmError): OkmError;
+/**
+ * Maps a driver or query error and records it on the session logger.
+ *
+ * The archive hook uses this so a failed statement stays an `OkmError`.
+ *
+ * @param session - Pool, statuses, and logger
+ * @param error - Rejection from the driver or the statement chunk
+ * @returns Never. The mapped error is thrown
+ */
+export declare function settleCall(session: Session, error: unknown): Promise<never>;
 export {};

package/dist/runtime/conflict.d.ts

@@ -17,9 +17,10 @@ export type ConflictPlan = {
  *
  * @param table - Target table
  * @param value - The option the caller passed
+ * @param allow - Guarded fields this write may set
  * @returns The plan, or `undefined` for the default `"error"`
  */
-export declare function readConflict(table: Indexed, value: unknown): ConflictPlan | undefined;
+export declare function readConflict(table: Indexed, value: unknown, allow?: ReadonlySet<string>): ConflictPlan | undefined;
 /**
  * Appends the conflict clause, or wraps a first-or-create insert.
  *

package/dist/runtime/exposure.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Redaction for hidden and sensitive fields.
+ *
+ * Loaded the first time a concealed table is inspected or a read of one fails.
+ */
+import { OkmError } from "../contracts/error.js";
+import type { QuerySchema } from "../dialects/pg/model.js";
+import type { ReadCall } from "./plan.js";
+import type { Inspection } from "./types.js";
+/**
+ * Replaces concealed values in an inspection and records the exposure rules.
+ *
+ * @param schema - Connected schema
+ * @param view - Inspection that still holds the real values
+ * @param call - The read, used to encode parameter values and to see `select`
+ * @returns The inspection a caller can print
+ */
+export declare function redactView(schema: QuerySchema, view: Inspection, call: ReadCall): Inspection;
+/**
+ * Removes concealed values from a read error.
+ *
+ * @param error - Failure from the driver or the planner
+ * @param schema - Connected schema
+ * @param call - The read whose hidden or sensitive values may have been echoed
+ * @returns The error, with those values replaced
+ */
+export declare function scrubCall(error: OkmError, schema: QuerySchema, call: ReadCall): OkmError;