okmodel 0.1.1 → 0.2.1

package/dist/runtime/pg/postgresjs.js

@@ -1,36 +1,23 @@
 import {
   DriverError2
-} from "../../shared/hd293j9g.js";
+} from "../../shared/kyxb62mc.js";
 import {
   open2
-} from "../../shared/dkn3y60a.js";
-import {
-  createClient
-} from "../../shared/rgs0st28.js";
+} from "../../shared/ecdzej21.js";
 import {
   POSTGRESJS_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/xy79j5hq.js";
+} from "../../shared/9k6vetvf.js";
+import {
+  createClient
+} from "../../shared/mxmcdsh5.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,
+  const owned = !isPool(target);
+  const pool = isPool(target) ? target : open2({
+    url: target,
     ...options.max !== undefined ? { max: options.max } : {},
     ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {},
     ...options.prepared !== undefined ? { prepared: options.prepared } : {},
@@ -38,15 +25,18 @@ function connect(target, options) {
     ...options.ssl !== undefined ? { ssl: options.ssl } : {}
   });
   return createClient(options.schema, pool, {
-    ownsPool: true,
+    ownsPool: owned,
     http: options.errors?.http,
     includeValues: options.errors?.includeValues,
     logger: options.logger,
     signal: options.signal,
     timeout: options.timeout,
+    timeouts: options.timeouts,
+    hookm: options.hookm,
     catalog: options.catalog,
     catalogDir: options.catalogDir,
-    requireMeta: options.requireMeta
+    requireMeta: options.requireMeta,
+    generators: options.generators
   });
 }
 function isPool(target) {

package/dist/runtime/plan.d.ts

@@ -5,11 +5,26 @@
  * Identifiers come from the catalog model. Values are parameters.
  */
 import { type QueryCode } from "../contracts/error.js";
+import { type OperatorName } from "../dialects/pg/operators.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";
+export type ReadOp = "find" | "one" | "count" | "exists" | "aggregate";
 /** Routing constraint chosen before execute. */
 export type RouteConstraint = "auto" | "primary" | "replica";
+/**
+ * Tenant scope for one call.
+ *
+ * The value is a parameter. The cache key records `tenant` or `unscoped`, not the value.
+ */
+export type CallScope = {
+    readonly value: string;
+} | {
+    readonly unscoped: string;
+};
+/** Writes one more `where` condition after the tenant and active-set predicates. */
+export type Keyset = (sink: Sink, alias: string) => void;
+/** Writes the whole statement of a read the planner does not know. */
+export type ReadBuild = (schema: QuerySchema, table: Indexed, sink: Sink, outputs: Built | undefined, call: ReadCall) => void;
 /** One read call. `all` is the `.all(reason)` escape for an unbounded read. */
 export type ReadCall = {
     readonly op: ReadOp;
@@ -20,7 +35,57 @@ export type ReadCall = {
     readonly limit?: unknown;
     readonly include?: unknown;
     readonly all?: string;
+    /** The `after` cursor of a `page`. The condition joins the others with `and`. */
+    readonly after?: Keyset;
+    /** Set by `aggregate`. It writes the statement and the safety predicates stay in `emitWhere`. */
+    readonly build?: ReadBuild;
+    /** Writes the end of the statement, after `limit`. A row lock sets it. */
+    readonly tail?: (sink: Sink) => void;
+    /** The caller's `signal` and `timeout`. They never enter the plan or its key. */
+    readonly signal?: AbortSignal;
+    readonly timeout?: number;
+    /** Set by `for()` or `unscoped()`. Absent on a schema with no tenancy. */
+    readonly scope?: CallScope;
+    /** Inspect lines from the tenancy object. Absent when the schema has no tenancy. */
+    readonly tenancyRules?: readonly AppliedRule[];
+    /** `withArchived` or `onlyArchived`. Absent means the active set. */
+    readonly archive?: ArchiveView;
+    /** Inspect lines for the archive set and for presets. Absent when neither applies. */
+    readonly ruleLines?: readonly AppliedRule[];
 };
+/** How an archivable read or write chooses rows. Absent means the active set. */
+export type ArchiveView = "with" | "only";
+/**
+ * Runs `fn` with a tenant scope and an archive visibility visible to {@link emitWhere}.
+ *
+ * Restores both, including when `fn` throws. Sync callers finish the statement
+ * before the first await.
+ *
+ * @param scope - Tenant value or an unscoped reason
+ * @param view - `with` or `only`. `undefined` is the active set
+ * @param fn - Statement builder
+ * @returns Whatever `fn` returns
+ */
+export declare function withRowFilters<T>(scope: CallScope | undefined, view: ArchiveView | undefined, fn: () => T): T;
+type ArchiveInspect = (model: TableModel | undefined, view: ArchiveView | undefined) => readonly AppliedRule[] | undefined;
+/**
+ * Installs the phrase recorder `archivable()` owns.
+ *
+ * A featureless schema never calls this, so the phrases stay out of startup.
+ *
+ * @param fn - Builds the lines for one table
+ */
+export declare function installArchiveInspect(fn: ArchiveInspect): void;
+/**
+ * Inspect lines for one archivable table.
+ *
+ * Absent when the trait was not installed, or the table is not archivable.
+ *
+ * @param model - Table model
+ * @param view - `with` or `only`. `undefined` is the active set
+ * @returns The lines, or `undefined`
+ */
+export declare function archiveRules(model: TableModel | undefined, view: ArchiveView | undefined): readonly AppliedRule[] | undefined;
 /** Where a decoded value sits. */
 export type ScalarOut = {
     readonly key: string;
@@ -68,6 +133,8 @@ export type AppliedRule = {
     readonly rule: string;
     readonly contribution: string;
     readonly provenance: string;
+    /** `file.ts:line` where the rule or the table was defined. */
+    readonly source?: string;
 };
 export type Indexed = {
     readonly model: TableModel;
@@ -81,13 +148,49 @@ export type Sink = {
     mark(token: string): void;
 };
 /**
- * Rules the read path enforces before planning.
+ * Option names `find`, `one`, `count`, and `exists` accept.
+ *
+ * @param op - The read
+ * @returns Names in a stable order
+ */
+export declare function readOptionNames(op: ReadOp): readonly string[];
+/** 0.2 operator SQL. Absent until that module has been imported. */
+type OperatorEmit = (column: ColumnModel, ref: string, name: OperatorName, value: unknown, sink: Sink) => void;
+/**
+ * Installs the 0.2 operator compiler.
  *
- * P21 adds the rest of the final safety verification here.
+ * Called when `operator-sql` loads. A second install replaces the first.
  *
- * @param rules - Rules already checked for this call
+ * @param emit - Compiler for containment, keys, paths, and matches
  */
-export declare function verifyRead(rules: readonly AppliedRule[]): void;
+export declare function installOperatorSql(emit: OperatorEmit): void;
+/**
+ * Reports whether planning this read has to load the 0.2 operator module first.
+ *
+ * Equality, comparisons, and text patterns plan without it.
+ *
+ * @param schema - Connected schema
+ * @param call - The read
+ * @returns `true` when {@link installOperatorSql} has not run and the read needs it
+ */
+export declare function readNeedsOperatorSql(schema: QuerySchema, call: ReadCall): boolean;
+/**
+ * Writes `<table> <alias> where <link to parent>` for a to-many relation.
+ *
+ * A `manyThrough` relation reads the join table and joins the related table.
+ * The caller adds the related table's own predicates after it.
+ */
+export declare function emitRelationFrom(schema: QuerySchema, relation: RelationModel, child: Indexed, sink: Sink, parent: string, alias: string, depth: number): void;
+/**
+ * Runs registered safety rules before planning.
+ *
+ * Nothing runs until `okmodel/safety` has registered a rule. The startup
+ * graph pays for the check, not for the registry.
+ *
+ * @param schema - Connected schema
+ * @param call - The read
+ */
+export declare function verifyRead(schema: QuerySchema, call: ReadCall): void;
 /**
  * Binds a call: shape key and parameters, no SQL.
  *
@@ -133,12 +236,15 @@ export declare function logicalIntent(call: ReadCall): {
 /**
  * Rules for inspection, including the caller filter when one was passed.
  *
+ * Catalog rules carry `source` when the table recorded one.
+ *
  * @param call - The read
+ * @param source - `file.ts:line` of the table, when `table()` recorded it
  * @returns Provenance-tagged rules
  */
-export declare function appliedRules(call: ReadCall): readonly AppliedRule[];
+export declare function appliedRules(call: ReadCall, source?: string): 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 emitWhere(schema: QuerySchema, table: Indexed, where: unknown, sink: Sink, alias: string, depth: number, appended?: boolean, extra?: Keyset): 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 = {
@@ -154,8 +260,24 @@ export type ParsedInclude = {
     readonly nested: readonly ParsedInclude[];
 };
 export declare function selectedColumns(table: Indexed, select: unknown): readonly ColumnModel[];
+export declare function parseOrder(field: string, value: unknown): {
+    readonly dir: "asc" | "desc";
+    readonly nulls: "first" | "last";
+};
 export declare function rejectKeys(value: Readonly<Record<string, unknown>>, accepted: readonly string[], where: string): void;
 export declare function readLimit(value: unknown): number;
+/**
+ * Lets an object through only when the column's codec takes it (OKM1121).
+ *
+ * A column whose codec takes only scalars has no `accepts`, so every object is
+ * refused for it. A bare object in a `where` is refused for every column; the
+ * operators and `eq` are the explicit forms (D125).
+ *
+ * @param column - Target column
+ * @param value - The object
+ * @param bare - Whether the object sits in a `where` without `eq`
+ */
+export declare function takeObject(column: ColumnModel, value: object, bare?: boolean): void;
 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>;
@@ -164,4 +286,21 @@ export declare function indexes(schema: QuerySchema): ReadonlyMap<string, Indexe
 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>;
+/**
+ * Records the fix text for a code thrown from a chunk that loads on first use.
+ *
+ * A read does not carry the write, conflict, or include sentences. The module
+ * that throws the code registers the same sentence before it can throw.
+ *
+ * @param code - Spec code
+ * @param summary - Fix sentence `fail` attaches
+ */
+export declare function registerFailFix(code: QueryCode, summary: string): void;
+/**
+ * Throws an {@link OkmError} for a query the planner rejects.
+ *
+ * @param code - Spec code
+ * @param message - What failed
+ */
 export declare function fail(code: QueryCode, message: string): never;
+export {};

package/dist/runtime/preset-stack.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Puts preset filters after a caller's filter.
+ *
+ * Kept apart from the presets module so a write or an archive that uses no
+ * preset does not load the code that runs them.
+ */
+/**
+ * Joins a caller's `where` and the filters presets added, with AND.
+ *
+ * The planner reads the result like any `where`, so the tenant predicate and
+ * the active set are written around it and cannot be dropped by a preset.
+ *
+ * @param where - The caller's `where`, when there is one
+ * @param presets - Filters the presets added, in call order. Absent or empty adds nothing
+ * @returns The same `where`, or one that also holds the preset filters
+ */
+export declare function stack(where: unknown, presets: readonly unknown[] | undefined): unknown;

package/dist/runtime/presets.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Runs the presets chained on a table handle.
+ *
+ * Loaded on the first call that uses a preset. A schema with no preset, and a
+ * call that chains none, never load this file.
+ *
+ * A preset gets a builder with one method, `where`, which adds a filter. The
+ * filters join the caller's with AND (`stack`), and the planner writes the
+ * tenant predicate and the active set around the result, so no preset can
+ * remove either one (D125, D126).
+ */
+import type { PresetUse, QuerySchema } from "../dialects/pg/model.js";
+import type { AppliedRule, ReadCall } from "./plan.js";
+/** The filters a chain of presets added, and the inspect lines that name them. */
+export type Resolved = {
+    readonly wheres: readonly unknown[];
+    readonly rules: readonly AppliedRule[];
+};
+/**
+ * Fails on a preset name that is a client method or reserved.
+ *
+ * Runs when the client connects, for every table that has presets, so a bad
+ * name fails before the first query and not at the first preset call.
+ *
+ * @param schema - Connected schema
+ */
+export declare function checkSchema(schema: QuerySchema): void;
+/**
+ * Runs the chained presets and collects what each one added.
+ *
+ * @param schema - Connected schema
+ * @param table - Table the chain is on
+ * @param uses - The last preset call in the chain
+ * @returns The filters, in call order, and one `preset` rule per call
+ */
+export declare function resolve(schema: QuerySchema, table: string, uses: PresetUse): Resolved;
+/**
+ * Applies the chained presets to a read.
+ *
+ * The caller's `where` stays first. The call keeps its tenant and active-set
+ * rules, and gains one `preset` rule per call for `inspect()`.
+ *
+ * @param schema - Connected schema
+ * @param call - The read as the caller wrote it
+ * @param uses - Presets chained on the handle
+ * @returns The same read with the presets' filters stacked after its `where`
+ */
+export declare function refine(schema: QuerySchema, call: ReadCall, uses: PresetUse): ReadCall;

package/dist/runtime/read-stream.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Server-side read cursor.
+ *
+ * Loaded the first time `.stream()` is iterated. A find that is only awaited
+ * does not load it.
+ */
+import type { DriverPool } from "../contracts/driver.js";
+import { OkmError, type ErrorStatuses } from "../contracts/error.js";
+import { type Plan, type ReadCall } from "./plan.js";
+/**
+ * Yields decoded rows from the driver's stream.
+ *
+ * @param session - Connected pool and HTTP statuses
+ * @param call - The read being streamed
+ * @param prepare - Compiles the statement on first use
+ * @param log - Attaches the session logger and returns the error
+ * @returns One row at a time
+ */
+export declare function streamRows(session: {
+    readonly connected: Promise<void>;
+    readonly pool: DriverPool;
+    readonly http: ErrorStatuses | undefined;
+}, call: ReadCall, prepare: () => Promise<{
+    readonly plan: Plan;
+    readonly params: readonly (string | null)[];
+}>, log: (error: OkmError) => OkmError): AsyncIterable<unknown>;

package/dist/runtime/safety/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Final safety verification (`okmodel/safety`).
+ *
+ * A registry and a property harness. Later steps register the rules they own.
+ * This module does not hard-code those rules, and the application startup
+ * graph does not import it.
+ */
+import { OkmError } from "../../contracts/error.js";
+import { type SafetyContribution, type SafetyHatch } from "../safety-hook.js";
+export type { SafetyContribution, SafetyHatch };
+/** What one registered rule sees. */
+export type SafetyInput = {
+    /** Contributions the pipeline recorded, including the caller. */
+    readonly contributions: readonly SafetyContribution[];
+    /**
+     * Contributions recorded before a later step ran.
+     *
+     * One that is missing from {@link SafetyInput.contributions} is `dropped`.
+     */
+    readonly recorded?: readonly SafetyContribution[];
+    /** Escape hatches with a reason. A blank reason is itself a violation. */
+    readonly hatches?: readonly SafetyHatch[];
+};
+/** One broken rule. */
+export type SafetyViolation = {
+    readonly rule: string;
+    readonly contribution: string;
+    /** `file.ts:line` of the rule, when it was recorded. */
+    readonly source?: string;
+    readonly detail: string;
+};
+/**
+ * A rule a later step registers.
+ *
+ * `check` returns violations. It does not throw. The registry sorts them.
+ */
+export type SafetyRule = {
+    readonly name: string;
+    /** Who added the rule. */
+    readonly contribution: string;
+    /**
+     * `file.ts:line`.
+     *
+     * {@link registerRule} records the caller when this is omitted.
+     */
+    readonly source?: string;
+    /**
+     * @param input - Contributions and hatches for one query
+     * @returns Violations. Empty when the rule holds
+     */
+    check(input: SafetyInput): readonly SafetyViolation[];
+};
+/**
+ * OKM1190. `violations` is every broken rule, in stable order.
+ *
+ * `rule` and `contribution` repeat the first of that list.
+ */
+export declare class SafetyError extends OkmError {
+    /** Rule name of the first violation. */
+    readonly rule: string;
+    /** Contribution of the first violation. */
+    readonly contribution: string;
+    /** Every violation, sorted. */
+    readonly violations: readonly SafetyViolation[];
+    /**
+     * @param violations - Broken rules, already in stable order
+     */
+    constructor(violations: readonly SafetyViolation[]);
+}
+/**
+ * Registers one rule and installs the read-path hook.
+ *
+ * The returned function removes that rule. The hook is cleared when no rules
+ * remain, so a query does not call into this module.
+ *
+ * @param rule - The check. A missing `source` is the caller's file and line
+ * @returns Removes this registration
+ */
+/**
+ * Registers the field-exposure rule.
+ *
+ * A contribution that shows a hidden field, reveals a sensitive value, or
+ * sets a guarded field without `{ allow }` is OKM1190. The package does not
+ * register it on import (`sideEffects` is false). Call this once.
+ *
+ * The contribution text is the whole subject the rule can see. P21's input
+ * has no schema and no query, so the planner phrases the verdict
+ * (`excluded`, `redacted`, `absent`, `allowed`) and a leak is the words
+ * `shown`, `revealed`, or `set`.
+ *
+ * @returns Removes this registration
+ */
+export declare function registerFieldExposure(): () => void;
+/**
+ * Registers the timestamps rule.
+ *
+ * A contribution that sets `createdAt` or `updatedAt` from input is OKM1190.
+ * `{ allow }` does not permit it. The planner records `set by timestamps`
+ * or `kept`. The package does not register the rule on import.
+ *
+ * @returns Removes this registration
+ */
+/**
+ * Registers the column-tenancy rule.
+ *
+ * A contribution that sets the tenant key from input is OKM1190. `{ allow }`
+ * does not permit it. The planner throws the same code even when this rule
+ * is not registered. The package does not register the rule on import.
+ *
+ * @returns Removes this registration
+ */
+export declare function registerTenancy(): () => void;
+export declare function registerTimestamps(): () => void;
+/**
+ * Registers the archive rule.
+ *
+ * A contribution that drops the active set, or skips a named cascade, is
+ * OKM1190. The planner records `active set`, `with archived`, `only archived`,
+ * and `cascade <table>`. The package does not register the rule on import.
+ *
+ * @returns Removes this registration
+ */
+export declare function registerArchive(): () => void;
+/**
+ * Registers the presets rule.
+ *
+ * A preset only adds predicates. A contribution that says a preset `removed`
+ * or `replaced` one (the caller's, the tenant's, or the active set) is
+ * OKM1190. The builder has no such method, so the planner never records the
+ * words; the rule keeps the contract checkable if a later builder grows one.
+ * The package does not register the rule on import.
+ *
+ * @returns Removes this registration
+ */
+export declare function registerPresets(): () => void;
+export declare function registerRule(rule: SafetyRule): () => void;
+/**
+ * Runs the registered rules.
+ *
+ * @param input - Contributions, an optional earlier recording, and hatches
+ * @returns Violations in stable order. Empty when every rule holds
+ */
+export declare function review(input: SafetyInput): readonly SafetyViolation[];
+/**
+ * Throws OKM1190 when {@link review} finds a violation.
+ *
+ * @param input - Contributions, an optional earlier recording, and hatches
+ */
+export declare function verify(input: SafetyInput): void;
+/**
+ * Checks each case, then again with the registered rules reversed.
+ *
+ * The two verdicts must match. A later step copies this, registers its rule,
+ * and passes its cases. Rule order is not part of the verdict.
+ *
+ * @param cases - Subjects to check
+ * @returns Violations for each case, in case order
+ */
+export declare function safetyProperty(cases: readonly SafetyInput[]): readonly (readonly SafetyViolation[])[];