okmodel 0.1.0 → 0.2.1

package/dist/runtime/safety/index.js

@@ -0,0 +1,294 @@
+import {
+  callerLocation
+} from "../../shared/k7dwkhvq.js";
+import {
+  installSafetyHook
+} from "../../shared/a5sxz52y.js";
+import {
+  OkmError2
+} from "../../shared/52szzakm.js";
+
+// src/runtime/safety/index.ts
+class SafetyError extends OkmError2 {
+  rule;
+  contribution;
+  violations;
+  constructor(violations) {
+    const first = violations[0];
+    const rule = first?.rule ?? "unknown";
+    const contribution = first?.contribution ?? "unknown";
+    const extra = violations.length > 1 ? ` (+${String(violations.length - 1)} more)` : "";
+    const source = first?.source === undefined ? "" : ` (${first.source})`;
+    super("OKM1190", first === undefined ? "A safety check failed." : `${rule} [${contribution}]${source}: ${first.detail}${extra}`);
+    this.rule = rule;
+    this.contribution = contribution;
+    this.violations = violations;
+  }
+}
+var rules = [];
+function registerFieldExposure() {
+  return registerRule({
+    name: "exposure",
+    contribution: "field-exposure",
+    check(input) {
+      const allowed = new Set;
+      if (input.hatches !== undefined) {
+        for (const hatch of input.hatches) {
+          if (hatch.name === "allow" && hatch.reason.trim().length > 0)
+            allowed.add(hatch.reason);
+        }
+      }
+      const violations = [];
+      for (const item of input.contributions) {
+        if (!leaked(item.rule, item.contribution))
+          continue;
+        if (item.rule === "guarded" && permitted(item.contribution, allowed))
+          continue;
+        violations.push({
+          rule: item.rule,
+          contribution: item.contribution,
+          ...item.source !== undefined ? { source: item.source } : {},
+          detail: exposureDetail(item.rule)
+        });
+      }
+      return violations;
+    }
+  });
+}
+function registerTenancy() {
+  return registerRule({
+    name: "tenancy",
+    contribution: "tenancy",
+    check(input) {
+      const violations = [];
+      for (const item of input.contributions) {
+        if (item.rule !== "tenancy" || !item.contribution.includes("set by input"))
+          continue;
+        violations.push({
+          rule: item.rule,
+          contribution: item.contribution,
+          ...item.source !== undefined ? { source: item.source } : {},
+          detail: "The tenant key comes from the scope. Input cannot set it."
+        });
+      }
+      return violations;
+    }
+  });
+}
+function registerTimestamps() {
+  return registerRule({
+    name: "timestamps",
+    contribution: "timestamps",
+    check(input) {
+      const violations = [];
+      for (const item of input.contributions) {
+        if (item.rule !== "timestamps" || !item.contribution.includes("set by input"))
+          continue;
+        violations.push({
+          rule: item.rule,
+          contribution: item.contribution,
+          ...item.source !== undefined ? { source: item.source } : {},
+          detail: "A timestamp is set by the trait. Input cannot set it."
+        });
+      }
+      return violations;
+    }
+  });
+}
+function registerArchive() {
+  return registerRule({
+    name: "archive",
+    contribution: "archive",
+    check(input) {
+      const violations = [];
+      for (const item of input.contributions) {
+        if (item.rule !== "archive")
+          continue;
+        if (item.contribution.includes("active set dropped")) {
+          violations.push({
+            rule: item.rule,
+            contribution: item.contribution,
+            ...item.source !== undefined ? { source: item.source } : {},
+            detail: "Reads, updates, and deletes target the active set."
+          });
+        }
+        if (item.contribution.includes("cascade skipped")) {
+          violations.push({
+            rule: item.rule,
+            contribution: item.contribution,
+            ...item.source !== undefined ? { source: item.source } : {},
+            detail: "Cascade archives and restores the named children with the row."
+          });
+        }
+      }
+      return violations;
+    }
+  });
+}
+function registerPresets() {
+  return registerRule({
+    name: "presets",
+    contribution: "preset",
+    check(input) {
+      const violations = [];
+      for (const item of input.contributions) {
+        if (item.rule !== "preset")
+          continue;
+        if (!item.contribution.includes(" removed ") && !item.contribution.includes(" replaced ")) {
+          continue;
+        }
+        violations.push({
+          rule: item.rule,
+          contribution: item.contribution,
+          ...item.source !== undefined ? { source: item.source } : {},
+          detail: "A preset adds predicates. It cannot remove or replace one."
+        });
+      }
+      return violations;
+    }
+  });
+}
+function leaked(rule, contribution) {
+  if (rule === "hidden")
+    return contribution.includes(" shown");
+  if (rule === "sensitive")
+    return contribution.includes(" revealed");
+  if (rule === "guarded")
+    return contribution.includes(" set");
+  return false;
+}
+function permitted(contribution, allowed) {
+  for (const reason of allowed) {
+    if (contribution.includes(`${reason} set`))
+      return true;
+  }
+  return false;
+}
+function exposureDetail(rule) {
+  if (rule === "hidden")
+    return "A hidden field was returned.";
+  if (rule === "sensitive")
+    return "A sensitive value was shown.";
+  return "A guarded field was set from input.";
+}
+function registerRule(rule) {
+  const source = rule.source ?? callerLocation(1);
+  const stored = source === undefined || rule.source !== undefined ? rule : { ...rule, source };
+  rules.push(stored);
+  installSafetyHook(runHook);
+  return () => {
+    const index = rules.indexOf(stored);
+    if (index >= 0)
+      rules.splice(index, 1);
+    if (rules.length === 0)
+      installSafetyHook(undefined);
+  };
+}
+function review(input) {
+  const violations = [];
+  const hatches = [];
+  if (input.hatches !== undefined) {
+    for (const hatch of input.hatches) {
+      if (hatch.reason.trim().length === 0) {
+        violations.push({
+          rule: "hatch",
+          contribution: hatch.name,
+          detail: "An escape hatch needs a reason."
+        });
+        continue;
+      }
+      hatches.push(hatch);
+    }
+  }
+  if (input.recorded !== undefined) {
+    for (const item of input.recorded) {
+      if (present(item, input.contributions))
+        continue;
+      violations.push({
+        rule: "dropped",
+        contribution: item.contribution,
+        ...item.source !== undefined ? { source: item.source } : {},
+        detail: `${item.rule} was removed.`
+      });
+    }
+  }
+  const seen = input.hatches === undefined || hatches.length === input.hatches.length ? input : {
+    contributions: input.contributions,
+    ...input.recorded !== undefined ? { recorded: input.recorded } : {},
+    hatches
+  };
+  for (const rule of rules) {
+    for (const found of rule.check(seen)) {
+      violations.push(found.source === undefined && rule.source !== undefined ? { ...found, source: rule.source } : found);
+    }
+  }
+  violations.sort((left, right) => violationKey(left).localeCompare(violationKey(right)));
+  return violations;
+}
+function verify(input) {
+  const violations = review(input);
+  if (violations.length > 0)
+    throw new SafetyError(violations);
+}
+function safetyProperty(cases) {
+  const forward = cases.map((item) => review(item));
+  const snapshot = rules.slice();
+  rules.reverse();
+  try {
+    for (let index = 0;index < cases.length; index += 1) {
+      const item = cases[index];
+      if (item === undefined)
+        continue;
+      if (!sameViolations(forward[index] ?? [], review(item))) {
+        throw new Error("safety.property: rule order changed the verdict.");
+      }
+    }
+  } finally {
+    rules.length = 0;
+    for (const rule of snapshot)
+      rules.push(rule);
+  }
+  return forward;
+}
+function runHook(contributions, hatches) {
+  verify({
+    contributions,
+    ...hatches !== undefined ? { hatches } : {}
+  });
+}
+function present(needle, contributions) {
+  for (const item of contributions) {
+    if (item.rule === needle.rule && item.contribution === needle.contribution && item.provenance === needle.provenance) {
+      return true;
+    }
+  }
+  return false;
+}
+function violationKey(violation) {
+  return `${violation.rule}\x00${violation.contribution}\x00${violation.detail}`;
+}
+function sameViolations(left, right) {
+  if (left.length !== right.length)
+    return false;
+  for (let index = 0;index < left.length; index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (a === undefined || b === undefined)
+      return false;
+    if (violationKey(a) !== violationKey(b))
+      return false;
+  }
+  return true;
+}
+export {
+  SafetyError,
+  registerArchive,
+  registerFieldExposure,
+  registerPresets,
+  registerRule,
+  registerTenancy,
+  registerTimestamps,
+  review,
+  safetyProperty,
+  verify
+};

package/dist/runtime/safety-hook.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Slot the read path calls before planning.
+ *
+ * Empty until `okmodel/safety` registers a rule. The application startup
+ * graph pays for this call and not for the registry.
+ */
+/** One recorded contribution. */
+export type SafetyContribution = {
+    readonly rule: string;
+    readonly contribution: string;
+    readonly provenance: string;
+    readonly source?: string;
+};
+/** A named escape hatch with a reason. */
+export type SafetyHatch = {
+    readonly name: "unscoped" | "all" | "trusted" | "allow";
+    readonly reason: string;
+};
+/** Installed by the safety registry. Absent until a rule is registered. */
+export type SafetyHook = (contributions: readonly SafetyContribution[], hatches: readonly SafetyHatch[] | undefined) => void;
+/**
+ * Reports whether a safety rule is registered.
+ *
+ * @returns `true` after the first {@link installSafetyHook} until the last rule is removed
+ */
+export declare function safetyInstalled(): boolean;
+/**
+ * Installs or clears the verifier the read path calls.
+ *
+ * @param next - Verifier, or `undefined` to remove it
+ */
+export declare function installSafetyHook(next: SafetyHook | undefined): void;
+/**
+ * Runs the installed verifier.
+ *
+ * A no-op when nothing is registered, and it does not allocate in that case
+ * because the caller returns first.
+ *
+ * @param contributions - Rules already recorded for this query
+ * @param hatches - Escape hatches the caller passed
+ */
+export declare function runSafety(contributions: readonly SafetyContribution[], hatches: readonly SafetyHatch[] | undefined): void;

package/dist/runtime/server-check.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Dialect, catalog-hash, and Postgres major checks.
+ *
+ * Loaded on the first connection. The strings stay out of the startup graph.
+ */
+import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
+import { type ErrorStatuses } from "../contracts/error.js";
+import type { QuerySchema } from "../dialects/pg/model.js";
+import type { CatalogArtifact } from "./types.js";
+/**
+ * Version, dialect, and the `okm_meta` hash in one round trip.
+ *
+ * The hash subquery is a string so a database with no `okm_meta` still plans.
+ * A null hash skips the compatibility check.
+ */
+export declare const versionQuery = "select current_setting('server_version_num'), version(), (select (xpath('//catalog_hash/text()', query_to_xml('select catalog_hash from okm_meta where id = ''head''', true, false, '')))[1]::text where to_regclass('okm_meta') is not null)";
+/**
+ * Accepts the `server_version_num` row, or throws OKM1801, OKM1520, OKM1802, or OKM1803.
+ *
+ * A declared `requires` is the minimum, including a major below 15 when the
+ * schema names it on purpose. With no `requires`, the floor is 15.
+ *
+ * @param pool - Connection that ran the version query
+ * @param schema - Schema whose `requires` is the declared minimum
+ * @param rows - `server_version_num`, `version()`, and the `okm_meta` hash
+ * @param http - Status overrides from `connect`
+ * @param requireMeta - When true, a missing hash is OKM1520
+ * @param options - Signal and timeout for the compatibility read
+ * @param source - Trusted catalog used when the hash does not match
+ */
+export declare function acceptServer(pool: DriverPool, schema: QuerySchema, rows: readonly (readonly (string | null)[])[], http: ErrorStatuses | undefined, requireMeta: boolean, options: ExecuteOptions | undefined, source: {
+    readonly catalog?: CatalogArtifact;
+    readonly catalogDir?: string;
+}): Promise<void>;

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

@@ -0,0 +1,37 @@
+/**
+ * Column tenancy (`okmodel/tenancy`).
+ *
+ * Importing this module is what puts tenancy on a schema. `schema()` calls
+ * `rewrite` once and then compiles ordinary columns, uniques, and foreign keys.
+ * The predicate and the client methods stay on this object.
+ */
+import type { ColumnTenancy } from "../../dialects/pg/tenancy.js";
+export type { ColumnTenancy };
+/**
+ * Opts a table out of column tenancy.
+ *
+ * The reason is stored on the table and shown by `inspect()`.
+ *
+ * @param reason - Why this table is shared across tenants
+ * @returns The marker `table({ tenancy })` stores
+ */
+export declare function global(reason: string): {
+    readonly kind: "global";
+    readonly reason: string;
+};
+/**
+ * Column tenancy for `schema({ tenancy })`.
+ *
+ * Every table gains `key` unless it passes `global("reason")`. The key is a
+ * guarded uuid. Insert fills it from `for()`. Reads and writes filter on it.
+ *
+ * @typeParam Key - Field name of the tenant key
+ * @param input - Field name and `uuid`
+ * @returns The object `schema()` applies
+ */
+export declare function columnTenancy<const Key extends string>(input: {
+    readonly key: Key;
+    readonly type: "uuid";
+}): ColumnTenancy & {
+    readonly key: Key;
+};