@cavelang/query 0.35.0 → 0.36.1

package/src/pattern.ts

@@ -17,6 +17,7 @@
 
 import { Confidence, Value, Verb } from '@cavelang/core'
 import { Token } from '@cavelang/parser'
+import { assertQueryUnicode } from './unicode.ts'
 
 /** A pattern slot: named variable, wildcard `_`, or a bound term. */
 export type Slot =
@@ -63,13 +64,19 @@ const filterOps: readonly FilterOp[] = ['>=', '<=', '!=', '=', '>', '<']
 const isFilterOp = (text: string): text is FilterOp =>
   filterOps.includes(text as FilterOp)
 
+const variableName = (text: string): string => {
+  const name = text.slice(1)
+  if (name === '') throw new Error('CAVE-Q: variable requires a name after ?; use _ for a wildcard')
+  return name
+}
+
 const slotOf = (token: Token.t): Slot => {
   if (token.kind === 'word') {
     if (token.text === '_') {
       return { kind: 'wildcard' }
     }
     if (token.text.startsWith('?')) {
-      return { kind: 'var', name: token.text.slice(1) }
+      return { kind: 'var', name: variableName(token.text) }
     }
     return { kind: 'term', text: token.text }
   }
@@ -85,7 +92,7 @@ const verbSlotOf = (token: Token.t): undefined | VerbSlot => {
     return { kind: 'wildcard' }
   }
   if (token.text.startsWith('?')) {
-    return { kind: 'var', name: token.text.slice(1) }
+    return { kind: 'var', name: variableName(token.text) }
   }
   const transitive = token.text.endsWith('+')
   const name = transitive ? token.text.slice(0, -1) : token.text
@@ -107,7 +114,7 @@ const parseFilter = (tokens: readonly Token.t[], lineNo: number): Filter => {
   switch (field.text) {
     case 'conf': {
       const conf = valueText.endsWith('%') ? Confidence.parse(valueText) : Number(valueText)
-      if (conf === undefined || Number.isNaN(conf)) {
+      if (conf === undefined || !Number.isFinite(conf)) {
         return bad(`cannot parse confidence ${JSON.stringify(valueText)}`)
       }
       return { field: 'conf', op: op.text, value: conf }
@@ -148,13 +155,16 @@ const parseFilter = (tokens: readonly Token.t[], lineNo: number): Filter => {
 export const parse = (input: string): Pattern => {
   const lines = input
     .split(/\r?\n/)
-    .map(line => line.trim())
-    .filter(line => line !== '' && !line.startsWith(';'))
+    .map((line, index) => {
+      assertQueryUnicode(line, index + 1)
+      return { text: line.trim(), lineNo: index + 1 }
+    })
+    .filter(line => line.text !== '' && !line.text.startsWith(';'))
   if (lines.length === 0) {
     throw new Error('CAVE-Q: empty query')
   }
   const [patternLine, ...filterLines] = lines
-  const { head } = Token.splitComment(patternLine!)
+  const { head } = Token.splitComment(patternLine!.text)
   const tokens = Token.tokenize(head)
   if (tokens.length < 2) {
     throw new Error('CAVE-Q: a pattern needs at least a subject and a verb (spec §12.1)')
@@ -214,13 +224,13 @@ export const parse = (input: string): Pattern => {
   } else {
     throw new Error(`CAVE-Q: cannot parse payload ${JSON.stringify(payloadTokens.map(token => token.text).join(' '))}`)
   }
-  const filters = filterLines.map((line, at) => {
-    const filterTokens = Token.tokenize(Token.splitComment(line).head)
+  const filters = filterLines.map(line => {
+    const filterTokens = Token.tokenize(Token.splitComment(line.text).head)
     const [keyword, ...rest_] = filterTokens
     if (keyword?.kind !== 'word' || keyword.text !== 'WHERE') {
-      throw new Error(`CAVE-Q line ${at + 2}: expected WHERE, got ${JSON.stringify(keyword?.text ?? '')}`)
+      throw new Error(`CAVE-Q line ${line.lineNo}: expected WHERE, got ${JSON.stringify(keyword?.text ?? '')}`)
     }
-    return parseFilter(rest_, at + 2)
+    return parseFilter(rest_, line.lineNo)
   })
   return { subject, verb, payload, negated, contexts, tags, filters }
 }

package/src/read-snapshot.ts

@@ -0,0 +1,23 @@
+import type { Store } from '@cavelang/store/adapter'
+
+const message = (error: unknown): string => {
+  try { return error instanceof Error ? String(error.message) : String(error) }
+  catch { return '[unprintable thrown value]' }
+}
+
+/** A deferred savepoint also nests within a caller-owned transaction. */
+export const readSnapshot = <T>(store: Store, read: () => T): T => {
+  const savepoint = 'cave_query_read'
+  store.db.exec(`SAVEPOINT ${savepoint}`)
+  let result: T
+  try { result = read() } catch (error) {
+    try { store.db.exec(`RELEASE ${savepoint}`) } catch (releaseError) {
+      throw new AggregateError([error, releaseError],
+        `CAVE-Q matching failed: ${message(error)}; read snapshot release also failed: ${message(releaseError)}`,
+        { cause: error })
+    }
+    throw error
+  }
+  store.db.exec(`RELEASE ${savepoint}`)
+  return result
+}

package/src/record.ts

@@ -4,6 +4,8 @@ import { Record as ClaimRecord } from '@cavelang/store/adapter'
 import type { Store } from '@cavelang/store/adapter'
 import type { Match, Options } from './compile.ts'
 import { query } from './bounded.ts'
+import { readSnapshot } from './read-snapshot.ts'
+import { captureOptions } from './capture.ts'
 
 export const format = 'cave.query-match' as const
 export const version = 1 as const
@@ -17,38 +19,69 @@ export type t = {
   readonly at?: Match['at']
 }
 
-export const of = (store: Store, match: Match): t => ({
-  format,
-  version,
-  bindings: match.bindings,
-  ...(match.row === undefined ? {} : { claim: store.recordOf(match.row) }),
-  ...(match.rows === undefined ? {} : { support: match.rows.map(store.recordOf) }),
-  ...(match.at === undefined ? {} : { at: match.at }),
-})
+export const of = (store: Store, match: Match): t => {
+  const supplied = { bindings: match.bindings, row: match.row, rows: match.rows, at: match.at }
+  requireBindingPrototype(supplied.bindings)
+  const { bindings, row, rows, at } = structuredClone(supplied)
+  validateMetadata(bindings, rows, at)
+  if (rows !== undefined) for (const evidence of rows) {
+    if (!object(evidence)) throw new Error(`CAVE query record: malformed ${format}/v${version} support`)
+  }
+  return {
+    format,
+    version,
+    bindings,
+    ...(row === undefined ? {} : { claim: store.recordOf(row) }),
+    ...(rows === undefined ? {} : { support: rows.map(store.recordOf) }),
+    ...(at === undefined ? {} : { at }),
+  }
+}
 
 const object = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
 
+const requireBindingPrototype = (bindings: unknown): void => {
+  if (object(bindings) && Object.getPrototypeOf(bindings) !== Object.prototype &&
+      Object.getPrototypeOf(bindings) !== null) {
+    throw new Error(`CAVE query record: malformed ${format}/v${version}`)
+  }
+}
+
+const validateMetadata = (bindings: unknown, support: unknown, at: unknown): void => {
+  if (!object(bindings) ||
+      (Object.getPrototypeOf(bindings) !== Object.prototype && Object.getPrototypeOf(bindings) !== null) ||
+      !Object.values(bindings).every(binding => typeof binding === 'string') ||
+      (support !== undefined && !Array.isArray(support))) {
+    throw new Error(`CAVE query record: malformed ${format}/v${version}`)
+  }
+  if (at !== undefined && (!object(at) || typeof at['num'] !== 'number' || !Number.isFinite(at['num']) ||
+      typeof at['text'] !== 'string' || (at['unit'] !== undefined && typeof at['unit'] !== 'string'))) {
+    throw new Error(`CAVE query record: malformed ${format}/v${version} interpolation`)
+  }
+}
+
 /** Decode a persisted query-match record and every nested claim record. */
 export const decode = (input: string | unknown): t => {
-  const value: unknown = typeof input === 'string' ? JSON.parse(input) : input
+  let value: unknown = typeof input === 'string' ? JSON.parse(input) : object(input) ? { ...input } : input
+  if (typeof input !== 'string' && object(value)) {
+    // Check the supplied map before cloning normalizes custom prototypes.
+    requireBindingPrototype(value['bindings'])
+    value = structuredClone(value)
+  }
   if (!object(value) || value['format'] !== format) {
     throw new Error(`CAVE query record: expected format ${JSON.stringify(format)}`)
   }
   if (value['version'] !== version) {
     throw new Error(`CAVE query record: unsupported ${format} version ${JSON.stringify(value['version'])}`)
   }
-  if (!object(value['bindings']) ||
-      !Object.values(value['bindings']).every(binding => typeof binding === 'string') ||
-      (value['support'] !== undefined && !Array.isArray(value['support']))) {
-    throw new Error(`CAVE query record: malformed ${format}/v${version}`)
-  }
+  validateMetadata(value['bindings'], value['support'], value['at'])
   const decoded = value as t
   return {
     ...decoded,
     ...(decoded.claim === undefined ? {} : { claim: ClaimRecord.decode(decoded.claim) }),
     ...(decoded.support === undefined ? {} : {
-      support: decoded.support.map(record => ClaimRecord.decode(record))
+      support: Array.from({ length: decoded.support.length },
+        (_, index) => ClaimRecord.decode(decoded.support![index]))
     }),
   }
 }
@@ -61,4 +94,7 @@ export const queryRecords = (
   store: Store,
   input: string,
   options: Options = {}
-): t[] => query(store, input, options).map(match => of(store, match))
+): t[] => {
+  options = captureOptions(options)
+  return readSnapshot(store, () => query(store, input, options).map(match => of(store, match)))
+}

package/src/unicode.ts

@@ -0,0 +1,6 @@
+/** Query strings must survive SQLite's UTF-8 encoding without replacement. */
+export const assertQueryUnicode = (value: unknown, line?: number): void => {
+  if (typeof value === 'string' && /[\uD800-\uDFFF]/u.test(value)) {
+    throw new Error(`CAVE-Q${line === undefined ? '' : ` line ${line}`}: unpaired UTF-16 surrogate cannot be queried as UTF-8`)
+  }
+}