@githolon/dsl 0.1.0

package/src/certified_read.ts

@@ -0,0 +1,313 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * **CertifiedRead — the DECLARED write-path read surface (survival Constraint 5;
+ * `certified_read.md`).** A tenant directive's `decide()` may READ the current world to
+ * decide whether a write is valid ("is this thing assigned? what's the balance? enough
+ * stock?"). That read RESULT is a DECISION INPUT, so it must be a deterministic, captured,
+ * byte-identical-across-peers fact ([[determinism-or-death]]). This module is the AUTHORING
+ * surface a tenant uses to DECLARE such reads — the `reads:{ name: q.someProfiledRead(args) }`
+ * shape from `certified_read.md` §"Tenant authoring".
+ *
+ * ## The two halves (mirroring `readmodel/src/certified_read.rs`)
+ *   1. {@link sqlProfileV0Check} — the TS port of the Rust `SqlProfileV0` enforcer. The villain
+ *      is UNDER-SPECIFICATION, not SQLite: a declared write-path read MUST obey the restricted
+ *      profile so EVERY valid execution plan produces the SAME canonical result (explicit
+ *      `ORDER BY` ending in a UNIQUE tie-breaker on multi-row, NO clock/rng functions, BINARY
+ *      collation only, NO floats, explicit columns, no implicit rowid, a single pure SELECT). An
+ *      under-specified declared read is REFUSED at COMPILE (`certifiedRead(...).sql(...)` throws),
+ *      the SAME refusal the Rust `CertifiedReadDef::compile` raises — so a tenant cannot author a
+ *      non-deterministic write-path read.
+ *   2. {@link certifiedRead} — the declaration builder. `certifiedRead("stockAvailable")
+ *      .sql("SELECT value_json FROM rows WHERE …", { multiRow:false })` yields a
+ *      {@link CertifiedReadDecl} the directive's `.readsCertified({ available: decl })` attaches.
+ *      The declared `query_id`s land in the canonical manifest (`manifest.ts`), so the
+ *      ONE write-path gate (`executor::admit` step 5.6) can DERIVE the expected declared-read set
+ *      and REFUSE any admit where a declared read produced no witness (the vacuous-pass close).
+ *
+ * THE BOUNDARY: a tenant declares the SQL recipe + the shape (single/multi-row + tie-breakers).
+ * Nomos owns the determinism (the profile, the canonical encoding, the witness, the admission
+ * re-run). The DSL author NEVER mints a witness or touches SQLite at decide time — the HOST
+ * resolves each declared read against the pinned projection snapshot and records the witness
+ * (the capture wire; the Rust `CertifiedReadPort::resolve_and_witness`).
+ */
+
+/** The SQL-profile-v0 version pin — frozen alongside the Rust `SQL_PROFILE_VERSION`. */
+export const SQL_PROFILE_VERSION = "v0";
+
+/** The NON-DETERMINISTIC SQL functions BANNED on the write/decide path — the clock family +
+ * the entropy family. Lower-cased (SQLite function names are case-insensitive). Byte-identical
+ * to the Rust `BANNED_FUNCTIONS` so the TS compile refusal and the Rust runtime guard agree. */
+export const BANNED_FUNCTIONS = [
+  "random",
+  "randomblob",
+  "datetime",
+  "date",
+  "time",
+  "julianday",
+  "unixepoch",
+  "strftime",
+  "current_timestamp",
+  "current_time",
+  "current_date",
+  "localtime",
+  "localtimestamp",
+] as const;
+
+/** Why a declared write-path read was REFUSED by the SQL-profile-v0 enforcer — the same typed
+ * cause set as the Rust `ProfileViolation`. Carried in the thrown {@link ProfileError}. */
+export type ProfileViolation =
+  | { kind: "SelectStar" }
+  | { kind: "MissingOrderBy" }
+  | { kind: "NoUniqueTieBreaker" }
+  | { kind: "BannedFunction"; name: string }
+  | { kind: "NonBinaryCollation"; collation: string }
+  | { kind: "FloatInDecision"; literal: string }
+  | { kind: "ImplicitRowid" }
+  | { kind: "NotASingleSelect" };
+
+/** A compile-time refusal of an under-specified declared read (the villain is
+ * UNDER-SPECIFICATION). Thrown by {@link certifiedRead}'s `.sql(...)`. */
+export class ProfileError extends Error {
+  constructor(public readonly violation: ProfileViolation) {
+    super(`SQL-profile-v0 violation: ${describe(violation)}`);
+    this.name = "ProfileError";
+  }
+}
+
+function describe(v: ProfileViolation): string {
+  switch (v.kind) {
+    case "SelectStar":
+      return "SELECT * is banned on the write path — list explicit columns";
+    case "MissingOrderBy":
+      return "a multi-row query MUST have an explicit ORDER BY (row order is UNDEFINED without one)";
+    case "NoUniqueTieBreaker":
+      return "ORDER BY MUST end in a UNIQUE deterministic tie-breaker (e.g. `…, aggregate_id`)";
+    case "BannedFunction":
+      return `non-deterministic function \`${v.name}\` is banned (the clock/rng family)`;
+    case "NonBinaryCollation":
+      return `COLLATE \`${v.collation}\` is banned — only BINARY/canonical collation is byte-stable`;
+    case "FloatInDecision":
+      return `float literal \`${v.literal}\` in a decision is banned — use integers / decimals-as-strings`;
+    case "ImplicitRowid":
+      return "implicit rowid is banned unless modeled";
+    case "NotASingleSelect":
+      return "the write-path read must be a SINGLE pure SELECT (no chained statements / write verb)";
+  }
+}
+
+// ── the profile parser (lower-cased input only; a faithful TS port of the Rust enforcer) ──
+
+function collapseWs(s: string): string {
+  return ` ${s.replace(/\s+/g, " ").trim()} `;
+}
+
+function containsWord(hay: string, word: string): boolean {
+  if (word.length === 0) return false;
+  const re = new RegExp(`(?<![A-Za-z0-9_])${escapeRe(word)}(?![A-Za-z0-9_])`);
+  return re.test(hay);
+}
+
+function containsFunctionCall(hay: string, name: string): boolean {
+  // `name` followed (with optional spaces) by `(`, and NOT preceded by a word char.
+  const re = new RegExp(`(?<![A-Za-z0-9_])${escapeRe(name)}\\s*\\(`);
+  return re.test(hay);
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function selectListOf(trimmed: string): string {
+  const afterSelect = trimmed.startsWith("select ") ? trimmed.slice("select ".length) : trimmed;
+  const idx = afterSelect.indexOf(" from ");
+  return idx >= 0 ? afterSelect.slice(0, idx) : afterSelect;
+}
+
+function orderByClause(normalized: string): string | undefined {
+  const idx = normalized.lastIndexOf(" order by ");
+  if (idx < 0) return undefined;
+  const after = normalized.slice(idx + " order by ".length);
+  const lim = after.indexOf(" limit ");
+  return (lim >= 0 ? after.slice(0, lim) : after).trim();
+}
+
+function collateOtherThanBinary(normalized: string): string | undefined {
+  const re = /collate\s+([a-z0-9_]+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(normalized)) !== null) {
+    const name = m[1]!;
+    if (name !== "binary") return name;
+  }
+  return undefined;
+}
+
+function floatLiteral(normalized: string): string | undefined {
+  // A numeric literal that is NOT a pure integer: a decimal point and/or scientific exponent,
+  // at a token boundary, outside single-quoted strings. Mirrors the Rust `float_literal`.
+  let inStr = false;
+  const isIdent = (c: string) => /[A-Za-z0-9_]/.test(c);
+  const n = normalized.length;
+  let i = 0;
+  while (i < n) {
+    const ch = normalized[i]!;
+    if (ch === "'") {
+      inStr = !inStr;
+      i += 1;
+      continue;
+    }
+    if (inStr) {
+      i += 1;
+      continue;
+    }
+    const prev = i > 0 ? normalized[i - 1]! : "";
+    const startsDigit = /[0-9]/.test(ch);
+    const startsDot = ch === "." && i + 1 < n && /[0-9]/.test(normalized[i + 1]!);
+    const boundary = i === 0 || (!isIdent(prev) && prev !== ".");
+    if (boundary && (startsDigit || startsDot)) {
+      const start = i;
+      let isFloat = startsDot;
+      while (i < n && /[0-9.]/.test(normalized[i]!)) {
+        if (normalized[i] === ".") isFloat = true;
+        i += 1;
+      }
+      if (i < n && (normalized[i] === "e" || normalized[i] === "E")) {
+        let j = i + 1;
+        if (j < n && (normalized[j] === "+" || normalized[j] === "-")) j += 1;
+        if (j < n && /[0-9]/.test(normalized[j]!)) {
+          isFloat = true;
+          i = j;
+          while (i < n && /[0-9]/.test(normalized[i]!)) i += 1;
+        }
+      }
+      if (isFloat) return normalized.slice(start, i);
+      continue;
+    }
+    i += 1;
+  }
+  return undefined;
+}
+
+/**
+ * Check `sql` against SQL-profile-v0 — the TS port of `SqlProfileV0::check`. `multiRow` is
+ * whether the query can return more than one row (a scalar COUNT/MAX is single-row, exempt from
+ * the ORDER BY rule). `uniqueTieBreakers` are the declared unique deterministic key columns the
+ * multi-row `ORDER BY` must end in. Returns the FIRST {@link ProfileViolation}, or `undefined`
+ * when the query obeys EVERY rule.
+ */
+export function sqlProfileV0Check(
+  sql: string,
+  multiRow: boolean,
+  uniqueTieBreakers: string[],
+): ProfileViolation | undefined {
+  const lower = sql.toLowerCase();
+  const normalized = collapseWs(lower);
+
+  // single pure SELECT (no chained statements / write verbs)
+  const trimmed = normalized.replace(/;+$/, "").trim();
+  if (trimmed.includes(";")) return { kind: "NotASingleSelect" };
+  if (!trimmed.startsWith("select ") && trimmed !== "select") return { kind: "NotASingleSelect" };
+  for (const verb of [
+    " insert ", " update ", " delete ", " drop ", " create ", " alter ", " attach ",
+    " pragma ", " replace ", " reindex ", " vacuum ",
+  ]) {
+    if (normalized.includes(verb)) return { kind: "NotASingleSelect" };
+  }
+
+  // explicit columns (no SELECT *), allowing the one `count(*)`
+  const selectList = selectListOf(trimmed).replaceAll("count(*)", "count_star");
+  if (selectList.includes("*")) return { kind: "SelectStar" };
+
+  // banned non-deterministic functions (clock/rng family), anywhere
+  for (const name of BANNED_FUNCTIONS) {
+    if (containsFunctionCall(normalized, name)) return { kind: "BannedFunction", name };
+    if (name.startsWith("current_") && containsWord(normalized, name)) {
+      return { kind: "BannedFunction", name };
+    }
+  }
+
+  // BINARY/canonical collation only
+  const coll = collateOtherThanBinary(normalized);
+  if (coll !== undefined) return { kind: "NonBinaryCollation", collation: coll };
+
+  // no implicit rowid (unless modeled as a column)
+  for (const kw of ["rowid", "_rowid_", "oid"]) {
+    if (containsWord(normalized, kw)) return { kind: "ImplicitRowid" };
+  }
+
+  // no floats in decision-critical results
+  const lit = floatLiteral(normalized);
+  if (lit !== undefined) return { kind: "FloatInDecision", literal: lit };
+
+  // ORDER BY with a unique tie-breaker (multi-row only)
+  if (multiRow) {
+    const orderBy = orderByClause(normalized);
+    if (orderBy === undefined) return { kind: "MissingOrderBy" };
+    let lastTerm = orderBy.split(",").pop()!.trim();
+    const collIdx = lastTerm.indexOf(" collate ");
+    if (collIdx >= 0) lastTerm = lastTerm.slice(0, collIdx).trim();
+    lastTerm = lastTerm.replace(/ asc$/, "").replace(/ desc$/, "").trim();
+    const bare = lastTerm.includes(".") ? lastTerm.split(".").pop()! : lastTerm;
+    const ok = uniqueTieBreakers.some((t) => t === lastTerm || t === bare);
+    if (!ok) return { kind: "NoUniqueTieBreaker" };
+  }
+
+  return undefined;
+}
+
+/**
+ * A FINISHED, profile-conforming CertifiedRead declaration — the write-path read API surface
+ * (the DSL analogue of the Rust `CertifiedReadDef`). Construction (`certifiedRead(id).sql(...)`)
+ * is the COMPILE-TIME refusal: a profile-violating SQL throws {@link ProfileError}, so a
+ * `CertifiedReadDecl` value is a profile-conformance WITNESS by construction. The `queryId` is
+ * which question; the `sql` is the validated recipe; `multiRow` + `uniqueTieBreakers` are the
+ * shape the profile + the admission re-run pin.
+ */
+export interface CertifiedReadDecl {
+  readonly queryId: string;
+  readonly sql: string;
+  readonly multiRow: boolean;
+  readonly uniqueTieBreakers: string[];
+}
+
+/** Options for {@link CertifiedReadBuilder.sql}. */
+export interface CertifiedReadOpts {
+  /** Whether the query can return more than one row (drives the ORDER BY requirement).
+   * Defaults to `false` (a single-row scalar read, e.g. a COUNT/MAX — exempt from ORDER BY). */
+  readonly multiRow?: boolean;
+  /** The declared unique deterministic tie-breaker column(s) the multi-row ORDER BY must end in
+   * (e.g. `["aggregate_id"]`). Required for a `multiRow` query; ignored for single-row. */
+  readonly uniqueTieBreakers?: string[];
+}
+
+/** Stage 2: attach the profiled SQL recipe, producing the finished {@link CertifiedReadDecl}. */
+class CertifiedReadBuilder<Id extends string> {
+  constructor(private readonly id: Id) {}
+  /**
+   * Declare the read's SQL recipe. COMPILE-TIME refusal: the SQL is validated against
+   * SQL-profile-v0 here ({@link sqlProfileV0Check}) and THROWS {@link ProfileError} on any
+   * under-specification — the SAME refusal the Rust `CertifiedReadDef::compile` raises. So a
+   * non-conforming declared read can never become a {@link CertifiedReadDecl}.
+   */
+  sql(text: string, opts: CertifiedReadOpts = {}): CertifiedReadDecl {
+    const multiRow = opts.multiRow ?? false;
+    const uniqueTieBreakers = [...(opts.uniqueTieBreakers ?? [])];
+    const violation = sqlProfileV0Check(text, multiRow, uniqueTieBreakers);
+    if (violation !== undefined) throw new ProfileError(violation);
+    return { queryId: this.id, sql: text, multiRow, uniqueTieBreakers };
+  }
+}
+
+/**
+ * Begin a CertifiedRead declaration: `certifiedRead("stockAvailable").sql("SELECT … FROM …",
+ * { multiRow:false })`. The id is the `query_id` frozen into the witness + the manifest's
+ * declared-read set; `.sql(...)` validates the recipe and produces the finished decl.
+ */
+export function certifiedRead<const Id extends string>(id: Id): CertifiedReadBuilder<Id> {
+  return new CertifiedReadBuilder(id);
+}