@cavelang/store 0.35.0 → 0.36.0

package/src/provenance.ts

@@ -86,6 +86,33 @@ export const fromEntries = (values: readonly Entry[]): t => ({
   domains: values.filter(entry => entry.dimension === 'domain').map(entry => entry.value)
 })
 
+/** Stable set representation for interchange and identity comparison. */
+export const normalize = (value: t): t => ({
+  actors: [...new Set(value.actors)].sort(),
+  sources: [...new Set(value.sources)].sort(),
+  runs: [...new Set(value.runs)].sort(),
+  domains: [...new Set(value.domains)].sort(),
+})
+
+/** Parse a complete explicit provenance object; reject unknown dimensions and malformed entries. */
+export const parse = (value: unknown): undefined | t => {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const object = value as Record<string, unknown>
+  const keys = ['actors', 'sources', 'runs', 'domains'] as const
+  const fields = Object.keys(object)
+  if (fields.length !== keys.length || keys.some(key => !fields.includes(key))) return undefined
+  const captured: Record<(typeof keys)[number], string[]> = { actors: [], sources: [], runs: [], domains: [] }
+  for (const key of keys) {
+    const dimension = object[key]
+    if (!Array.isArray(dimension)) return undefined
+    const values: unknown[] = Array.from(dimension)
+    if (!values.every((entry): entry is string => typeof entry === 'string' && entry.length > 0 &&
+      !/[\uD800-\uDFFF]/u.test(entry))) return undefined
+    captured[key] = values
+  }
+  return normalize(captured)
+}
+
 /** Idempotently derives dimensions for rows written by older CAVE versions. */
 export const backfill = (db: Database): void => {
   const missing = db.prepare(`
@@ -96,7 +123,12 @@ export const backfill = (db: Database): void => {
   `).all() as { id: string, context: null | string }[]
   const grouped = new Map<string, string[]>()
   for (const row of missing) {
-    grouped.set(row.id, [...grouped.get(row.id) ?? [], ...row.context === null ? [] : [row.context]])
+    let contexts = grouped.get(row.id)
+    if (contexts === undefined) {
+      contexts = []
+      grouped.set(row.id, contexts)
+    }
+    if (row.context !== null) contexts.push(row.context)
   }
   const insert = db.prepare(`
     INSERT OR IGNORE INTO cave_provenance (claim_id, dimension, value) VALUES (?, ?, ?)

package/src/query-sql.ts

@@ -24,9 +24,11 @@ export type AsOfBoundary = {
 export const transactionBounds = (text: string): TransactionBounds | undefined => {
   const boundary = Time.parseBoundary(text)
   if (boundary === undefined) return undefined
+  // UUID transactions cannot precede the Unix epoch. Earlier calendar
+  // intervals are empty; intervals crossing the epoch retain their overlap.
   return {
-    lo: Uuidv7.at(boundary.start, 0, new Uint8Array(8)),
-    hi: Uuidv7.at(boundary.end, 0, new Uint8Array(8)),
+    lo: Uuidv7.at(Math.max(0, boundary.start), 0, new Uint8Array(8)),
+    hi: Uuidv7.at(Math.max(0, boundary.end), 0, new Uint8Array(8)),
   }
 }
 

package/src/read-snapshot.ts

@@ -0,0 +1,21 @@
+import type { Database } from './adapter.ts'
+import { errorMessage } from './error-message.ts'
+
+/** Keep a multi-query read on one deferred snapshot, including inside caller transactions. */
+export const readSnapshot = <T>(db: Database, operation: 'export' | 'resolution' | 'reverse', read: () => T): T => {
+  const savepoint = `cave_${operation}_read`
+  db.exec(`SAVEPOINT ${savepoint}`)
+  let result: T
+  try {
+    result = read()
+  } catch (error) {
+    try { db.exec(`RELEASE ${savepoint}`) } catch (releaseError) {
+      throw new AggregateError([error, releaseError],
+        `CAVE ${operation} failed: ${errorMessage(error)}; read snapshot release also failed: ${errorMessage(releaseError)}`,
+        { cause: error })
+    }
+    throw error
+  }
+  db.exec(`RELEASE ${savepoint}`)
+  return result
+}

package/src/record.ts

@@ -1,9 +1,10 @@
 /** Versioned, storage-independent claim and transaction records. */
 
-import { Key, Uuidv7 } from '@cavelang/core'
+import { Key, Uuidv7, Value } from '@cavelang/core'
 import type { Claim } from '@cavelang/core'
 import { emitClaim } from '@cavelang/canonical'
 import type * as Provenance from './provenance.ts'
+import { parse as parseProvenance } from './provenance.ts'
 import type * as Row from './row.ts'
 
 export const format = 'cave.claim' as const
@@ -29,49 +30,124 @@ export type V1 = {
 
 export type t = V1
 
-export const of = (row: Row.t, claim: Claim.t, provenance: Provenance.t): t => ({
-  format,
-  version,
-  id: row.id,
-  tx: row.tx,
-  key: row.claim_key,
-  canonical: emitClaim(claim),
-  claim,
-  provenance,
-})
+const requireTransactionIdentity = (id: unknown, tx: unknown): void => {
+  if (typeof id !== 'string' || !Uuidv7.is(id) || tx !== id) {
+    throw new Error(`CAVE record: malformed ${format}/v${version} transaction identity`)
+  }
+}
+
+export const of = (row: Row.t, claim: Claim.t, provenance: Provenance.t): t => {
+  const id = row.id, tx = row.tx
+  requireTransactionIdentity(id, tx)
+  const key = row.claim_key
+  const capturedClaim = structuredClone(claim)
+  validateClaim(capturedClaim)
+  if (Key.of(capturedClaim) !== key) {
+    throw new Error(`CAVE record: malformed ${format}/v${version} semantic identity`)
+  }
+  const capturedProvenance = structuredClone(provenance)
+  if (parseProvenance(capturedProvenance) === undefined) {
+    throw new Error(`CAVE record: malformed ${format}/v${version} provenance`)
+  }
+  return {
+    format,
+    version,
+    id,
+    tx,
+    key,
+    canonical: emitClaim(capturedClaim),
+    claim: capturedClaim,
+    provenance: capturedProvenance,
+  }
+}
 
 const object = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
 
-const strings = (value: unknown): value is readonly string[] =>
-  Array.isArray(value) && value.every(entry => typeof entry === 'string')
+const strings = (value: unknown): value is readonly string[] => {
+  if (!Array.isArray(value)) return false
+  for (const entry of value) if (typeof entry !== 'string') return false
+  return true
+}
+
+const term = (value: unknown): boolean => object(value) &&
+  (value['kind'] === 'entity' || value['kind'] === 'text' || value['kind'] === 'code') &&
+  typeof value['text'] === 'string'
+
+const semanticValue = (value: unknown): boolean => {
+  if (!object(value) || typeof value['kind'] !== 'string' ||
+      !['number', 'trajectory', 'date', 'atom', 'text', 'code'].includes(value['kind']) ||
+      typeof value['raw'] !== 'string' || typeof value['approx'] !== 'boolean' ||
+      (value['unit'] !== undefined && typeof value['unit'] !== 'string')) return false
+  for (const field of ['num', 'from', 'to']) {
+    const number = value[field]
+    if (number !== undefined && (typeof number !== 'number' || !Number.isFinite(number))) return false
+  }
+  const parsed = value['kind'] === 'text' ? Value.ofText(value['raw']) :
+    value['kind'] === 'code' ? Value.ofCode(value['raw']) : Value.parse(value['raw'])
+  return value['kind'] === parsed.kind && value['approx'] === parsed.approx &&
+    value['num'] === parsed.num && value['from'] === parsed.from && value['to'] === parsed.to &&
+    value['unit'] === parsed.unit
+}
+
+const payload = (value: Record<string, unknown>): boolean => {
+  switch (value['kind']) {
+    case 'none': return true
+    case 'relation': return term(value['object'])
+    case 'attribute': return typeof value['attribute'] === 'string' && semanticValue(value['value'])
+    case 'metric': return semanticValue(value['value'])
+    default: return false
+  }
+}
+
+const validateClaim = (claim: unknown): void => {
+  if (!object(claim) || !object(claim['subject']) || !object(claim['payload']) ||
+      typeof claim['verb'] !== 'string' || typeof claim['negated'] !== 'boolean' ||
+      !strings(claim['contexts']) || !Array.isArray(claim['tags']) ||
+      typeof claim['conf'] !== 'number' || typeof claim['importance'] !== 'boolean' ||
+      typeof claim['raw'] !== 'string') {
+    throw new Error(`CAVE record: malformed ${format}/v${version}`)
+  }
+  for (const tag of claim['tags']) {
+    if (!object(tag) || typeof tag['key'] !== 'string' ||
+        (tag['value'] !== undefined && typeof tag['value'] !== 'string')) {
+      throw new Error(`CAVE record: malformed ${format}/v${version} tag`)
+    }
+  }
+  if (!term(claim['subject']) ||
+      (claim['payload']['kind'] === 'relation' && !term(claim['payload']['object']))) {
+    throw new Error(`CAVE record: malformed ${format}/v${version} term`)
+  }
+  if (!payload(claim['payload'])) {
+    throw new Error(`CAVE record: malformed ${format}/v${version} payload`)
+  }
+  const sigmaLevel = claim['sigmaLevel']
+  const delta = claim['delta']
+  if ((delta !== undefined && (!semanticValue(delta) || !object(delta) ||
+        typeof delta['num'] !== 'number' || delta['num'] <= 0)) ||
+      (sigmaLevel !== undefined && (typeof sigmaLevel !== 'number' || !Number.isFinite(sigmaLevel) || sigmaLevel <= 0)) ||
+      (claim['comment'] !== undefined && typeof claim['comment'] !== 'string')) {
+    throw new Error(`CAVE record: malformed ${format}/v${version} metadata`)
+  }
+}
 
 /** Decode a persisted v1 fixture, rejecting unknown future formats loudly. */
 export const decode = (input: string | unknown): t => {
-  const value: unknown = typeof input === 'string' ? JSON.parse(input) : input
+  const value: unknown = typeof input === 'string' ? JSON.parse(input) : structuredClone(input)
   if (!object(value) || value['format'] !== format) {
     throw new Error(`CAVE record: expected format ${JSON.stringify(format)}`)
   }
   if (value['version'] !== version) {
     throw new Error(`CAVE record: unsupported ${format} version ${JSON.stringify(value['version'])}`)
   }
-  const claim = value['claim']
-  const provenance = value['provenance']
   if (typeof value['id'] !== 'string' || typeof value['tx'] !== 'string' ||
       typeof value['key'] !== 'string' || typeof value['canonical'] !== 'string' ||
-      !object(claim) || !object(claim['subject']) || !object(claim['payload']) ||
-      typeof claim['verb'] !== 'string' || typeof claim['negated'] !== 'boolean' ||
-      !strings(claim['contexts']) || !Array.isArray(claim['tags']) ||
-      typeof claim['conf'] !== 'number' || typeof claim['importance'] !== 'boolean' ||
-      typeof claim['raw'] !== 'string' || !object(provenance) ||
-      !strings(provenance['actors']) || !strings(provenance['sources']) ||
-      !strings(provenance['runs']) || !strings(provenance['domains'])) {
+      parseProvenance(value['provenance']) === undefined) {
     throw new Error(`CAVE record: malformed ${format}/v${version}`)
   }
+  validateClaim(value['claim'])
   const decoded = value as t
-  if (!Uuidv7.is(decoded.id) || !Uuidv7.is(decoded.tx)) {
-    throw new Error(`CAVE record: malformed ${format}/v${version} transaction identity`)
-  }
+  requireTransactionIdentity(decoded.id, decoded.tx)
   if (Key.of(decoded.claim) !== decoded.key || emitClaim(decoded.claim) !== decoded.canonical) {
     throw new Error(`CAVE record: malformed ${format}/v${version} semantic identity`)
   }

package/src/resolve.ts

@@ -103,9 +103,10 @@ const rootOf = (entries: readonly Entry[], dimension: 'precedence' | 'reliabilit
  */
 const classOf = (entries: readonly Entry[], paths: readonly string[]): number => {
   const root = rootOf(entries, 'precedence') ?? 0
-  return paths.length === 0 ?
-    root :
-    Math.max(...paths.map(path => lookup(entries, path, 'precedence') ?? root))
+  if (paths.length === 0) return root
+  let maximum = Number.NEGATIVE_INFINITY
+  for (const path of paths) maximum = Math.max(maximum, lookup(entries, path, 'precedence') ?? root)
+  return maximum
 }
 
 type DeclarationRow = {
@@ -155,8 +156,7 @@ export const readPolicy = (db: Database, currentSql: string): Entry[] => {
       AND (c.subject = 'source' OR substr(c.subject, 1, 7) = 'source/')
   `).all() as unknown as DeclarationRow[]
   const sourcesOf = db.prepare(`
-    SELECT CASE WHEN instr(substr(context, 5), '#') = 0 THEN substr(context, 5)
-      ELSE substr(substr(context, 5), 1, instr(substr(context, 5), '#') - 1) END AS path
+    SELECT context
     FROM cave_context
     WHERE claim_id = ? AND substr(context, 1, 4) = 'src:'
   `)
@@ -168,8 +168,9 @@ export const readPolicy = (db: Database, currentSql: string): Entry[] => {
     if (value === undefined) {
       continue
     }
-    const paths = (sourcesOf.all(row.id) as { path: string }[]).map(source => source.path)
-    const key = `${row.subject}\0${row.attribute}`
+    const paths = (sourcesOf.all(row.id) as { context: string }[])
+      .map(source => source.context.slice(4).split('#', 1)[0]!)
+    const key = JSON.stringify([row.subject, row.attribute])
     const candidates = contests.get(key) ?? []
     candidates.push({ row, value, cls: classOf(builtins, paths) })
     contests.set(key, candidates)
@@ -179,7 +180,7 @@ export const readPolicy = (db: Database, currentSql: string): Entry[] => {
     builtins.map(entry => [entry.prefix, { ...entry }])
   )
   for (const [key, candidates] of contests) {
-    const [subject, attribute] = key.split('\0') as [string, string]
+    const [subject, attribute] = JSON.parse(key) as [string, string]
     const winner = candidates.sort((a, b) =>
       b.cls - a.cls || b.row.conf - a.row.conf || (a.row.tx < b.row.tx ? 1 : a.row.tx > b.row.tx ? -1 : 0))[0]!
     const prefix = subject === 'source' ? '' : subject.slice('source/'.length)
@@ -190,8 +191,13 @@ export const readPolicy = (db: Database, currentSql: string): Entry[] => {
   return [...merged.values()].sort((a, b) => a.prefix < b.prefix ? -1 : a.prefix > b.prefix ? 1 : 0)
 }
 
-const sqlString = (text: string): string =>
-  `'${text.replaceAll("'", "''")}'`
+const sqlString = (text: string): string => {
+  if (text.includes('\0')) {
+    const hex = Array.from(new TextEncoder().encode(text), byte => byte.toString(16).padStart(2, '0')).join('')
+    return `CAST(X'${hex}' AS TEXT)`
+  }
+  return `'${text.replaceAll("'", "''")}'`
+}
 
 const sqlNumber = (value: undefined | number): string =>
   value !== undefined && Number.isFinite(value) ? String(value) : 'NULL'
@@ -218,8 +224,20 @@ export const rankedSql = (
   currentSql: string,
   options: { aliases?: boolean } = {}
 ): string => {
-  const values = entries.map(entry =>
-    `(${sqlString(entry.prefix)}, ${sqlNumber(entry.precedence)}, ${sqlNumber(entry.reliability)})`)
+  let policySql: string
+  const materialized = entries.length > 16
+  if (materialized) {
+    const finite = (value: undefined | number): null | number =>
+      value !== undefined && Number.isFinite(value) ? value : null
+    const data = JSON.stringify(entries.map(entry =>
+      [entry.prefix, finite(entry.precedence), finite(entry.reliability)]))
+    policySql = `SELECT json_extract(value, '$[0]'), json_extract(value, '$[1]'), ` +
+      `json_extract(value, '$[2]') FROM json_each(${sqlString(data)})`
+  } else {
+    const values = entries.map(entry =>
+      `(${sqlString(entry.prefix)}, ${sqlNumber(entry.precedence)}, ${sqlNumber(entry.reliability)})`)
+    policySql = values.length === 0 ? 'SELECT NULL, NULL, NULL WHERE 0' : `VALUES ${values.join(', ')}`
+  }
   const rootClass = sqlNumber(rootOf(entries, 'precedence') ?? 0)
   const rootReliability = sqlNumber(rootOf(entries, 'reliability') ?? 1)
   // Alias representative: the closure group's smallest member name —
@@ -228,11 +246,14 @@ export const rankedSql = (
     `min(${expr}, COALESCE((SELECT MIN(ap.b) FROM alias_pair ap WHERE ap.a = ${expr}), ${expr}))`
   const subjectPart = `json_extract(c.claim_key, '$[0]')`
   const payloadPart = `json_extract(c.claim_key, '$[3]')`
+  // Strip the ASCII key marker in bytes; TEXT substr stops at an embedded NUL.
+  const entityName = (part: string, start: number): string =>
+    `CAST(substr(CAST(${part} AS BLOB), ${start}) AS TEXT)`
   const subjectExpr = options.aliases === true ?
-    `CASE WHEN substr(${subjectPart}, 1, 2) = 'e:' THEN 'e:' || ${representative(`substr(${subjectPart}, 3)`)} ELSE ${subjectPart} END` :
+    `CASE WHEN substr(${subjectPart}, 1, 2) = 'e:' THEN 'e:' || ${representative(entityName(subjectPart, 3))} ELSE ${subjectPart} END` :
     subjectPart
   const payloadExpr = options.aliases === true ?
-    `CASE WHEN substr(${payloadPart}, 1, 4) = 'r:e:' THEN 'r:e:' || ${representative(`substr(${payloadPart}, 5)`)} ELSE ${payloadPart} END` :
+    `CASE WHEN substr(${payloadPart}, 1, 4) = 'r:e:' THEN 'r:e:' || ${representative(entityName(payloadPart, 5))} ELSE ${payloadPart} END` :
     payloadPart
   // Claim key modulo polarity and src: contexts (spec §26.1). Contexts in
   // the key are already sorted; filtering preserves the order.
@@ -249,14 +270,16 @@ export const rankedSql = (
   // Longest-prefix match of one source path against the policy (spec §26.3).
   const matched = (column: string): string =>
     `(SELECT y.${column} FROM cave_policy y WHERE y.${column} IS NOT NULL AND ` +
-    `(y.prefix = '' OR x.path = y.prefix OR substr(x.path, 1, length(y.prefix) + 1) = y.prefix || '/') ` +
-    `ORDER BY length(y.prefix) DESC LIMIT 1)`
-  const classExpr = `COALESCE((SELECT MAX(${matched('cls')}) FROM (${paths}) x), ${rootClass})`
-  const reliabilityExpr = `COALESCE((SELECT MIN(${matched('rel')}) FROM (${paths}) x), ${rootReliability})`
+    `(y.prefix = '' OR x.path = y.prefix OR ` +
+    `substr(CAST(x.path AS BLOB), 1, length(CAST(y.prefix AS BLOB)) + 1) = CAST(y.prefix || '/' AS BLOB)) ` +
+    `ORDER BY length(CAST(y.prefix AS BLOB)) DESC LIMIT 1)`
+  const classExpr = `COALESCE((SELECT MAX(COALESCE(${matched('cls')}, ${rootClass})) FROM (${paths}) x), ${rootClass})`
+  const reliabilityExpr = `COALESCE((SELECT MIN(COALESCE(${matched('rel')}, ${rootReliability})) FROM (${paths}) x), ${rootReliability})`
   const order = `${classExpr} DESC, c.conf * ${reliabilityExpr} DESC, c.tx DESC`
+  // REAL projection keeps finite JS numbers out of the driver's int64 decoder.
   return `
-WITH cave_policy(prefix, cls, rel) AS (VALUES ${values.join(', ')})
-SELECT c.*, ${groupExpr} AS res_group, ${classExpr} AS res_class, c.conf * ${reliabilityExpr} AS res_conf,
+WITH cave_policy(prefix, cls, rel) AS ${materialized ? 'MATERIALIZED ' : ''}(${policySql})
+SELECT c.*, ${groupExpr} AS res_group, CAST(${classExpr} AS REAL) AS res_class, c.conf * ${reliabilityExpr} AS res_conf,
   ROW_NUMBER() OVER (PARTITION BY ${groupExpr} ORDER BY ${order}) AS res_rank
 FROM (${currentSql}) c
 WHERE c.conf > 0`

package/src/row.ts

@@ -124,8 +124,19 @@ export const toClaim = (
   row: Row,
   contexts: readonly string[],
   tags: readonly { key: string, value: null | string }[]
-): Claim.t =>
-  Claim.of({
+): Claim.t => {
+  for (const field of ['negated', 'importance', 'value_approx'] as const) {
+    if (row[field] !== 0 && row[field] !== 1) {
+      throw new TypeError(`stored claim ${field} must be 0 or 1`)
+    }
+  }
+  if (row.object !== null && (row.attribute !== null || row.value_text !== null)) {
+    throw new TypeError('stored claim payload cannot combine an object with an attribute or value')
+  }
+  if (row.attribute !== null && row.value_text === null) {
+    throw new TypeError('stored claim attribute payload requires a value')
+  }
+  const claim = Claim.of({
     subject: parseTerm(row.subject),
     verb: row.verb,
     negated: row.negated !== 0,
@@ -143,3 +154,19 @@ export const toClaim = (
     ...row.comment !== null ? { comment: row.comment } : {},
     raw: row.raw_line
   })
+  const value = claim.payload.kind === 'attribute' || claim.payload.kind === 'metric'
+    ? claim.payload.value : undefined
+  const expected = {
+    value_num: value?.num ?? null,
+    value_unit: value?.unit ?? null,
+    value_approx: value?.approx === true ? 1 : 0,
+    delta_num: claim.delta?.num ?? null,
+    delta_unit: claim.delta?.unit ?? null
+  }
+  for (const field of Object.keys(expected) as (keyof typeof expected)[]) {
+    if (row[field] !== expected[field]) {
+      throw new TypeError(`stored claim ${field} does not agree with its authored value`)
+    }
+  }
+  return claim
+}

package/src/runtime.ts

@@ -34,9 +34,12 @@ const declarationsAsOf = (store: BaseStore, asOf: string): Declaration[] => {
     SELECT subject, verb, object FROM cave_claim
     WHERE tx ${boundary.operator} ?
       AND negated = 0 AND object IS NOT NULL AND verb IN ('REVERSE', 'RENAMED-TO', 'IS')
-      AND id NOT IN (SELECT child_id FROM cave_edge WHERE role IN ('WHEN', 'VIA', 'BECAUSE'))
+      AND id NOT IN (
+        SELECT e.child_id FROM cave_edge e JOIN cave_claim parent ON parent.id = e.parent_id
+        WHERE e.role IN ('WHEN', 'VIA', 'BECAUSE') AND parent.tx ${boundary.operator} ?
+      )
     ORDER BY tx
-  `).all(boundary.tx) as Declaration[]
+  `).all(boundary.tx, boundary.tx) as Declaration[]
 }
 
 const applyDeclarations = (
@@ -71,8 +74,9 @@ export const openWith = (
   path: string = ':memory:',
   options: OpenOptions = {}
 ): Store => {
-  const baseRegistry = options.registry ?? Canonical.standardRegistry
-  const store = openStore(adapter, path, options)
+  const { registry, access } = options
+  const baseRegistry = registry ?? Canonical.standardRegistry
+  const store = openStore(adapter, path, { registry: baseRegistry, access })
   return Object.assign(store, {
     registryAsOf: (asOf: string): Canonical.Registry.t =>
       applyDeclarations(baseRegistry, declarationsAsOf(store, asOf))

package/src/schema.ts

@@ -1,9 +1,10 @@
 /** Ordered, transactional storage schema migrations (spec §13). */
 
-import type { Capabilities, Database } from './adapter.ts'
+import type { Capabilities, Database, Row } from './adapter.ts'
 import * as Provenance from './provenance.ts'
+import { errorMessage } from './error-message.ts'
 
-export const currentVersion = 1
+export const currentVersion = 2
 
 const ddlBeforeFts = `
 CREATE TABLE IF NOT EXISTS cave_claim (
@@ -88,7 +89,8 @@ CREATE VIRTUAL TABLE IF NOT EXISTS cave_fts USING ${fullText}(
 `
 
 /** Default Node/FTS5 schema SQL retained for callers that inspect the DDL. */
-export const ddl = ddlBeforeFts + ftsDdl('fts5')
+const transactionIndexDdl = 'CREATE INDEX IF NOT EXISTS idx_cave_tx ON cave_claim (tx);'
+export const ddl = ddlBeforeFts + ftsDdl('fts5') + transactionIndexDdl
 
 const ddlFor = (capabilities: Capabilities): string =>
   ddlBeforeFts + ftsDdl(capabilities.fullText)
@@ -105,7 +107,8 @@ const migrations: readonly Migration[] = [
       db.exec(ddlFor(capabilities))
       Provenance.backfill(db)
     }
-  }
+  },
+  { version: 2, up: db => { db.exec(transactionIndexDdl) } }
 ]
 
 export const versionOf = (db: Database): number =>
@@ -116,10 +119,21 @@ const requiredTables = [
 ] as const
 
 const requiredIndexes = [
-  'idx_cave_claim_key_tx', 'idx_cave_subject', 'idx_cave_verb', 'idx_cave_object',
-  'idx_cave_attribute', 'idx_cave_conf', 'idx_cave_context', 'idx_cave_context_claim',
-  'idx_cave_provenance_lookup', 'idx_cave_tag_key', 'idx_cave_tag_claim',
-  'idx_cave_edge_parent', 'idx_cave_edge_child', 'idx_cave_edge_role'
+  ['idx_cave_claim_key_tx', 'cave_claim', ['claim_key', 'tx']],
+  ['idx_cave_subject', 'cave_claim', ['subject']],
+  ['idx_cave_verb', 'cave_claim', ['verb']],
+  ['idx_cave_object', 'cave_claim', ['object']],
+  ['idx_cave_attribute', 'cave_claim', ['attribute']],
+  ['idx_cave_conf', 'cave_claim', ['conf']],
+  ['idx_cave_context', 'cave_context', ['context']],
+  ['idx_cave_context_claim', 'cave_context', ['claim_id', 'context']],
+  ['idx_cave_provenance_lookup', 'cave_provenance', ['dimension', 'value', 'claim_id']],
+  ['idx_cave_tag_key', 'cave_tag', ['key', 'value']],
+  ['idx_cave_tag_claim', 'cave_tag', ['claim_id', 'key', 'value']],
+  ['idx_cave_edge_parent', 'cave_edge', ['parent_id']],
+  ['idx_cave_edge_child', 'cave_edge', ['child_id']],
+  ['idx_cave_edge_role', 'cave_edge', ['role']],
+  ['idx_cave_tx', 'cave_claim', ['tx']]
 ] as const
 
 const requiredColumns: Readonly<Record<string, readonly string[]>> = {
@@ -135,27 +149,111 @@ const requiredColumns: Readonly<Record<string, readonly string[]>> = {
   cave_fts: ['claim_id', 'subject', 'verb', 'object', 'attribute', 'value_text', 'comment', 'raw_line']
 }
 
+const requiredPrimaryKeys: Readonly<Record<string, readonly string[]>> = {
+  cave_claim: ['id'],
+  cave_provenance: ['claim_id', 'dimension', 'value']
+}
+
+const numericClaimColumns = new Set([
+  'negated', 'value_num', 'value_approx', 'delta_num', 'sigma_level', 'conf', 'importance'
+])
+const fractionalClaimColumns = new Set(['value_num', 'delta_num', 'sigma_level', 'conf'])
+
+// SQLite checks INT before CHAR/CLOB/TEXT: CHARINT is integer-affinity.
+const affinityFamily = (type: unknown): 'TEXT' | 'numeric' | 'BLOB' => {
+  const declared = String(type).toUpperCase()
+  if (declared.includes('INT')) return 'numeric'
+  if (/CHAR|CLOB|TEXT/.test(declared)) return 'TEXT'
+  if (declared === '' || declared.includes('BLOB')) return 'BLOB'
+  // INTEGER, REAL and NUMERIC all retain numeric comparison semantics.
+  return 'numeric'
+}
+
 export const validate = (db: Database, version: number, schema = 'main'): void => {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(schema)) {
     throw new Error(`CAVE: invalid SQLite schema name ${JSON.stringify(schema)}`)
   }
+  const indexes = requiredIndexes.filter(([name]) => version >= 2 || name !== 'idx_cave_tx')
+  const tables = new Map(db.prepare(`PRAGMA ${schema}.table_list`).all().map(row => [row.name, row]))
+  const indexLists = new Map<string, Row[]>()
+  const indexesOf = (table: string): Row[] => {
+    let rows = indexLists.get(table)
+    if (rows === undefined) {
+      rows = db.prepare(`PRAGMA ${schema}.index_list(${table})`).all()
+      indexLists.set(table, rows)
+    }
+    return rows
+  }
   const objects = new Map(
     (db.prepare(`SELECT name, type FROM ${schema}.sqlite_schema WHERE name LIKE 'cave_%' OR name LIKE 'idx_cave_%'`)
       .all() as { name: string, type: string }[]).map(row => [row.name, row.type])
   )
   const problems = [
-    ...requiredTables.flatMap(name => objects.has(name) ? [] : [`missing table ${name}`]),
-    ...requiredIndexes.flatMap(name => objects.get(name) === 'index' ? [] : [`missing index ${name}`]),
+    ...requiredTables.flatMap(name => objects.get(name) === 'table' ? [] : [`missing table ${name}`]),
+    ...indexes
+      .flatMap(([name]) => objects.get(name) === 'index' ? [] : [`missing index ${name}`]),
     ...Object.entries(requiredColumns).flatMap(([table, required]) => {
       if (!objects.has(table)) {
         return []
       }
-      const columns = new Set(
-        (db.prepare(`PRAGMA ${schema}.table_info(${table})`).all() as { name: string }[]).map(row => row.name)
-      )
-      return required.flatMap(column => columns.has(column) ? [] : [`missing column ${table}.${column}`])
+      const info = db.prepare(`PRAGMA ${schema}.table_info(${table})`).all()
+      const columns = new Set(info.map(row => row.name))
+      const expectedKey = requiredPrimaryKeys[table]
+      const key = info.filter(row => Number(row.pk) > 0)
+        .sort((left, right) => Number(left.pk) - Number(right.pk)).map(row => row.name)
+      let binaryKey = true
+      if (expectedKey !== undefined) {
+        const primary = indexesOf(table).find(row => row.origin === 'pk')
+        const name = typeof primary?.name === 'string' ? primary.name : undefined
+        const indexed = name === undefined ? [] :
+          db.prepare(`PRAGMA ${schema}.index_xinfo("${name.replaceAll('"', '""')}")`).all()
+            .filter(row => Number(row.key) === 1)
+        binaryKey = indexed.length === expectedKey.length &&
+          indexed.every(row => String(row.coll).toUpperCase() === 'BINARY')
+      }
+      return [
+        ...required.flatMap(column => columns.has(column) ? [] : [`missing column ${table}.${column}`]),
+        ...info.flatMap(row => {
+          const column = String(row.name)
+          // FTS virtual columns have module-defined storage, not ordinary affinity.
+          if (table === 'cave_fts' || !required.includes(column)) return []
+          const strict = Number(tables.get(table)?.strict) === 1
+          const declared = String(row.type).toUpperCase()
+          if (strict && table === 'cave_claim' && fractionalClaimColumns.has(column) && declared !== 'REAL') {
+            return [`incompatible column ${table}.${column}: expected REAL in a STRICT table`]
+          }
+          const expected = table === 'cave_claim' && numericClaimColumns.has(column) ? 'numeric' : 'TEXT'
+          const affinity = strict && declared === 'ANY' ? 'BLOB' : affinityFamily(row.type)
+          return affinity === expected ? [] :
+            [`incompatible column ${table}.${column}: expected ${expected} affinity`]
+        }),
+        ...(expectedKey !== undefined && (!binaryKey || key.length !== expectedKey.length || key.some((name, index) => name !== expectedKey[index]))
+          ? [`incompatible table ${table}: expected primary key (${expectedKey.join(', ')}) with BINARY collation`] : [])
+      ]
     })
   ]
+  if (objects.get('cave_fts') === 'table') {
+    const searchTable = tables.get('cave_fts')
+    if (searchTable?.type !== 'virtual') {
+      problems.push('incompatible table cave_fts: expected a virtual table for full-text search')
+    } else {
+      const searchColumns = db.prepare(`PRAGMA ${schema}.table_xinfo(cave_fts)`).all()
+      if (!searchColumns.some(row => row.name === 'cave_fts' && Number(row.hidden) === 1)) {
+        problems.push('incompatible table cave_fts: missing the hidden full-text search column')
+      }
+    }
+  }
+  for (const [name, table, expected] of indexes) {
+    if (objects.get(name) !== 'index') continue
+    const columns = db.prepare(`PRAGMA ${schema}.index_xinfo(${name})`).all()
+      .filter(row => Number(row.key) === 1)
+    const index = indexesOf(table).find(row => row.name === name)
+    if (index === undefined || Number(index.unique) !== 0 || Number(index.partial) !== 0 ||
+        columns.length !== expected.length || columns.some((column, position) =>
+          column.name !== expected[position] || String(column.coll).toUpperCase() !== 'BINARY')) {
+      problems.push(`incompatible index ${name}: expected non-unique ${table}(${expected.map(column => `${column} COLLATE BINARY`).join(', ')}) without a partial predicate`)
+    }
+  }
   if (problems.length > 0) {
     throw new Error(`CAVE: schema version ${version} is incompatible: ${problems.join(', ')}`)
   }
@@ -214,11 +312,12 @@ export const init = (
     } catch (error) {
       try {
         db.exec('ROLLBACK')
-      } catch {
-        // SQLite may already have rolled back a failed statement.
+      } catch (rollbackError) {
+        throw new AggregateError([error, rollbackError],
+          `CAVE: schema migration ${version} -> ${migration.version} failed: ${errorMessage(error)}; rollback also failed: ${errorMessage(rollbackError)}`,
+          { cause: error })
       }
-      const detail = error instanceof Error ? error.message : String(error)
-      throw new Error(`CAVE: schema migration ${version} -> ${migration.version} failed: ${detail}`)
+      throw new Error(`CAVE: schema migration ${version} -> ${migration.version} failed: ${errorMessage(error)}`, { cause: error })
     }
   }
   validate(db, version)