@cavelang/store 0.27.14 → 0.29.0

package/src/runtime.ts

@@ -0,0 +1,78 @@
+import { Verb } from '@cavelang/core'
+import * as Canonical from '@cavelang/canonical'
+import type { Adapter } from './adapter.ts'
+import * as QuerySql from './query-sql.ts'
+import { open as openStore } from './store.ts'
+import type { Store as BaseStore } from './store.ts'
+
+export type Store = BaseStore & {
+  /**
+   * Verb registry reconstructed from the configured base registry plus
+   * declaration rows visible at the transaction-time boundary.
+   */
+  readonly registryAsOf: (asOf: string) => Canonical.Registry.t
+}
+
+export type OpenOptions = {
+  readonly registry?: Canonical.Registry.t
+}
+
+type Declaration = {
+  readonly subject: string
+  readonly verb: string
+  readonly object: string
+}
+
+const declarationsAsOf = (store: BaseStore, asOf: string): Declaration[] => {
+  const boundary = QuerySql.asOfBoundary(asOf)
+  if (boundary === undefined) {
+    throw new Error(`CAVE: cannot parse as-of boundary ${JSON.stringify(asOf)}`)
+  }
+  return store.db.prepare(`
+    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'))
+    ORDER BY tx
+  `).all(boundary.tx) as Declaration[]
+}
+
+const applyDeclarations = (
+  baseRegistry: Canonical.Registry.t,
+  declarations: readonly Declaration[]
+): Canonical.Registry.t => {
+  let registry = baseRegistry
+  for (const declaration of declarations) {
+    if (!Verb.isVerbToken(declaration.subject)) continue
+    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)
+    }
+  }
+  return registry
+}
+
+/** Open a CAVE store with an explicitly selected SQLite implementation. */
+export const openWith = (
+  adapter: Adapter,
+  path: string = ':memory:',
+  options: OpenOptions = {}
+): Store => {
+  const baseRegistry = options.registry ?? Canonical.standardRegistry
+  const store = openStore(adapter, path, options)
+  return Object.assign(store, {
+    registryAsOf: (asOf: string): Canonical.Registry.t =>
+      applyDeclarations(baseRegistry, declarationsAsOf(store, asOf))
+  })
+}

package/src/schema.ts

@@ -1,11 +1,11 @@
-/**
- * Storage schema (spec §13.1, §13.2) — verbatim from the specification,
- * with `IF NOT EXISTS` added so opening an existing database is idempotent.
- */
+/** Ordered, transactional storage schema migrations (spec §13). */
+
+import type { Capabilities, Database } from './adapter.ts'
+import * as Provenance from './provenance.ts'
 
-import type { DatabaseSync } from 'node:sqlite'
+export const currentVersion = 1
 
-export const ddl = `
+const ddlBeforeFts = `
 CREATE TABLE IF NOT EXISTS cave_claim (
   id            TEXT PRIMARY KEY,      -- UUIDv7
   tx            TEXT NOT NULL,         -- UUIDv7, lexicographic = transaction order
@@ -50,6 +50,15 @@ CREATE TABLE IF NOT EXISTS cave_context (
 CREATE INDEX IF NOT EXISTS idx_cave_context ON cave_context (context);
 CREATE INDEX IF NOT EXISTS idx_cave_context_claim ON cave_context (claim_id, context);
 
+CREATE TABLE IF NOT EXISTS cave_provenance (
+  claim_id   TEXT NOT NULL,
+  dimension  TEXT NOT NULL CHECK (dimension IN ('actor', 'source', 'run', 'domain')),
+  value      TEXT NOT NULL,
+  PRIMARY KEY (claim_id, dimension, value),
+  FOREIGN KEY (claim_id) REFERENCES cave_claim(id)
+);
+CREATE INDEX IF NOT EXISTS idx_cave_provenance_lookup ON cave_provenance (dimension, value, claim_id);
+
 CREATE TABLE IF NOT EXISTS cave_tag (
   claim_id TEXT NOT NULL,
   key      TEXT NOT NULL,
@@ -70,12 +79,128 @@ CREATE INDEX IF NOT EXISTS idx_cave_edge_parent ON cave_edge (parent_id);
 CREATE INDEX IF NOT EXISTS idx_cave_edge_child  ON cave_edge (child_id);
 CREATE INDEX IF NOT EXISTS idx_cave_edge_role   ON cave_edge (role);
 
-CREATE VIRTUAL TABLE IF NOT EXISTS cave_fts USING fts5(
+`
+
+const ftsDdl = (fullText: Capabilities['fullText']): string => `
+CREATE VIRTUAL TABLE IF NOT EXISTS cave_fts USING ${fullText}(
   claim_id, subject, verb, object, attribute, value_text, comment, raw_line
 );
 `
 
-/** Creates all tables and indexes. */
-export const init = (db: DatabaseSync): void => {
-  db.exec(ddl)
+/** Default Node/FTS5 schema SQL retained for callers that inspect the DDL. */
+export const ddl = ddlBeforeFts + ftsDdl('fts5')
+
+const ddlFor = (capabilities: Capabilities): string =>
+  ddlBeforeFts + ftsDdl(capabilities.fullText)
+
+type Migration = {
+  readonly version: number
+  readonly up: (db: Database, capabilities: Capabilities) => void
+}
+
+const migrations: readonly Migration[] = [
+  {
+    version: 1,
+    up: (db, capabilities) => {
+      db.exec(ddlFor(capabilities))
+      Provenance.backfill(db)
+    }
+  }
+]
+
+const versionOf = (db: Database): number =>
+  (db.prepare('PRAGMA user_version').get() as { user_version: number }).user_version
+
+const requiredTables = [
+  'cave_claim', 'cave_context', 'cave_provenance', 'cave_tag', 'cave_edge', 'cave_fts'
+] 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'
+] as const
+
+const requiredColumns: Readonly<Record<string, readonly string[]>> = {
+  cave_claim: [
+    'id', 'tx', 'subject', 'verb', 'negated', 'object', 'attribute', 'value_text',
+    'value_num', 'value_unit', 'value_approx', 'delta_text', 'delta_num', 'delta_unit',
+    'sigma_level', 'conf', 'importance', 'comment', 'raw_line', 'claim_key'
+  ],
+  cave_context: ['claim_id', 'context'],
+  cave_provenance: ['claim_id', 'dimension', 'value'],
+  cave_tag: ['claim_id', 'key', 'value'],
+  cave_edge: ['parent_id', 'role', 'child_id'],
+  cave_fts: ['claim_id', 'subject', 'verb', 'object', 'attribute', 'value_text', 'comment', 'raw_line']
+}
+
+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 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}`]),
+    ...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}`])
+    })
+  ]
+  if (problems.length > 0) {
+    throw new Error(`CAVE: schema version ${version} is incompatible: ${problems.join(', ')}`)
+  }
+}
+
+/**
+ * Upgrade every supported older version in order. Each step owns one SQLite
+ * transaction, including its `user_version` update, so interruption leaves
+ * either the old version or the complete next version and reopen can resume.
+ */
+export const init = (
+  db: Database,
+  capabilities: Capabilities = {
+    transactions: { immediate: true, savepoints: true },
+    fullText: 'fts5',
+  }
+): void => {
+  let version = versionOf(db)
+  if (version > currentVersion) {
+    throw new Error(
+      `CAVE: schema version ${version} is newer than this runtime supports (${currentVersion}); upgrade CAVE`)
+  }
+  for (const migration of migrations) {
+    if (migration.version <= version) {
+      continue
+    }
+    if (migration.version !== version + 1) {
+      throw new Error(`CAVE: no schema migration path from version ${version} to ${migration.version}`)
+    }
+    db.exec('BEGIN IMMEDIATE')
+    try {
+      migration.up(db, capabilities)
+      db.exec(`PRAGMA user_version = ${migration.version}`)
+      validate(db, migration.version)
+      db.exec('COMMIT')
+      version = migration.version
+    } catch (error) {
+      try {
+        db.exec('ROLLBACK')
+      } catch {
+        // SQLite may already have rolled back a failed statement.
+      }
+      const detail = error instanceof Error ? error.message : String(error)
+      throw new Error(`CAVE: schema migration ${version} -> ${migration.version} failed: ${detail}`)
+    }
+  }
+  validate(db, version)
 }

package/src/sensitivity.ts

@@ -0,0 +1,42 @@
+/**
+ * Sensitivity labels and row visibility (spec §9.7).
+ *
+ * Claims opt into a level with `#sensitivity:<level>`. Unlabelled rows are
+ * `internal`; malformed, flat, or unknown labels fail closed as `restricted`.
+ * Several labels on one row resolve to the most restrictive one.
+ */
+
+export const levels = ['public', 'internal', 'confidential', 'restricted'] as const
+export type Level = (typeof levels)[number]
+
+export const defaultLevel: Level = 'internal'
+export const defaultMaximum: Level = 'internal'
+
+export const parse = (value: string): undefined | Level =>
+  levels.includes(value as Level) ? value as Level : undefined
+
+export const rank = (level: Level): number => levels.indexOf(level)
+
+/**
+ * SQL predicate that allows rows at or below `maximum`. `alias` must be a
+ * trusted SQL identifier supplied by CAVE code, never user input.
+ */
+export const sql = (alias: string, maximum: Level = defaultMaximum): string =>
+  `COALESCE((SELECT MAX(CASE s.value ` +
+  `WHEN 'public' THEN 0 WHEN 'internal' THEN 1 WHEN 'confidential' THEN 2 WHEN 'restricted' THEN 3 ELSE 3 END) ` +
+  `FROM cave_tag s WHERE s.claim_id = ${alias}.id AND s.key = 'sensitivity'), ${rank(defaultLevel)}) <= ${rank(maximum)}`
+
+/** Most restrictive recognized label; malformed labels are `restricted`. */
+export const ofTags = (tags: readonly { key: string, value?: null | string }[]): Level => {
+  let effective: undefined | Level
+  for (const tag of tags) {
+    if (tag.key !== 'sensitivity') {
+      continue
+    }
+    const level = tag.value === undefined || tag.value === null ? 'restricted' : parse(tag.value) ?? 'restricted'
+    if (effective === undefined || rank(level) > rank(effective)) {
+      effective = level
+    }
+  }
+  return effective ?? defaultLevel
+}