@prisma-next/runtime-executor 0.3.0-pr.94.3 → 0.3.0-pr.95.2

package/dist/index.js

@@ -0,0 +1,746 @@
+// src/errors.ts
+function runtimeError(code, message, details) {
+  const error = new Error(message);
+  Object.defineProperty(error, "name", {
+    value: "RuntimeError",
+    configurable: true
+  });
+  return Object.assign(error, {
+    code,
+    category: resolveCategory(code),
+    severity: "error",
+    message,
+    details
+  });
+}
+function resolveCategory(code) {
+  const prefix = code.split(".")[0] ?? "RUNTIME";
+  switch (prefix) {
+    case "PLAN":
+    case "CONTRACT":
+    case "LINT":
+    case "BUDGET":
+      return prefix;
+    default:
+      return "RUNTIME";
+  }
+}
+
+// src/async-iterable-result.ts
+var AsyncIterableResult = class {
+  generator;
+  consumed = false;
+  consumedBy;
+  constructor(generator) {
+    this.generator = generator;
+  }
+  [Symbol.asyncIterator]() {
+    if (this.consumed) {
+      throw runtimeError(
+        "RUNTIME.ITERATOR_CONSUMED",
+        `AsyncIterableResult iterator has already been consumed via ${this.consumedBy === "toArray" ? "toArray()" : "for-await loop"}. Each AsyncIterableResult can only be iterated once.`,
+        {
+          consumedBy: this.consumedBy,
+          suggestion: this.consumedBy === "toArray" ? "If you need to iterate multiple times, store the results from toArray() in a variable and reuse that." : "If you need to iterate multiple times, use toArray() to collect all results first."
+        }
+      );
+    }
+    this.consumed = true;
+    this.consumedBy = "iterator";
+    return this.generator;
+  }
+  /**
+   * Collects all values from the async iterator into an array.
+   * Once called, the iterator is consumed and cannot be reused.
+   */
+  async toArray() {
+    if (this.consumed) {
+      throw runtimeError(
+        "RUNTIME.ITERATOR_CONSUMED",
+        `AsyncIterableResult iterator has already been consumed via ${this.consumedBy === "toArray" ? "toArray()" : "for-await loop"}. Each AsyncIterableResult can only be iterated once.`,
+        {
+          consumedBy: this.consumedBy,
+          suggestion: this.consumedBy === "toArray" ? "You cannot call toArray() twice on the same AsyncIterableResult. Store the result from the first call in a variable and reuse that." : "The iterator was already consumed by a for-await loop. Use toArray() to collect all results before iterating."
+        }
+      );
+    }
+    this.consumed = true;
+    this.consumedBy = "toArray";
+    const out = [];
+    for await (const item of this.generator) {
+      out.push(item);
+    }
+    return out;
+  }
+};
+
+// src/fingerprint.ts
+import { createHash } from "crypto";
+var STRING_LITERAL_REGEX = /'(?:''|[^'])*'/g;
+var NUMERIC_LITERAL_REGEX = /\b\d+(?:\.\d+)?\b/g;
+var WHITESPACE_REGEX = /\s+/g;
+function computeSqlFingerprint(sql) {
+  const withoutStrings = sql.replace(STRING_LITERAL_REGEX, "?");
+  const withoutNumbers = withoutStrings.replace(NUMERIC_LITERAL_REGEX, "?");
+  const normalized = withoutNumbers.replace(WHITESPACE_REGEX, " ").trim().toLowerCase();
+  const hash = createHash("sha256").update(normalized).digest("hex");
+  return `sha256:${hash}`;
+}
+
+// src/guardrails/raw.ts
+var SELECT_STAR_REGEX = /select\s+\*/i;
+var LIMIT_REGEX = /\blimit\b/i;
+var MUTATION_PREFIX_REGEX = /^(insert|update|delete|create|alter|drop|truncate)\b/i;
+var READ_ONLY_INTENTS = /* @__PURE__ */ new Set(["read", "report", "readonly"]);
+function evaluateRawGuardrails(plan, config) {
+  const lints2 = [];
+  const budgets2 = [];
+  const normalized = normalizeWhitespace(plan.sql);
+  const statementType = classifyStatement(normalized);
+  if (statementType === "select") {
+    if (SELECT_STAR_REGEX.test(normalized)) {
+      lints2.push(
+        createLint("LINT.SELECT_STAR", "error", "Raw SQL plan selects all columns via *", {
+          sql: snippet(plan.sql)
+        })
+      );
+    }
+    if (!LIMIT_REGEX.test(normalized)) {
+      const severity = config?.budgets?.unboundedSelectSeverity ?? "error";
+      lints2.push(
+        createLint("LINT.NO_LIMIT", "warn", "Raw SQL plan omits LIMIT clause", {
+          sql: snippet(plan.sql)
+        })
+      );
+      budgets2.push(
+        createBudget(
+          "BUDGET.ROWS_EXCEEDED",
+          severity,
+          "Raw SQL plan is unbounded and may exceed row budget",
+          {
+            sql: snippet(plan.sql),
+            ...config?.budgets?.estimatedRows !== void 0 ? { estimatedRows: config.budgets.estimatedRows } : {}
+          }
+        )
+      );
+    }
+  }
+  if (isMutationStatement(statementType) && isReadOnlyIntent(plan.meta)) {
+    lints2.push(
+      createLint(
+        "LINT.READ_ONLY_MUTATION",
+        "error",
+        "Raw SQL plan mutates data despite read-only intent",
+        {
+          sql: snippet(plan.sql),
+          intent: plan.meta.annotations?.["intent"]
+        }
+      )
+    );
+  }
+  const refs = plan.meta.refs;
+  if (refs) {
+    evaluateIndexCoverage(refs, lints2);
+  }
+  return { lints: lints2, budgets: budgets2, statement: statementType };
+}
+function evaluateIndexCoverage(refs, lints2) {
+  const predicateColumns = refs.columns ?? [];
+  if (predicateColumns.length === 0) {
+    return;
+  }
+  const indexes = refs.indexes ?? [];
+  if (indexes.length === 0) {
+    lints2.push(
+      createLint(
+        "LINT.UNINDEXED_PREDICATE",
+        "warn",
+        "Raw SQL plan predicates lack supporting indexes",
+        {
+          predicates: predicateColumns
+        }
+      )
+    );
+    return;
+  }
+  const hasSupportingIndex = predicateColumns.every(
+    (column) => indexes.some(
+      (index) => index.table === column.table && index.columns.some((col) => col.toLowerCase() === column.column.toLowerCase())
+    )
+  );
+  if (!hasSupportingIndex) {
+    lints2.push(
+      createLint(
+        "LINT.UNINDEXED_PREDICATE",
+        "warn",
+        "Raw SQL plan predicates lack supporting indexes",
+        {
+          predicates: predicateColumns
+        }
+      )
+    );
+  }
+}
+function classifyStatement(sql) {
+  const trimmed = sql.trim();
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith("with")) {
+    if (lower.includes("select")) {
+      return "select";
+    }
+  }
+  if (lower.startsWith("select")) {
+    return "select";
+  }
+  if (MUTATION_PREFIX_REGEX.test(trimmed)) {
+    return "mutation";
+  }
+  return "other";
+}
+function isMutationStatement(statement) {
+  return statement === "mutation";
+}
+function isReadOnlyIntent(meta) {
+  const annotations = meta.annotations;
+  const intent = typeof annotations?.intent === "string" ? annotations.intent.toLowerCase() : void 0;
+  return intent !== void 0 && READ_ONLY_INTENTS.has(intent);
+}
+function normalizeWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function snippet(sql) {
+  return normalizeWhitespace(sql).slice(0, 200);
+}
+function createLint(code, severity, message, details) {
+  return { code, severity, message, ...details ? { details } : {} };
+}
+function createBudget(code, severity, message, details) {
+  return { code, severity, message, ...details ? { details } : {} };
+}
+
+// src/marker.ts
+import { type } from "arktype";
+var MetaSchema = type({ "[string]": "unknown" });
+function parseMeta(meta) {
+  if (meta === null || meta === void 0) {
+    return {};
+  }
+  let parsed;
+  if (typeof meta === "string") {
+    try {
+      parsed = JSON.parse(meta);
+    } catch {
+      return {};
+    }
+  } else {
+    parsed = meta;
+  }
+  const result = MetaSchema(parsed);
+  if (result instanceof type.errors) {
+    return {};
+  }
+  return result;
+}
+var ContractMarkerRowSchema = type({
+  core_hash: "string",
+  profile_hash: "string",
+  "contract_json?": "unknown | null",
+  "canonical_version?": "number | null",
+  "updated_at?": "Date | string",
+  "app_tag?": "string | null",
+  "meta?": "unknown | null"
+});
+function parseContractMarkerRow(row) {
+  const result = ContractMarkerRowSchema(row);
+  if (result instanceof type.errors) {
+    const messages = result.map((p) => p.message).join("; ");
+    throw new Error(`Invalid contract marker row: ${messages}`);
+  }
+  const validatedRow = result;
+  const updatedAt = validatedRow.updated_at ? validatedRow.updated_at instanceof Date ? validatedRow.updated_at : new Date(validatedRow.updated_at) : /* @__PURE__ */ new Date();
+  return {
+    coreHash: validatedRow.core_hash,
+    profileHash: validatedRow.profile_hash,
+    contractJson: validatedRow.contract_json ?? null,
+    canonicalVersion: validatedRow.canonical_version ?? null,
+    updatedAt,
+    appTag: validatedRow.app_tag ?? null,
+    meta: parseMeta(validatedRow.meta)
+  };
+}
+
+// src/plugins/budgets.ts
+async function computeEstimatedRows(plan, driver) {
+  if (typeof driver.explain !== "function") {
+    return void 0;
+  }
+  try {
+    const result = await driver.explain(plan.sql, [...plan.params]);
+    return extractEstimatedRows(result.rows);
+  } catch {
+    return void 0;
+  }
+}
+function extractEstimatedRows(rows) {
+  for (const row of rows) {
+    const estimate = findPlanRows(row);
+    if (estimate !== void 0) {
+      return estimate;
+    }
+  }
+  return void 0;
+}
+function findPlanRows(node) {
+  if (!node || typeof node !== "object") {
+    return void 0;
+  }
+  const explainNode = node;
+  const planRows = explainNode["Plan Rows"];
+  if (typeof planRows === "number") {
+    return planRows;
+  }
+  if ("Plan" in explainNode && explainNode.Plan !== void 0) {
+    const nested = findPlanRows(explainNode.Plan);
+    if (nested !== void 0) {
+      return nested;
+    }
+  }
+  if (Array.isArray(explainNode.Plans)) {
+    for (const child of explainNode.Plans) {
+      const nested = findPlanRows(child);
+      if (nested !== void 0) {
+        return nested;
+      }
+    }
+  }
+  for (const value of Object.values(node)) {
+    if (typeof value === "object" && value !== null) {
+      const nested = findPlanRows(value);
+      if (nested !== void 0) {
+        return nested;
+      }
+    }
+  }
+  return void 0;
+}
+function budgetError(code, message, details) {
+  const error = new Error(message);
+  Object.defineProperty(error, "name", {
+    value: "RuntimeError",
+    configurable: true
+  });
+  return Object.assign(error, {
+    code,
+    category: "BUDGET",
+    severity: "error",
+    details
+  });
+}
+function estimateRows(plan, tableRows, defaultTableRows) {
+  if (!plan.ast) {
+    return null;
+  }
+  const table = plan.meta.refs?.tables?.[0];
+  if (!table) {
+    return null;
+  }
+  const tableEstimate = tableRows[table] ?? defaultTableRows;
+  if (plan.ast && typeof plan.ast === "object" && "kind" in plan.ast && plan.ast.kind === "select" && "limit" in plan.ast && typeof plan.ast.limit === "number") {
+    return Math.min(plan.ast.limit, tableEstimate);
+  }
+  return tableEstimate;
+}
+function hasDetectableLimit(plan) {
+  if (plan.ast && typeof plan.ast === "object" && "kind" in plan.ast && plan.ast.kind === "select" && "limit" in plan.ast && typeof plan.ast.limit === "number") {
+    return true;
+  }
+  const annotations = plan.meta.annotations;
+  return typeof annotations?.limit === "number" || typeof annotations?.LIMIT === "number";
+}
+function budgets(options) {
+  const maxRows = options?.maxRows ?? 1e4;
+  const defaultTableRows = options?.defaultTableRows ?? 1e4;
+  const tableRows = options?.tableRows ?? {};
+  const maxLatencyMs = options?.maxLatencyMs ?? 1e3;
+  const rowSeverity = options?.severities?.rowCount ?? "error";
+  const latencySeverity = options?.severities?.latency ?? "warn";
+  let observedRows = 0;
+  return Object.freeze({
+    name: "budgets",
+    async beforeExecute(plan, ctx) {
+      observedRows = 0;
+      void ctx.now();
+      const estimated = estimateRows(plan, tableRows, defaultTableRows);
+      const isUnbounded = !hasDetectableLimit(plan);
+      const sqlUpper = plan.sql.trimStart().toUpperCase();
+      const isSelect = sqlUpper.startsWith("SELECT");
+      if (isSelect && isUnbounded) {
+        if (estimated !== null && estimated >= maxRows) {
+          const error2 = budgetError(
+            "BUDGET.ROWS_EXCEEDED",
+            "Unbounded SELECT query exceeds budget",
+            {
+              source: "heuristic",
+              estimatedRows: estimated,
+              maxRows
+            }
+          );
+          const shouldBlock2 = rowSeverity === "error" || ctx.mode === "strict";
+          if (shouldBlock2) {
+            throw error2;
+          }
+          ctx.log.warn({
+            code: error2.code,
+            message: error2.message,
+            details: error2.details
+          });
+          return;
+        }
+        const error = budgetError("BUDGET.ROWS_EXCEEDED", "Unbounded SELECT query exceeds budget", {
+          source: "heuristic",
+          maxRows
+        });
+        const shouldBlock = rowSeverity === "error" || ctx.mode === "strict";
+        if (shouldBlock) {
+          throw error;
+        }
+        ctx.log.warn({
+          code: error.code,
+          message: error.message,
+          details: error.details
+        });
+        return;
+      }
+      if (estimated !== null) {
+        if (estimated > maxRows) {
+          const error = budgetError("BUDGET.ROWS_EXCEEDED", "Estimated row count exceeds budget", {
+            source: "heuristic",
+            estimatedRows: estimated,
+            maxRows
+          });
+          const shouldBlock = rowSeverity === "error" || ctx.mode === "strict";
+          if (shouldBlock) {
+            throw error;
+          }
+          ctx.log.warn({
+            code: error.code,
+            message: error.message,
+            details: error.details
+          });
+        }
+        return;
+      }
+      if (!plan.ast) {
+        const explainEnabled = options?.explain?.enabled === true;
+        if (explainEnabled && isSelect && typeof ctx.driver === "object" && ctx.driver !== null) {
+          const estimatedRows = await computeEstimatedRows(plan, ctx.driver);
+          if (estimatedRows !== void 0) {
+            if (estimatedRows > maxRows) {
+              const error = budgetError(
+                "BUDGET.ROWS_EXCEEDED",
+                "Estimated row count exceeds budget",
+                {
+                  source: "explain",
+                  estimatedRows,
+                  maxRows
+                }
+              );
+              const shouldBlock = rowSeverity === "error" || ctx.mode === "strict";
+              if (shouldBlock) {
+                throw error;
+              }
+              ctx.log.warn({
+                code: error.code,
+                message: error.message,
+                details: error.details
+              });
+            }
+            return;
+          }
+        }
+      }
+    },
+    async onRow(_row, _plan, _ctx) {
+      void _row;
+      void _plan;
+      void _ctx;
+      observedRows += 1;
+      if (observedRows > maxRows) {
+        throw budgetError("BUDGET.ROWS_EXCEEDED", "Observed row count exceeds budget", {
+          source: "observed",
+          observedRows,
+          maxRows
+        });
+      }
+    },
+    async afterExecute(_plan, result, ctx) {
+      const latencyMs = result.latencyMs;
+      if (latencyMs > maxLatencyMs) {
+        const error = budgetError("BUDGET.TIME_EXCEEDED", "Query latency exceeds budget", {
+          latencyMs,
+          maxLatencyMs
+        });
+        const shouldBlock = latencySeverity === "error" && ctx.mode === "strict";
+        if (shouldBlock) {
+          throw error;
+        }
+        ctx.log.warn({
+          code: error.code,
+          message: error.message,
+          details: error.details
+        });
+      }
+    }
+  });
+}
+
+// src/plugins/lints.ts
+function lintError(code, message, details) {
+  const error = new Error(message);
+  Object.defineProperty(error, "name", {
+    value: "RuntimeError",
+    configurable: true
+  });
+  return Object.assign(error, {
+    code,
+    category: "LINT",
+    severity: "error",
+    details
+  });
+}
+function lints(options) {
+  return Object.freeze({
+    name: "lints",
+    async beforeExecute(plan, ctx) {
+      if (plan.ast) {
+        return;
+      }
+      const evaluation = evaluateRawGuardrails(plan);
+      for (const lint of evaluation.lints) {
+        const configuredSeverity = getConfiguredSeverity(lint.code, options);
+        const effectiveSeverity = configuredSeverity ?? lint.severity;
+        if (effectiveSeverity === "error") {
+          throw lintError(lint.code, lint.message, lint.details);
+        }
+        if (effectiveSeverity === "warn") {
+          ctx.log.warn({
+            code: lint.code,
+            message: lint.message,
+            details: lint.details
+          });
+        }
+      }
+    }
+  });
+}
+function getConfiguredSeverity(code, options) {
+  const severities = options?.severities;
+  if (!severities) {
+    return void 0;
+  }
+  if (code === "LINT.SELECT_STAR") {
+    return severities.selectStar;
+  }
+  if (code === "LINT.NO_LIMIT") {
+    return severities.noLimit;
+  }
+  if (code === "LINT.READ_ONLY_MUTATION") {
+    return severities.readOnlyMutation;
+  }
+  if (code === "LINT.UNINDEXED_PREDICATE") {
+    return severities.unindexedPredicate;
+  }
+  return void 0;
+}
+
+// src/runtime-core.ts
+var RuntimeCoreImpl = class {
+  _typeContract;
+  _typeAdapter;
+  _typeDriver;
+  contract;
+  familyAdapter;
+  driver;
+  plugins;
+  mode;
+  verify;
+  operationRegistry;
+  pluginContext;
+  verified;
+  startupVerified;
+  _telemetry;
+  constructor(options) {
+    const { familyAdapter, driver } = options;
+    this.contract = familyAdapter.contract;
+    this.familyAdapter = familyAdapter;
+    this.driver = driver;
+    this.plugins = options.plugins ?? [];
+    this.mode = options.mode ?? "strict";
+    this.verify = options.verify;
+    this.operationRegistry = options.operationRegistry;
+    this.verified = options.verify.mode === "startup" ? false : options.verify.mode === "always";
+    this.startupVerified = false;
+    this._telemetry = null;
+    this.pluginContext = {
+      contract: this.contract,
+      adapter: options.familyAdapter,
+      driver: this.driver,
+      mode: this.mode,
+      now: () => Date.now(),
+      log: options.log ?? {
+        info: () => {
+        },
+        warn: () => {
+        },
+        error: () => {
+        }
+      }
+    };
+  }
+  async verifyPlanIfNeeded(_plan) {
+    void _plan;
+    if (this.verify.mode === "always") {
+      this.verified = false;
+    }
+    if (this.verified) {
+      return;
+    }
+    const readStatement = this.familyAdapter.markerReader.readMarkerStatement();
+    const driver = this.driver;
+    const result = await driver.query(readStatement.sql, readStatement.params);
+    if (result.rows.length === 0) {
+      if (this.verify.requireMarker) {
+        throw runtimeError("CONTRACT.MARKER_MISSING", "Contract marker not found in database");
+      }
+      this.verified = true;
+      return;
+    }
+    const marker = parseContractMarkerRow(result.rows[0]);
+    const contract = this.contract;
+    if (marker.coreHash !== contract.coreHash) {
+      throw runtimeError("CONTRACT.MARKER_MISMATCH", "Database core hash does not match contract", {
+        expected: contract.coreHash,
+        actual: marker.coreHash
+      });
+    }
+    const expectedProfile = contract.profileHash ?? null;
+    if (expectedProfile !== null && marker.profileHash !== expectedProfile) {
+      throw runtimeError(
+        "CONTRACT.MARKER_MISMATCH",
+        "Database profile hash does not match contract",
+        {
+          expectedProfile,
+          actualProfile: marker.profileHash
+        }
+      );
+    }
+    this.verified = true;
+    this.startupVerified = true;
+  }
+  validatePlan(plan) {
+    this.familyAdapter.validatePlan(plan, this.contract);
+  }
+  recordTelemetry(plan, outcome, durationMs) {
+    const contract = this.contract;
+    this._telemetry = Object.freeze({
+      lane: plan.meta.lane,
+      target: contract.target,
+      fingerprint: computeSqlFingerprint(plan.sql),
+      outcome,
+      ...durationMs !== void 0 ? { durationMs } : {}
+    });
+  }
+  execute(plan) {
+    this.validatePlan(plan);
+    this._telemetry = null;
+    const iterator = async function* (self) {
+      const startedAt = Date.now();
+      let rowCount = 0;
+      let completed = false;
+      if (!self.startupVerified && self.verify.mode === "startup") {
+        await self.verifyPlanIfNeeded(plan);
+      }
+      if (self.verify.mode === "onFirstUse") {
+        await self.verifyPlanIfNeeded(plan);
+      }
+      try {
+        if (self.verify.mode === "always") {
+          await self.verifyPlanIfNeeded(plan);
+        }
+        for (const plugin of self.plugins) {
+          if (plugin.beforeExecute) {
+            await plugin.beforeExecute(plan, self.pluginContext);
+          }
+        }
+        const driver = self.driver;
+        const encodedParams = plan.params;
+        for await (const row of driver.execute({
+          sql: plan.sql,
+          params: encodedParams
+        })) {
+          for (const plugin of self.plugins) {
+            if (plugin.onRow) {
+              await plugin.onRow(row, plan, self.pluginContext);
+            }
+          }
+          rowCount++;
+          yield row;
+        }
+        completed = true;
+        self.recordTelemetry(plan, "success", Date.now() - startedAt);
+      } catch (error) {
+        if (self._telemetry === null) {
+          self.recordTelemetry(plan, "runtime-error", Date.now() - startedAt);
+        }
+        const latencyMs2 = Date.now() - startedAt;
+        for (const plugin of self.plugins) {
+          if (plugin.afterExecute) {
+            try {
+              await plugin.afterExecute(
+                plan,
+                { rowCount, latencyMs: latencyMs2, completed },
+                self.pluginContext
+              );
+            } catch {
+            }
+          }
+        }
+        throw error;
+      }
+      const latencyMs = Date.now() - startedAt;
+      for (const plugin of self.plugins) {
+        if (plugin.afterExecute) {
+          await plugin.afterExecute(plan, { rowCount, latencyMs, completed }, self.pluginContext);
+        }
+      }
+    };
+    return new AsyncIterableResult(iterator(this));
+  }
+  telemetry() {
+    return this._telemetry;
+  }
+  operations() {
+    return this.operationRegistry;
+  }
+  close() {
+    const driver = this.driver;
+    if (typeof driver.close === "function") {
+      return driver.close();
+    }
+    return Promise.resolve();
+  }
+};
+function createRuntimeCore(options) {
+  return new RuntimeCoreImpl(options);
+}
+export {
+  AsyncIterableResult,
+  budgets,
+  computeSqlFingerprint,
+  createRuntimeCore,
+  evaluateRawGuardrails,
+  lints,
+  parseContractMarkerRow,
+  runtimeError
+};
+//# sourceMappingURL=index.js.map