@cavelang/store 0.27.14 → 0.29.1

package/src/store.ts

@@ -1,15 +1,15 @@
 /**
  * The CAVE store (spec §13) — append-only claim persistence on the Node.js
- * builtin `node:sqlite`.
+ * through an explicit synchronous SQLite adapter.
  *
  * - one row per fact, canonical direction; inverses are query-time views
  *   over existing indexes, never materialized rows (spec §13.3);
  * - current belief = latest tx per claim key (spec §9.1, §13.5);
  * - the verb registry is rebuilt from stored in-band declaration claims on
- *   open, so a reopened database keeps its inverse vocabulary;
+ *   open, so a reopened database keeps its inverse and lifecycle vocabulary;
  * - full-text search over subjects, objects, values, comments and raw
  *   lines via FTS5;
- * - appends can stamp actor provenance (spec §9.5): pass `source` and every
+ * - appends record actor provenance and keep compatibility stamps (spec §9.5): pass `source` and every
  *   claim without a `src:` context gets `@src:<actor>` — applied before the
  *   claim key is computed, so different actors keep separate belief series;
  * - contradiction resolution (spec §26): coexisting series about one fact
@@ -18,65 +18,27 @@
  *   traversal opt-in.
  */
 
-import { DatabaseSync } from 'node:sqlite'
 import { Claim, Context, Key, Uuidv7, Verb } from '@cavelang/core'
 import * as Canonical from '@cavelang/canonical'
+import type { Adapter } from './adapter.ts'
+import * as QuerySql from './query-sql.ts'
 import * as Resolve from './resolve.ts'
 import * as Row from './row.ts'
 import * as Schema from './schema.ts'
+import * as Sensitivity from './sensitivity.ts'
+import * as Provenance from './provenance.ts'
+import * as Record from './record.ts'
 
-const currentSql = `
-SELECT c.* FROM cave_claim c
-JOIN (
-  SELECT claim_key, MAX(tx) AS max_tx
-  FROM cave_claim GROUP BY claim_key
-) latest ON c.claim_key = latest.claim_key AND c.tx = latest.max_tx
-`
-
-/**
- * Alias edges (spec §13.6): current positive `ALIAS` claims read as
- * undirected (`ALIAS` has no `REVERSE`, so each written direction is its
- * own claim key — both assert the same link). Retraction unmerges:
- * `a ALIAS b @ 0%` drops that direction's edge. Both endpoints must be
- * entity-form — the closure is defined for entity terms only, so a row
- * naming a `"…"`/`` `…` `` literal contributes no edge and two entities
- * aliasing one literal never link through it.
- */
-const aliasEdgeSql = `alias_edge(a, b) AS (
-  SELECT c.subject, c.object FROM (${currentSql}) c
-  WHERE c.verb = 'ALIAS' AND c.negated = 0 AND c.conf > 0 AND c.object IS NOT NULL
-    AND ${Row.entityTermSql('c.subject')} AND ${Row.entityTermSql('c.object')}
-  UNION
-  SELECT c.object, c.subject FROM (${currentSql}) c
-  WHERE c.verb = 'ALIAS' AND c.negated = 0 AND c.conf > 0 AND c.object IS NOT NULL
-    AND ${Row.entityTermSql('c.subject')} AND ${Row.entityTermSql('c.object')}
-)`
+const currentSql = QuerySql.current()
 
 /**
  * The closure walked from a seed entity — the seed is the query's first
  * positional parameter. Requires `alias_edge` in scope.
  */
-const aliasSeedSql = `alias_closure(name) AS (
-  SELECT ?
-  UNION
-  SELECT e.b FROM alias_closure s JOIN alias_edge e ON e.a = s.name
-)`
-
-/**
- * The full transitive closure as ordered pairs — every two names currently
- * believed to denote one entity. Resolution grouping widens through it
- * (spec §26.1). Requires `alias_edge` in scope.
- */
-const aliasPairSql = `alias_pair(a, b) AS (
-  SELECT a, b FROM alias_edge
-  UNION
-  SELECT p.a, e.b FROM alias_pair p JOIN alias_edge e ON e.a = p.b
-)`
+const aliasSeedSql = QuerySql.aliasSeed()
 
 /** Seeded alias closure (spec §13.6), ready to prefix a SELECT. */
-const aliasClosureSql = `
-WITH RECURSIVE ${aliasEdgeSql}, ${aliasSeedSql}
-`
+const aliasClosureSql = QuerySql.aliasClosure(currentSql)
 
 export type IngestResult = {
   /** ids of the batch's claim rows, in document order — for a row skipped as already present (`ids` replay, spec §28.1), the existing id. */
@@ -90,7 +52,8 @@ export type IngestResult = {
 
 export type AppendOptions = {
   /**
-   * Actor provenance (spec §9.5): stamp `@src:<source>` on every appended
+   * Actor provenance (spec §9.5): record actor `<source>` and stamp
+   * `@src:<source>` on every appended
    * claim that carries no `src:` context — e.g. `cli`, `agent/claude-code`,
    * `ingest/93a01c626b3f`. Applied before the claim key is computed, so the
    * stamp is part of claim identity; claims that already name a source keep
@@ -99,15 +62,23 @@ export type AppendOptions = {
    */
   readonly source?: string
   /**
-   * Lifecycle stamping (spec §9.5): stamp `@src:<source>` even when the
+   * Lifecycle ownership (spec §9.5.1): record run `<source>` and stamp
+   * `@src:<source>` even when the
    * claim already names a source. Connect records, rule conclusions and
-   * action effects are found for retraction and attribution by their
-   * stamp, so an authored `src:` context must not displace it — both are
-   * kept (multi-source rows resolve per §26.3). The exact stamp context
+   * action effects are found for retraction and attribution by their run,
+   * so an authored `src:` context must not displace it — both contexts are
+   * kept for compatibility (multi-source rows resolve per §26.3). The exact stamp context
    * is never duplicated. Without this flag an authored source suppresses
    * the stamp.
    */
   readonly lifecycle?: boolean
+  /**
+   * Additional structured contexts applied to every row before keying. Used
+   * by connectors to attach source spans without rewriting generated text.
+   */
+  readonly contexts?: readonly Context.t[]
+  /** Explicit provenance dimensions; compact contexts remain unchanged. */
+  readonly provenance?: Provenance.Input
   /**
    * Explicit row identity (spec §28.1), index-aligned with the result's
    * claims: a claim with an id here is replayed under it — inserted with
@@ -133,6 +104,11 @@ const stampSource = (claim: Claim.t, source: undefined | string, lifecycle: bool
     { ...claim, contexts: [...claim.contexts, context] }
 }
 
+const addContexts = (claim: Claim.t, contexts: readonly Context.t[] = []): Claim.t => {
+  const combined = Context.dedupe([...claim.contexts, ...contexts])
+  return combined.length === claim.contexts.length ? claim : { ...claim, contexts: combined }
+}
+
 export type ForwardFact = {
   /** Canonical (primary) verb. */
   readonly verb: string
@@ -187,18 +163,34 @@ export const defaultDbPath = (): string =>
  * already stored; pass `Canonical.Registry.empty` for a declaration-free
  * start.
  */
-export const open = (path: string = ':memory:', options: { registry?: Canonical.Registry.t } = {}) => {
-  const db = new DatabaseSync(path)
+export const open = (
+  adapter: Adapter,
+  path: string = ':memory:',
+  options: { registry?: Canonical.Registry.t } = {}
+) => {
+  const db = adapter.open(path)
+  // Concurrent writers wait for the database allocation lock instead of
+  // failing immediately with SQLITE_BUSY.
+  db.exec('PRAGMA busy_timeout = 5000')
   db.exec('PRAGMA foreign_keys = ON')
-  Schema.init(db)
+  try {
+    Schema.init(db, adapter.capabilities)
+  } catch (error) {
+    db.close()
+    throw error
+  }
 
   // The receive rule (spec §28.2): the store, not the wall clock, is the
   // monotonic authority — every append outsorts every tx already stored,
   // merged history from fast-clocked origins included.
-  const maxTx = db.prepare('SELECT MAX(tx) AS tx FROM cave_claim').get() as undefined | { tx: null | string }
-  if (maxTx?.tx != null) {
-    Uuidv7.observe(maxTx.tx)
+  const selectMaxTx = db.prepare('SELECT MAX(tx) AS tx FROM cave_claim')
+  const observeMaxTx = (): void => {
+    const maxTx = selectMaxTx.get() as undefined | { tx: null | string }
+    if (maxTx?.tx != null) {
+      Uuidv7.observe(maxTx.tx)
+    }
   }
+  observeMaxTx()
 
   const baseRegistry = options.registry ?? Canonical.standardRegistry
   let registry = baseRegistry
@@ -212,6 +204,8 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `)
   const insertContext = db.prepare('INSERT INTO cave_context (claim_id, context) VALUES (?, ?)')
+  const insertProvenance = db.prepare(
+    'INSERT OR IGNORE INTO cave_provenance (claim_id, dimension, value) VALUES (?, ?, ?)')
   const insertTag = db.prepare('INSERT INTO cave_tag (claim_id, key, value) VALUES (?, ?, ?)')
   const insertEdge = db.prepare('INSERT INTO cave_edge (parent_id, role, child_id) VALUES (?, ?, ?)')
   const insertFts = db.prepare(`
@@ -230,7 +224,7 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
   const rebuildRegistry = (): void => {
     const declarations = db.prepare(`
       SELECT subject, verb, object FROM cave_claim
-      WHERE negated = 0 AND object IS NOT NULL AND verb IN ('REVERSE', 'IS')
+      WHERE 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'))
       ORDER BY tx
     `).all() as { subject: string, verb: string, object: string }[]
@@ -240,6 +234,8 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
       }
       if (declaration.verb === 'REVERSE' && Verb.isVerbToken(declaration.object)) {
         registry = Canonical.Registry.declareReverse(registry, declaration.subject, declaration.object).registry
+      } else if (declaration.verb === 'RENAMED-TO' && Verb.isVerbToken(declaration.object)) {
+        registry = Canonical.Registry.declareRename(registry, declaration.subject, declaration.object).registry
       } else if (declaration.verb === 'IS' && declaration.object === 'verb') {
         registry = Canonical.Registry.declareVerb(registry, declaration.subject)
       }
@@ -248,25 +244,34 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
   rebuildRegistry()
 
   /**
-   * Savepoint-based, so transactions nest: a caller can wrap several
-   * appends — or an append plus checks against the appended state — and
-   * roll the whole group back by throwing (spec §20.3 write gating).
-   * Rollback also restores the in-memory verb registry, so declarations
-   * from rolled-back claims don't outlive their rows.
+   * The outer transaction takes SQLite's write-reservation lock before any
+   * transaction id is allocated, serializing concurrent processes. Nested
+   * transactions use savepoints, so a caller can still wrap several appends
+   * and checks and roll the group back by throwing (spec §20.3 write gating).
+   * Rollback also restores the in-memory verb registry.
    */
   let transactionDepth = 0
   const transaction = <T>(body: () => T): T => {
+    const outer = transactionDepth === 0
     const savepoint = `cave_tx_${transactionDepth}`
     transactionDepth += 1
     const savedRegistry = registry
-    db.exec(`SAVEPOINT ${savepoint}`)
+    let started = false
     try {
+      db.exec(outer ? 'BEGIN IMMEDIATE' : `SAVEPOINT ${savepoint}`)
+      started = true
       const result = body()
-      db.exec(`RELEASE ${savepoint}`)
+      db.exec(outer ? 'COMMIT' : `RELEASE ${savepoint}`)
       return result
     } catch (error) {
-      db.exec(`ROLLBACK TO ${savepoint}`)
-      db.exec(`RELEASE ${savepoint}`)
+      if (started) {
+        if (outer) {
+          db.exec('ROLLBACK')
+        } else {
+          db.exec(`ROLLBACK TO ${savepoint}`)
+          db.exec(`RELEASE ${savepoint}`)
+        }
+      }
       registry = savedRegistry
       throw error
     } finally {
@@ -283,6 +288,12 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
       const ids: string[] = []
       const replay = options_.ids !== undefined
       let skipped = 0
+      // BEGIN IMMEDIATE makes this read and all following inserts one
+      // database-serialized allocation step. A process that opened before a
+      // fast-clock peer wrote now observes that peer before minting (§28.2).
+      if (result.claims.some((_, index) => options_.ids?.[index] === undefined)) {
+        observeMaxTx()
+      }
       result.claims.forEach((entry, index) => {
         const explicit = options_.ids?.[index]
         if (explicit !== undefined) {
@@ -295,7 +306,14 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
             return
           }
         }
-        const claim = stampSource(entry.claim, options_.source, options_.lifecycle === true)
+        const authored = addContexts(entry.claim, options_.contexts)
+        const claim = stampSource(authored, options_.source, options_.lifecycle === true)
+        const provided = options_.provenance ?? {}
+        const provenance = Provenance.entries(authored.contexts, {
+          ...provided,
+          actor: provided.actor ?? options_.source,
+          run: provided.run ?? (options_.lifecycle === true ? options_.source : undefined)
+        })
         const id = explicit ?? Uuidv7.next()
         const columns = Row.toColumns(claim)
         const rawLine = columns.rawLine === '' ? Canonical.emitClaim(claim) : columns.rawLine
@@ -311,6 +329,9 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
         for (const context of claim.contexts) {
           insertContext.run(id, context)
         }
+        for (const entry of provenance) {
+          insertProvenance.run(id, entry.dimension, entry.value)
+        }
         for (const tag of claim.tags) {
           insertTag.run(id, tag.key, tag.value ?? null)
         }
@@ -347,6 +368,18 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
   const toClaim = (row: Row.t): Claim.t =>
     Row.toClaim(row, contextsOf(row.id), tagsOf(row.id))
 
+  const provenanceOf = (row: Row.t | string): Provenance.t => {
+    const id = typeof row === 'string' ? row : row.id
+    const entries = db.prepare(`
+      SELECT dimension, value FROM cave_provenance WHERE claim_id = ? ORDER BY dimension, value
+    `).all(id) as Provenance.Entry[]
+    return Provenance.fromEntries(entries)
+  }
+
+  /** Stable, versioned public representation of one storage row. */
+  const recordOf = (row: Row.t): Record.t =>
+    Record.of(row, toClaim(row), provenanceOf(row))
+
   const traversalFilter = (options: TraverseOptions): string =>
     (options.negated === true ? '' : ' AND negated = 0') +
     (options.retracted === true ? '' : ' AND conf > 0')
@@ -364,7 +397,7 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
     options.aliases === true ?
       // Resolution grouping needs the pair closure too (spec §26.1).
       (options.resolve === true ?
-        `\nWITH RECURSIVE ${aliasEdgeSql}, ${aliasPairSql}, ${aliasSeedSql}\n` :
+        `\nWITH RECURSIVE ${QuerySql.aliasPairs(currentSql)}, ${aliasSeedSql}\n` :
         aliasClosureSql) :
       ''
 
@@ -381,12 +414,18 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
       currentSql
 
   return {
-    /** Raw database handle — used by `@cavelang/query`; treat as read-only. */
+    /** Adapter that owns this database connection and its capabilities. */
+    adapter,
+
+    /** Raw adapter database handle — used by `@cavelang/query`; treat as read-only. */
     db,
 
     /** Current verb registry (input registry + stored + ingested declarations). */
     registry: (): Canonical.Registry.t => registry,
 
+    /** Configured registry before any in-band declarations are applied. */
+    baseRegistry: (): Canonical.Registry.t => baseRegistry,
+
     /**
      * Rebuilds the registry from the base plus stored declarations — after
      * rows arrive outside `ingest`/`insertResult` (a §28 merge writes
@@ -462,7 +501,7 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
      */
     resolvedBeliefs(options_: { aliases?: boolean } = {}): Row.t[] {
       const aliases = options_.aliases === true
-      const prefix = aliases ? `WITH RECURSIVE ${aliasEdgeSql}, ${aliasPairSql}\n` : ''
+      const prefix = aliases ? `WITH RECURSIVE ${QuerySql.aliasPairs(currentSql)}\n` : ''
       return rows(`${prefix}SELECT * FROM (${Resolve.resolvedSql(readPolicy(), currentSql, { aliases })}) ORDER BY tx`)
     },
 
@@ -475,7 +514,7 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
      */
     contested(options_: { aliases?: boolean } = {}): Resolve.Contested[] {
       const aliases = options_.aliases === true
-      const prefix = aliases ? `WITH RECURSIVE ${aliasEdgeSql}, ${aliasPairSql}\n` : ''
+      const prefix = aliases ? `WITH RECURSIVE ${QuerySql.aliasPairs(currentSql)}\n` : ''
       const ranked = rows(
         `${prefix}SELECT * FROM (${Resolve.rankedSql(readPolicy(), currentSql, { aliases })}) ORDER BY res_group, res_rank`
       ) as Resolve.Ranked[]
@@ -556,6 +595,19 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
         WHERE ctx.context = ? ORDER BY c.tx DESC`, context)
     },
 
+    /** Rows carrying one explicit provenance dimension, newest first. */
+    byProvenance(dimension: Provenance.Dimension, value: string): Row.t[] {
+      return rows(`
+        SELECT c.* FROM cave_claim c JOIN cave_provenance p ON c.id = p.claim_id
+        WHERE p.dimension = ? AND p.value = ? ORDER BY c.tx DESC`, dimension, value)
+    },
+
+    /** Explicit actor, physical source, lifecycle run, and domain metadata. */
+    provenanceOf,
+
+    /** Map a database-shaped row to the stable `cave.claim/v1` contract. */
+    recordOf,
+
     /** Members of a topic — forward `CONTAINS` traversal (spec §11.2). */
     topicMembers(topic: string, options_: TraverseOptions = {}): string[] {
       return rows(
@@ -579,11 +631,12 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
      * FTS5 MATCH syntax. `limit` caps the rows inside the query itself,
      * so a broad search never materializes more than the caller reads.
      */
-    search(query: string, options_: { raw?: boolean, limit?: number } = {}): Row.t[] {
+    search(query: string, options_: { raw?: boolean, limit?: number, maxSensitivity?: Sensitivity.Level } = {}): Row.t[] {
       const match = options_.raw === true ? query : `"${query.replaceAll('"', '""')}"`
       const sql = `
         SELECT c.* FROM cave_claim c JOIN cave_fts f ON c.id = f.claim_id
-        WHERE cave_fts MATCH ? ORDER BY c.tx DESC`
+        WHERE cave_fts MATCH ?${options_.maxSensitivity === undefined ? '' : ` AND ${Sensitivity.sql('c', options_.maxSensitivity)}`}
+        ORDER BY c.tx DESC`
       return options_.limit === undefined ?
         rows(sql, match) :
         rows(`${sql} LIMIT ?`, match, options_.limit)
@@ -629,11 +682,12 @@ export const open = (path: string = ':memory:', options: { registry?: Canonical.
      * endpoint resolves to the *current row of its claim key*, and the
      * resulting edges are deduplicated.
      */
-    exportText(options_: { current?: boolean, tx?: boolean } = {}): string {
+    exportText(options_: { current?: boolean, tx?: boolean, maxSensitivity?: Sensitivity.Level } = {}): string {
       const current = options_.current === true
+      const maximum = options_.maxSensitivity ?? Sensitivity.defaultMaximum
       const claimRows = current ?
-        rows(`${currentSql} ORDER BY c.tx`) :
-        rows('SELECT * FROM cave_claim ORDER BY tx')
+        rows(`${currentSql} WHERE ${Sensitivity.sql('c', maximum)} ORDER BY c.tx`) :
+        rows(`SELECT c.* FROM cave_claim c WHERE ${Sensitivity.sql('c', maximum)} ORDER BY c.tx`)
       const indexById = new Map(claimRows.map((row, index) => [row.id, index]))
       let resolve = (id: string): undefined | number => indexById.get(id)
       if (current) {