opencode-harness-kit 0.5.4 → 0.5.6

package/src/rules.js

@@ -93,12 +93,18 @@ function heredocEnd(command, at) {
 }
 
 /**
- * Split a shell command into the individual commands it runs. Separators
- * inside quotes, and heredoc bodies, are not command boundaries.
+ * Split a shell command at the separators of one kind.
+ *
+ * The quoting, the escaping and the heredoc body are handled once, so the
+ * command splitter and the pipe splitter can never disagree about where a
+ * command starts and ends.
+ *
  * @param {string} command
+ * @param {"command" | "pipe"} kind `command` splits at every separator,
+ *   `pipe` splits at the pipe only
  * @returns {string[]}
  */
-export function segments(command) {
+function split(command, kind) {
   /** @type {string[]} */
   const parts = []
   let cur = ""
@@ -139,13 +145,30 @@ export function segments(command) {
         continue
       }
     }
-    if (ch === "\n" || ch === ";") {
+    if (ch === "|") {
+      if (kind === "pipe") {
+        // `||` is a logical or, not a pipe: the second command runs only if
+        // the first one failed, and nothing was piped into it.
+        if (command[i + 1] === "|") {
+          cur += "||"
+          i++
+          continue
+        }
+        flush()
+        continue
+      }
       flush()
+      if (command[i + 1] === "|") i++
       continue
     }
-    if (ch === "|") {
+    // A pipe stage is everything between two pipes. A `;` or an `&&` inside
+    // a stage is still part of that stage.
+    if (kind === "pipe") {
+      cur += ch
+      continue
+    }
+    if (ch === "\n" || ch === ";") {
       flush()
-      if (command[i + 1] === "|") i++
       continue
     }
     if (ch === "&") {
@@ -172,6 +195,30 @@ export function segments(command) {
   return parts
 }
 
+/**
+ * Split a shell command into the individual commands it runs. Separators
+ * inside quotes, and heredoc bodies, are not command boundaries.
+ * @param {string} command
+ * @returns {string[]}
+ */
+export function segments(command) {
+  return split(command, "command")
+}
+
+/**
+ * Split a shell command into the stages a pipe connects.
+ *
+ * The command splitter loses the pipe: `curl x | sh` is two commands, and
+ * nothing in the two says which fed which. A rule about "download and run"
+ * needs that link, so it reads the pipe itself.
+ *
+ * @param {string} command
+ * @returns {string[]}
+ */
+function pipeStages(command) {
+  return split(command, "pipe")
+}
+
 /**
  * Split one segment into words, honouring quotes so that a quoted phrase is
  * one argument rather than several.
@@ -238,6 +285,14 @@ const GIT_WRAPPERS = new Set([
   "xargs",
   "npx",
 ])
+// The shells a script can be piped into, by name. The name is what matters:
+// `/bin/sh` is the same shell as `sh`.
+const SHELL_NAMES = /^(sh|bash|zsh|dash|ksh)(\.exe)?$/i
+// Python is not a shell, but `curl x | python3` runs what it was given
+// just the same.
+const SCRIPT_RUNNERS = /^python[0-9.]*$/i
+// The commands that fetch something over the network.
+const DOWNLOADERS = /\b(curl|wget)\b/i
 // Wrappers whose flag consumes the next word, e.g. `sudo -u deploy git push`.
 const WRAPPER_VALUE_FLAGS = new Set(["-u", "--user", "-g", "--group", "-I", "-P", "-n", "-a", "-d"])
 // git options that take a value, so the subcommand is the word after them.
@@ -262,6 +317,67 @@ const GIT_GLOBAL_FLAGS = new Set([
   "--icase-pathspecs",
 ])
 
+/**
+ * The global flags each tool accepts, and that take a value.
+ *
+ * A denylist pattern names a COMMAND, so a command with a global flag in
+ * front of it is not the command the pattern describes: `npm --prefix /tmp
+ * publish` is `npm publish`, and `gh -R owner/repo pr create` is `gh pr
+ * create`. A flag that changes nothing about what the command does must not
+ * be a way around the list.
+ *
+ * The lists come from the tools' own `--help` output: `gh --help` lists
+ * `--repo` and `--hostname` among the global options, `npm help 7 config`
+ * lists `--prefix`, `--workspace`, `--registry` and `--cache` among the
+ * global config flags, `yarn --help` lists `--cwd`, and `pnpm --help` lists
+ * `--dir` and `--filter`.
+ *
+ * git is not in the table: its own options are resolved by `gitSubcommand`,
+ * which reads the subcommand rather than the whole command line.
+ *
+ * @type {Record<string, Set<string>>}
+ */
+const TOOL_VALUE_FLAGS = {
+  gh: new Set(["-R", "--repo", "-H", "--hostname"]),
+  npm: new Set([
+    "--prefix",
+    "--cache",
+    "--registry",
+    "--userconfig",
+    "--globalconfig",
+    "--otp",
+    "--tag",
+    "--access",
+    "--loglevel",
+    "--workspace",
+    "--script-shell",
+    "--init-author-name",
+    "--init-author-email",
+    "--init-author-url",
+    "--init-license",
+    "--init-module",
+    "--init-version",
+  ]),
+  yarn: new Set(["--cwd", "--registry", "--cache-folder", "--modules-folder"]),
+  pnpm: new Set(["--dir", "-C", "--filter", "--store-dir", "--registry"]),
+  bun: new Set(["--cwd", "--config", "--registry"]),
+}
+
+/**
+ * The last path segment of a command word: `/usr/bin/env` is `env`.
+ *
+ * A tool named by its full path is the same tool, so every list of command
+ * names - the wrappers, the shells - has to be matched against the name and
+ * not against the path.
+ *
+ * @param {string} word
+ * @returns {string}
+ */
+function baseName(word) {
+  const slash = Math.max(word.lastIndexOf("/"), word.lastIndexOf("\\"))
+  return slash === -1 ? word : word.slice(slash + 1)
+}
+
 /**
  * Skip the wrappers and environment assignments in front of a real command.
  * `env FOO=1 sudo -u deploy git -C /repo push` resolves at index 4.
@@ -277,7 +393,11 @@ function skipPrefixes(tokens) {
       i++
       continue
     }
-    if (GIT_WRAPPERS.has(word)) {
+    // The wrapper is matched by NAME, so `/usr/bin/env` is `env`. Matching
+    // the raw token left the whole wrapper list one absolute path away from
+    // being decorative: `/usr/bin/env rm -rf /` was not a command the rules
+    // had ever seen.
+    if (GIT_WRAPPERS.has(baseName(word))) {
       i++
       while (i < tokens.length && tokens[i].startsWith("-") && tokens[i] !== "-") {
         const flag = tokens[i]
@@ -303,11 +423,39 @@ export function stripPrefixes(segment) {
   const i = skipPrefixes(tokens)
   if (i >= tokens.length) return ""
   const rest = tokens.slice(i)
-  const slash = Math.max(rest[0].lastIndexOf("/"), rest[0].lastIndexOf("\\"))
-  if (slash !== -1) rest[0] = rest[0].slice(slash + 1)
+  rest[0] = baseName(rest[0])
   return rest.join(" ")
 }
 
+/**
+ * A command with the tool's own global flags taken out.
+ *
+ * The flags are taken out wherever they appear, because that is where the
+ * tool itself accepts them: `gh pr --repo owner/repo create` is the same
+ * command as `gh pr create`, and gh's own flag parser reads it that way.
+ *
+ * @param {string} command
+ * @returns {string} the command as the tool will read it
+ */
+function stripToolFlags(command) {
+  const tokens = tokenize(command)
+  if (!tokens.length) return command
+  const flags = TOOL_VALUE_FLAGS[baseName(tokens[0]).toLowerCase()]
+  if (!flags) return command
+  /** @type {string[]} */
+  const out = []
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]
+    if (!flags.has(token.split("=")[0])) {
+      out.push(token)
+      continue
+    }
+    // `--flag value` takes the next word; `--flag=value` carries its own.
+    if (!token.includes("=") && i + 1 < tokens.length) i++
+  }
+  return out.join(" ")
+}
+
 /**
  * Resolve the git subcommand a segment actually runs, or null if the segment
  * does not run git.
@@ -338,9 +486,48 @@ export function gitSubcommand(segment) {
   return tokens[i] ?? null
 }
 
-const SHELL_BIN = /(^|[\\/])(sh|bash|zsh|dash|ksh)(\.exe)?$/i
 const MAX_SHELL_DEPTH = 2
 
+/**
+ * The command string a shell's `-c` flag carries.
+ *
+ * The shell reads the operand of `-c` from the NEXT argv element, whatever
+ * else is in the flag cluster: `bash -cv "rm -rf /"` runs `rm -rf /`, and
+ * the `v` is a flag, not a payload. Reading the rest of the word instead
+ * made the guard look at the letter `v` and at nothing else, so the
+ * command line it checked was a letter.
+ *
+ * A payload written INTO the word (`bash -c"rm -rf /"`) is a different
+ * spelling. bash and dash do not read it as the command line at all: they
+ * read the whole word as a cluster of option characters and refuse it
+ * (`bash: invalid option`). The guard reads the remainder as the command
+ * string anyway, because that is how the payload is spelled, and because
+ * refusing more than the shell would run is the safe direction - the guard
+ * is not the place to decide that a word is harmless.
+ *
+ * @param {string[]} tokens
+ * @param {number} from the index of the shell word
+ * @returns {string | null} the command line, or null when there is none
+ */
+function shellCommandString(tokens, from) {
+  for (let n = from + 1; n < tokens.length; n++) {
+    const token = tokens[n]
+    if (!token.startsWith("-") || token === "-") continue
+    // The flag cluster is the run of letters after the dash, and `c` is the
+    // flag that takes the command line.
+    const m = /^-([a-zA-Z]*)c/.exec(token)
+    if (!m) continue
+    // What follows the `c` in the same word is either the rest of the
+    // cluster (`-cv`, where the `v` is a flag) or the command line written
+    // into the word (`-c"rm -rf /"`, where the remainder has something in it
+    // that cannot be a flag). A run of letters is a cluster.
+    const after = token.slice(m[0].length)
+    if (after && !/^[a-zA-Z]+$/.test(after)) return after.trim()
+    return tokens.slice(n + 1).join(" ") || null
+  }
+  return null
+}
+
 /**
  * The command line hidden inside `sh -c "..."` or `eval "..."`.
  * @param {string} segment
@@ -356,10 +543,225 @@ export function shellPayload(segment) {
   const i = skipPrefixes(tokens)
   if (i >= tokens.length) return null
   if (tokens[i] === "eval") return tokens.slice(i + 1).join(" ") || null
-  if (!SHELL_BIN.test(tokens[i])) return null
-  const c = tokens.findIndex((t, n) => n > i && /^-[a-zA-Z]*c$/.test(t))
-  if (c === -1 || c === tokens.length - 1) return null
-  return tokens.slice(c + 1).join(" ") || null
+  if (!SHELL_NAMES.test(baseName(tokens[i]))) return null
+  return shellCommandString(tokens, i)
+}
+
+/**
+ * The punctuation that opens a group of commands and the punctuation that
+ * ends a word in a command list.
+ *
+ * `sh;` is the shell `sh` is - the `;` ends the word, it does not make the
+ * word something else. Reading the word whole made every pipe with a `;`
+ * after the shell look like a pipe into something that is not a shell.
+ *
+ * The opening braces are here for the same reason: the contents of a group
+ * read the pipe the same way a command outside it does, so `{ sh; }` is a
+ * pipe into a shell even though the first word of the group is `{`.
+ */
+const GROUP_OPEN = /^[({[]+/
+const GROUP_END = /[;)&,}\]]+$/
+
+/**
+ * The name of the command a word names, with the path and the punctuation
+ * that frames it taken off.
+ * @param {string} word
+ * @returns {string}
+ */
+function commandName(word) {
+  return baseName(word).replace(GROUP_OPEN, "").replace(GROUP_END, "")
+}
+
+/**
+ * Whether a command hands what it was given to a shell or an interpreter.
+ *
+ * A pipe stage is not always one command. `sh; echo done` is a command
+ * list, and `cd /tmp && sh` is a list whose shell is not first at all, so
+ * the stage is split into its commands and each one is looked at. The
+ * wrappers in front of a command are skipped, so `sudo /bin/bash` is the
+ * shell `bash` is, and the path is dropped, so `/bin/sh` is `sh`.
+ *
+ * @param {string} stage one stage of a pipe
+ * @returns {boolean}
+ */
+function runsScript(stage) {
+  for (const command of segments(stage)) {
+    const tokens = tokenize(command)
+    let i = skipPrefixes(tokens)
+    if (i >= tokens.length) continue
+    let name = commandName(tokens[i])
+    // A word that is nothing but an opener is a group, and the group's
+    // contents are the command: `{ sh; }` reads the pipe through the `sh`.
+    if (!name) {
+      i++
+      if (i >= tokens.length) continue
+      name = commandName(tokens[i])
+    }
+    if (SHELL_NAMES.test(name) || SCRIPT_RUNNERS.test(name)) return true
+  }
+  return false
+}
+
+/**
+ * Whether a command downloads something and pipes it into a shell.
+ *
+ * Both halves are read the way the shell reads them. The pipe target is
+ * named by its base name, so `/bin/sh` is the shell `sh` is, and the
+ * wrappers in front of it are skipped, so `sudo /bin/bash` is the shell
+ * `bash` is. A rule that only knew the bare spelling of the shell was one
+ * absolute path away from being decorative.
+ *
+ * The target stage is read as the list of commands it is: `curl x | sh;` is
+ * still a pipe into a shell, because the `;` ends the word and not the
+ * pipe.
+ *
+ * The shell does not have to be the stage right after the download. A filter
+ * in between (`curl x | grep y | sh`) does not change what the shell RUNS -
+ * it changes only what the agent sees on the way there - so the chain is
+ * the same download-and-execute. The rule used to look at the stage after
+ * the download only, so a filter in the middle hid the shell from it.
+ *
+ * The order still matters: the shell has to come AFTER the download.
+ * `sh | grep y` runs a shell over a pipe it did not fetch, and there is
+ * nothing downloaded for it to execute.
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+function pipesScriptIntoShell(command) {
+  const stages = pipeStages(command)
+  for (let i = 0; i < stages.length; i++) {
+    if (!DOWNLOADERS.test(stages[i])) continue
+    for (let j = i + 1; j < stages.length; j++) {
+      if (!runsScript(stages[j])) continue
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Whether a token is a flag that makes an rm destructive.
+ *
+ * The short form is a CLUSTER of letters, so `-rf`, `-fr` and `-R` all name
+ * a recursive delete and `-f` names a forced one. The long form is GNU's
+ * own name for the same two flags.
+ *
+ * @param {string} token
+ * @returns {boolean}
+ */
+function isDestructiveRmFlag(token) {
+  if (/^--(recursive|force)$/i.test(token)) return true
+  return /^-[a-zA-Z]*[rf]/i.test(token)
+}
+
+/**
+ * Whether a command is an rm with a flag that makes it destructive.
+ *
+ * The flags and the paths are read SEPARATELY, because GNU rm PERMUTES its
+ * options: the flags can come after the path, and `rm /tmp/x -rf` is the
+ * same delete as `rm -rf /tmp/x`. The rule used to return at the FIRST flag
+ * token and then look for a path AFTER it, so a flag that came after the
+ * path was invisible and the delete the rule exists to stop went through.
+ *
+ * So the question is not "is the first flag recursive" but "is ANY of the
+ * flags recursive or force, AND is there a path" - a delete of one named
+ * file (`rm file.txt`, `rm -i notes.md`) is not a recursive delete, and a
+ * command with no path at all (`rm`, `rm -rf`) is not a delete.
+ *
+ * `--` ends the options, so every word after it is a path whatever it looks
+ * like. That makes `rm -- -rf` a delete of a file NAMED `-rf`, and not a
+ * recursive delete.
+ *
+ * @param {string} text the segment, with its prefixes stripped
+ * @returns {boolean}
+ */
+function isRecursiveDelete(text) {
+  const tokens = tokenize(text)
+  if (tokens.length < 2) return false
+  if (baseName(tokens[0]).toLowerCase() !== "rm") return false
+  let destructive = false
+  let hasPath = false
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i]
+    if (token === "--") {
+      // Everything after `--` is a path, so the words that follow it are
+      // the path this rm destroys.
+      hasPath = tokens.length > i + 1
+      break
+    }
+    if (!token.startsWith("-")) {
+      hasPath = true
+      continue
+    }
+    if (isDestructiveRmFlag(token)) destructive = true
+  }
+  return destructive && hasPath
+}
+
+/**
+ * The chmod options that carry their value in the NEXT word.
+ *
+ * `chmod --reference FILE` takes the mode from another file, so the word
+ * after it is not the mode. A scanner that read that word as the mode would
+ * see `chmod --reference 777 file` as "chmod 777", and that command is a
+ * file named 777 rather than a mode.
+ */
+const CHMOD_VALUE_OPTIONS = new Set(["--reference"])
+
+/**
+ * The mode a chmod command sets, or null when it sets none.
+ *
+ * The mode is the first numeric OPERAND, and every option in front of it is
+ * skipped - INCLUDING the long forms. The rule used to accept only a short
+ * letter cluster in the flag position, so GNU's own `--recursive` put the
+ * mode out of the rule's reach: `chmod --recursive 777 /` was allowed while
+ * `chmod -R 777 /` was blocked, and the mode is the same mode.
+ *
+ * A symbolic mode (`a=rwx`) is not a numeric one, so it is not a mode this
+ * function returns. That is a policy gap and not a spelling one, and it is
+ * left alone on purpose.
+ *
+ * @param {string} text the segment, with its prefixes stripped
+ * @returns {string | null} the mode, as it was written
+ */
+function chmodMode(text) {
+  const tokens = tokenize(text)
+  if (tokens.length < 2) return null
+  if (baseName(tokens[0]).toLowerCase() !== "chmod") return null
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i]
+    if (token === "--") continue
+    if (token.startsWith("--")) {
+      // `--flag=value` carries its own value, and a boolean long option
+      // carries none. Only the option that takes the next word swallows
+      // it, and that word is then not the mode.
+      if (!token.includes("=") && CHMOD_VALUE_OPTIONS.has(token)) i++
+      continue
+    }
+    if (token.startsWith("-")) continue
+    // The first numeric operand is the mode; the words after it are the
+    // files the mode is applied to.
+    if (/^\d+$/.test(token)) return token
+    return null
+  }
+  return null
+}
+
+/**
+ * Whether a chmod command sets the mode that opens permissions to everyone.
+ *
+ * The mode may be written with leading zeros: `0777` and `777` are the same
+ * mode, and a rule that required the bare digits let one spelling of it
+ * through.
+ *
+ * @param {string} text the segment, with its prefixes stripped
+ * @returns {boolean}
+ */
+function opensPermissions(text) {
+  const mode = chmodMode(text)
+  if (mode === null) return false
+  return /^0*777$/.test(mode)
 }
 
 /**
@@ -380,7 +782,19 @@ export const BASH_RULES = [
   {
     name: "secret exfiltration via shell",
     scope: "command",
-    test: /\b(TOKEN|SECRET|KEY|PASSWORD|API_KEY)\s*=\s*\$\(\s*(curl|wget)\b/i,
+    // The credential word has to be the whole name or the tail of it: the
+    // name of the variable is `GITHUB_TOKEN`, not `GITHUB`. A word boundary
+    // never fires after an underscore, so the boundary alone left every
+    // prefixed credential name unmatched.
+    //
+    // The name is matched in whatever case it is written: the rule used to
+    // match the upper case spelling only, so `token=$(curl ...)` was
+    // allowed, and a lower case name is the same name.
+    //
+    // What the rule does NOT cover is an assignment whose value is not
+    // fetched: `GITHUB_TOKEN=ghp_example` sets a credential, it does not
+    // send one.
+    test: /(^|[^A-Za-z0-9])(?:[A-Za-z0-9]+_)*(TOKEN|SECRET|KEY|PASSWORD|API_KEY)\s*=\s*\$\(\s*(curl|wget)\b/i,
     why: "assigns a fetched value into a credential-named variable",
   },
   {
@@ -392,7 +806,7 @@ export const BASH_RULES = [
   {
     name: "pipe remote script into a shell",
     scope: "command",
-    test: /\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh|python[0-9.]*)\b/i,
+    check: (text) => pipesScriptIntoShell(text),
     why: "downloads and executes a script in one step",
   },
   // `git push` is ask-gated via permissions (`*` ask in the generated
@@ -401,13 +815,17 @@ export const BASH_RULES = [
   {
     name: "recursive delete",
     scope: "segment",
-    test: /^rm\s+(-[a-zA-Z]*[rf][a-zA-Z]*)\s+/i,
+    check: (text) => isRecursiveDelete(text),
     why: "rm with a recursive or force flag",
   },
   {
     name: "chmod 777",
     scope: "segment",
-    test: /^chmod\s+(-[a-zA-Z]+\s+)*777\b/,
+    // The mode is read as an OPERAND rather than as a literal, because the
+    // flags in front of it can be long. `chmod --recursive 777 /` is the
+    // same chmod as `chmod -R 777 /`, and a rule that only knew the short
+    // flag cluster let the long spelling through.
+    check: (text) => opensPermissions(text),
     why: "opens permissions on everything",
   },
   {
@@ -485,7 +903,10 @@ export function checkDenied(command, depth = 0) {
   const parts = segments(command)
   const normalized = parts.map((seg) => stripPrefixes(seg))
   for (let i = 0; i < parts.length; i++) {
-    const pattern = deniedBy(normalized[i])
+    // The tool's own global flags come off before the list is read: the
+    // list names a command, and `npm --prefix /tmp publish` is the command
+    // `npm publish`.
+    const pattern = deniedBy(stripToolFlags(normalized[i]))
     if (pattern) return { pattern, segment: parts[i] }
   }
   if (depth < MAX_SHELL_DEPTH) {

package/src/sqlite.js

@@ -92,6 +92,71 @@ function encodePath(db) {
   return db.split("/").map(encodeURIComponent).join("/")
 }
 
+/**
+ * Whether a SQL string holds one statement.
+ *
+ * A semicolon inside a string literal or a comment does not end a
+ * statement, so the text is scanned rather than split on ";".
+ *
+ * Exported so a test can pin the rule without a database: the refusal is
+ * a promise about what the reader accepts, and a promise that can only be
+ * checked against a live database is a promise nobody checks.
+ *
+ * @param {string} sql
+ * @returns {boolean}
+ */
+export function isOneStatement(sql) {
+  let quote = ""
+  // Whether a statement has been terminated. Everything after the `;` that
+  // is not whitespace or a comment is a SECOND statement, and a comment
+  // after the `;` is not a statement at all.
+  let ended = false
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i]
+    if (quote) {
+      if (ch === quote) {
+        // A doubled quote inside a literal is an escaped quote, not the end
+        // of the literal.
+        if (sql[i + 1] === quote) i++
+        else quote = ""
+      }
+      continue
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      quote = ch
+      continue
+    }
+    // A line comment runs to the end of the line.
+    if (ch === "-" && sql[i + 1] === "-") {
+      const end = sql.indexOf("\n", i)
+      // The comment runs to the end of the text, so nothing follows it.
+      if (end < 0) break
+      i = end
+      continue
+    }
+    // A block comment runs to its own end.
+    if (ch === "/" && sql[i + 1] === "*") {
+      const end = sql.indexOf("*/", i + 2)
+      if (end < 0) break
+      i = end + 1
+      continue
+    }
+    if (ch === ";") {
+      // A second `;` is a second statement - an empty one, which is still a
+      // statement the caller did not ask for.
+      if (ended) return false
+      ended = true
+      continue
+    }
+    // The scan does not stop at the `;`. A comment after the last
+    // statement is a comment, and the old check - "is there anything after
+    // the semicolon?" - read it as a second statement and refused
+    // `"select 1; -- done"`.
+    if (ended && !/\s/.test(ch)) return false
+  }
+  return true
+}
+
 /**
  * Run a query and return the rows.
  *
@@ -105,6 +170,21 @@ function encodePath(db) {
  * @returns {any[]}
  */
 export function query(db, sql) {
+  // ONE statement, on both backends.
+  //
+  // The sqlite3 CLI runs the whole string, so a call with two statements ran
+  // them both; python3's execute() takes one statement and raised. The same
+  // call therefore behaved differently depending on which backend the
+  // machine happened to have - and on one side the failure was a database
+  // error about a statement the caller never wrote on its own.
+  //
+  // REFUSING is the behaviour chosen. The function returns ROWS, and the
+  // rows of two statements have no agreed meaning: the caller asked for one
+  // answer and would be handed two. A caller that wants two answers asks
+  // twice, and it says which one it wants each time.
+  if (!isOneStatement(sql)) {
+    throw new Error("query() runs one statement at a time - split the query into separate calls")
+  }
   if (hasSqlite()) {
     // The path is percent-encoded, because it goes into a URI. A `?` in a
     // path is a query separator, so a database called "we?ird.db" was read