@cavelang/store 0.27.14 → 0.29.1

package/src/backup.ts

@@ -0,0 +1,188 @@
+/** Exact SQLite snapshot backup, verification, and atomic restore. */
+
+import { createHash, randomBytes } from 'node:crypto'
+import {
+  closeSync, copyFileSync, existsSync, fsyncSync, linkSync, openSync, readSync,
+  realpathSync, renameSync, rmSync, statSync
+} from 'node:fs'
+import { basename, dirname, resolve } from 'node:path'
+import type { Store } from './store.ts'
+import { nodeSqliteAdapter } from './node-adapter.ts'
+import * as Schema from './schema.ts'
+
+export type Snapshot = {
+  readonly path: string
+  readonly bytes: number
+  readonly sha256: string
+  readonly schemaVersion: number
+  readonly rows: number
+  readonly maxTx: null | string
+}
+
+export type WriteOptions = {
+  /** Replace an existing destination atomically. Never permits source = destination. */
+  readonly force?: boolean
+}
+
+const temporaryPath = (destination: string): string => {
+  const target = resolve(destination)
+  return resolve(dirname(target), `.${basename(target)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`)
+}
+
+const hashFile = (path: string): string => {
+  const hash = createHash('sha256')
+  const fd = openSync(path, 'r')
+  const buffer = Buffer.allocUnsafe(1024 * 1024)
+  try {
+    for (;;) {
+      const size = readSync(fd, buffer, 0, buffer.length, null)
+      if (size === 0) break
+      hash.update(buffer.subarray(0, size))
+    }
+  } finally {
+    closeSync(fd)
+  }
+  return hash.digest('hex')
+}
+
+const syncFile = (path: string): void => {
+  const fd = openSync(path, 'r')
+  try {
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+const syncDirectory = (path: string): void => {
+  let fd: undefined | number
+  try {
+    fd = openSync(dirname(resolve(path)), 'r')
+    fsyncSync(fd)
+  } catch {
+    // Some platforms do not permit opening/fsyncing a directory. The fully
+    // written database itself is still synced before publication.
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+const publish = (temporary: string, destination: string, force: boolean): void => {
+  const target = resolve(destination)
+  if (force) {
+    renameSync(temporary, target)
+    syncDirectory(target)
+    return
+  }
+  // A hard link publishes the fully written inode atomically and fails if a
+  // racing process created the destination after the initial existence check.
+  linkSync(temporary, target)
+  rmSync(temporary)
+  syncDirectory(target)
+}
+
+const samePath = (left: string, right: string): boolean =>
+  existsSync(left) && existsSync(right) ?
+    realpathSync(left) === realpathSync(right) :
+    resolve(left) === resolve(right)
+
+/** Validate a standalone snapshot without migrating or mutating it. */
+export const verifyBackup = (path: string, expectedSha256?: string): Snapshot => {
+  const target = resolve(path)
+  if (!existsSync(target)) {
+    throw new Error(`CAVE backup: ${target}: no such file`)
+  }
+  const db = nodeSqliteAdapter.open(target, { readOnly: true })
+  let schemaVersion = 0
+  let rows = 0
+  let maxTx: null | string = null
+  try {
+    const integrity = db.prepare('PRAGMA integrity_check').all() as { integrity_check: string }[]
+    if (integrity.length !== 1 || integrity[0]?.integrity_check !== 'ok') {
+      throw new Error(`integrity_check failed: ${integrity.map(row => row.integrity_check).join('; ')}`)
+    }
+    const foreignKeys = db.prepare('PRAGMA foreign_key_check').all()
+    if (foreignKeys.length > 0) {
+      throw new Error(`foreign_key_check failed for ${foreignKeys.length} row(s)`)
+    }
+    schemaVersion = (db.prepare('PRAGMA user_version').get() as { user_version: number }).user_version
+    if (schemaVersion !== Schema.currentVersion) {
+      throw new Error(`schema version ${schemaVersion} is not the exact-backup format ${Schema.currentVersion}`)
+    }
+    Schema.validate(db, schemaVersion)
+    const summary = db.prepare('SELECT COUNT(*) AS rows, MAX(tx) AS max_tx FROM cave_claim').get() as
+      { rows: number, max_tx: null | string }
+    rows = summary.rows
+    maxTx = summary.max_tx
+  } finally {
+    db.close()
+  }
+  const sha256 = hashFile(target)
+  if (expectedSha256 !== undefined && sha256 !== expectedSha256.toLowerCase()) {
+    throw new Error(`CAVE backup: SHA-256 mismatch: expected ${expectedSha256.toLowerCase()}, got ${sha256}`)
+  }
+  return { path: target, bytes: statSync(target).size, sha256, schemaVersion, rows, maxTx }
+}
+
+/** Create and atomically publish a verified, point-in-time SQLite snapshot. */
+export const backup = (store: Store, destination: string, options: WriteOptions = {}): Snapshot => {
+  const target = resolve(destination)
+  const capability = store.adapter.capabilities.backup
+  if (capability === undefined) {
+    throw new Error(`CAVE backup: SQLite adapter ${JSON.stringify(store.adapter.name)} does not support exact snapshots`)
+  }
+  const source = capability.location(store.db)
+  if (source !== null && samePath(source, target)) {
+    throw new Error('CAVE backup: destination is the source database')
+  }
+  if (existsSync(target) && options.force !== true) {
+    throw new Error(`CAVE backup: ${target} already exists; pass force to replace it`)
+  }
+  if (capability.inTransaction(store.db)) {
+    throw new Error('CAVE backup: cannot snapshot inside an open transaction')
+  }
+  const temporary = temporaryPath(target)
+  try {
+    capability.write(store.db, temporary)
+    syncFile(temporary)
+    const checked = verifyBackup(temporary)
+    publish(temporary, target, options.force === true)
+    return { ...checked, path: target }
+  } catch (error) {
+    rmSync(temporary, { force: true })
+    throw error
+  }
+}
+
+/** Verify a snapshot, then atomically restore its exact bytes to a stopped destination. */
+export const restoreBackup = (
+  snapshotPath: string,
+  destination: string,
+  options: WriteOptions & { expectedSha256?: string } = {}
+): Snapshot => {
+  const source = resolve(snapshotPath)
+  const target = resolve(destination)
+  if (samePath(source, target)) {
+    throw new Error('CAVE restore: snapshot and destination are the same file')
+  }
+  if (existsSync(target) && options.force !== true) {
+    throw new Error(`CAVE restore: ${target} already exists; pass force to replace it`)
+  }
+  for (const suffix of ['-wal', '-shm', '-journal']) {
+    if (existsSync(`${target}${suffix}`)) {
+      throw new Error(`CAVE restore: refusing while ${target}${suffix} exists; stop all users and remove stale sidecars`)
+    }
+  }
+  const checked = verifyBackup(source, options.expectedSha256)
+  const temporary = temporaryPath(target)
+  try {
+    copyFileSync(source, temporary)
+    syncFile(temporary)
+    const copied = verifyBackup(temporary, checked.sha256)
+    publish(temporary, target, options.force === true)
+    return { ...copied, path: target }
+  } catch (error) {
+    rmSync(temporary, { force: true })
+    throw error
+  }
+}

package/src/index.ts

@@ -14,8 +14,16 @@
 
 export * as Resolve from './resolve.ts'
 export * as Row from './row.ts'
+export * as QuerySql from './query-sql.ts'
+export * as Record from './record.ts'
+export * as Provenance from './provenance.ts'
 export * as Schema from './schema.ts'
+export * as Sensitivity from './sensitivity.ts'
+export { backup, restoreBackup, verifyBackup } from './backup.ts'
+export type { Snapshot as BackupSnapshot, WriteOptions as BackupWriteOptions } from './backup.ts'
 export { open } from './open.ts'
 export type { Store } from './open.ts'
 export { defaultDbPath } from './store.ts'
 export type { AppendOptions, ForwardFact, IngestResult, ReverseFact, TraverseOptions } from './store.ts'
+export type { Dimension as ProvenanceDimension, Input as ProvenanceInput, t as ProvenanceRecord } from './provenance.ts'
+export type { Level as SensitivityLevel } from './sensitivity.ts'

package/src/node-adapter-entry.ts

@@ -0,0 +1,3 @@
+/** Node.js builtin implementation for explicit adapter composition. */
+
+export { nodeSqliteAdapter } from './node-adapter.ts'

package/src/node-adapter.ts

@@ -0,0 +1,23 @@
+/** Node.js builtin SQLite implementation of the CAVE adapter contract. */
+
+import { DatabaseSync } from 'node:sqlite'
+import type { Adapter, Database } from './adapter.ts'
+
+const asNodeDatabase = (db: Database): DatabaseSync => db as DatabaseSync
+
+export const nodeSqliteAdapter: Adapter = {
+  name: 'node:sqlite',
+  capabilities: {
+    transactions: { immediate: true, savepoints: true },
+    fullText: 'fts5',
+    loadExtension: (db, path) => asNodeDatabase(db).loadExtension(path),
+    backup: {
+      location: db => asNodeDatabase(db).location(),
+      inTransaction: db => asNodeDatabase(db).isTransaction,
+      write: (db, destination) => {
+        db.prepare('VACUUM INTO ?').run(destination)
+      },
+    },
+  },
+  open: (path, options = {}) => new DatabaseSync(path, options),
+}

package/src/open.ts

@@ -1,82 +1,9 @@
-import { Uuidv7, Verb } from '@cavelang/core'
-import * as Canonical from '@cavelang/canonical'
-import { open as openStore } from './store.ts'
-import type { Store as BaseStore } from './store.ts'
+import { nodeSqliteAdapter } from './node-adapter.ts'
+import { openWith } from './runtime.ts'
+import type { OpenOptions, Store } from './runtime.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 { Store } from './runtime.ts'
 
-type OpenOptions = {
-  readonly registry?: Canonical.Registry.t
-}
-
-type Declaration = {
-  readonly subject: string
-  readonly verb: string
-  readonly object: string
-}
-
-const upperTxBound = (text: string): string => {
-  const hasTime = text.includes('T')
-  const start = Date.parse(hasTime ? text : `${text}T00:00:00Z`)
-  if (Number.isNaN(start)) {
-    throw new Error(`CAVE: cannot parse as-of boundary ${JSON.stringify(text)}`)
-  }
-  const end = start + (hasTime ? 1_000 : 86_400_000)
-  return Uuidv7.at(end, 0, new Uint8Array(8))
-}
-
-const declarationsAsOf = (store: BaseStore, asOf: string): Declaration[] => {
-  const id = asOf.toLowerCase()
-  const [condition, boundary] = Uuidv7.is(id) ?
-    ['tx <= ?', id] as const :
-    ['tx < ?', upperTxBound(asOf)] as const
-  return store.db.prepare(`
-    SELECT subject, verb, object FROM cave_claim
-    WHERE ${condition}
-      AND negated = 0 AND object IS NOT NULL AND verb IN ('REVERSE', 'IS')
-      AND id NOT IN (SELECT child_id FROM cave_edge WHERE role IN ('WHEN', 'VIA', 'BECAUSE'))
-    ORDER BY tx
-  `).all(boundary) 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 === 'IS' && declaration.object === 'verb') {
-      registry = Canonical.Registry.declareVerb(registry, declaration.subject)
-    }
-  }
-  return registry
-}
-
-/**
- * Public store constructor. It retains the configured base registry so
- * transaction-time query views can rebuild vocabulary at the same boundary
- * as their claim rows.
- */
-export const open = (path: string = ':memory:', options: OpenOptions = {}): Store => {
-  const baseRegistry = options.registry ?? Canonical.standardRegistry
-  const store = openStore(path, options)
-  return Object.assign(store, {
-    registryAsOf: (asOf: string): Canonical.Registry.t =>
-      applyDeclarations(baseRegistry, declarationsAsOf(store, asOf))
-  })
-}
+/** Open a CAVE store with the Node.js builtin SQLite adapter. */
+export const open = (path: string = ':memory:', options: OpenOptions = {}): Store =>
+  openWith(nodeSqliteAdapter, path, options)

package/src/provenance.ts

@@ -0,0 +1,109 @@
+/** Explicit provenance dimensions derived alongside compact claim contexts. */
+
+import type { Database } from './adapter.ts'
+import { SourceSpan } from '@cavelang/core'
+
+export type Dimension = 'actor' | 'source' | 'run' | 'domain'
+
+export type t = {
+  readonly actors: readonly string[]
+  readonly sources: readonly string[]
+  readonly runs: readonly string[]
+  readonly domains: readonly string[]
+}
+
+export type Input = {
+  readonly actor?: string
+  readonly sources?: readonly string[]
+  readonly run?: string
+  readonly domains?: readonly string[]
+}
+
+export type Entry = {
+  readonly dimension: Dimension
+  readonly value: string
+}
+
+const runPrefixes = ['connect/', 'rule/', 'action/', 'automation/'] as const
+
+const actorSource = (source: string): boolean =>
+  source === 'cli' || source === 'sync' || source === 'ingest' || source.startsWith('ingest/') ||
+  source.startsWith('agent/') || source.startsWith('suggest/') ||
+  source.startsWith('cave-') || runPrefixes.some(prefix => source.startsWith(prefix))
+
+const contextEntries = (contexts: readonly string[], authoredSources: boolean): Entry[] => {
+  const result: Entry[] = []
+  for (const context of contexts) {
+    const reference = SourceSpan.parse(context)
+    if (reference !== undefined) {
+      if (authoredSources) {
+        result.push({ dimension: 'source', value: reference.source })
+        continue
+      }
+      if (runPrefixes.some(prefix => reference.source.startsWith(prefix))) {
+        result.push(
+          { dimension: 'actor' as const, value: reference.source },
+          { dimension: 'run' as const, value: reference.source }
+        )
+        continue
+      }
+      result.push(actorSource(reference.source) ?
+        { dimension: 'actor', value: reference.source } :
+        { dimension: 'source', value: reference.source })
+      continue
+    }
+    if (context.startsWith('scope:') && context.length > 'scope:'.length) {
+      result.push({ dimension: 'domain', value: context.slice('scope:'.length) })
+    }
+  }
+  return result
+}
+
+const clean = (values: readonly (undefined | string)[]): string[] =>
+  [...new Set(values.filter((value): value is string => value !== undefined && value !== ''))]
+
+export const entries = (contexts: readonly string[], input: Input = {}): Entry[] => {
+  // With an explicit actor, every src: in `contexts` was authored before
+  // compatibility stamping and therefore names evidence. During replay or
+  // migration, established actor/run prefixes are inferred conservatively.
+  const inferred = contextEntries(contexts, input.actor !== undefined)
+  return [
+    ...clean([input.actor, ...inferred.filter(entry => entry.dimension === 'actor').map(entry => entry.value)])
+      .map(value => ({ dimension: 'actor' as const, value })),
+    ...clean([...(input.sources ?? []), ...inferred.filter(entry => entry.dimension === 'source').map(entry => entry.value)])
+      .map(value => ({ dimension: 'source' as const, value })),
+    ...clean([input.run, ...inferred.filter(entry => entry.dimension === 'run').map(entry => entry.value)])
+      .map(value => ({ dimension: 'run' as const, value })),
+    ...clean([...(input.domains ?? []), ...inferred.filter(entry => entry.dimension === 'domain').map(entry => entry.value)])
+      .map(value => ({ dimension: 'domain' as const, value }))
+  ]
+}
+
+export const fromEntries = (values: readonly Entry[]): t => ({
+  actors: values.filter(entry => entry.dimension === 'actor').map(entry => entry.value),
+  sources: values.filter(entry => entry.dimension === 'source').map(entry => entry.value),
+  runs: values.filter(entry => entry.dimension === 'run').map(entry => entry.value),
+  domains: values.filter(entry => entry.dimension === 'domain').map(entry => entry.value)
+})
+
+/** Idempotently derives dimensions for rows written by older CAVE versions. */
+export const backfill = (db: Database): void => {
+  const missing = db.prepare(`
+    SELECT c.id, ctx.context FROM cave_claim c
+    LEFT JOIN cave_context ctx ON ctx.claim_id = c.id
+    WHERE NOT EXISTS (SELECT 1 FROM cave_provenance p WHERE p.claim_id = c.id)
+    ORDER BY c.tx, ctx.rowid
+  `).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]])
+  }
+  const insert = db.prepare(`
+    INSERT OR IGNORE INTO cave_provenance (claim_id, dimension, value) VALUES (?, ?, ?)
+  `)
+  for (const [id, contexts] of grouped) {
+    for (const entry of entries(contexts)) {
+      insert.run(id, entry.dimension, entry.value)
+    }
+  }
+}

package/src/query-sql.ts

@@ -0,0 +1,99 @@
+/**
+ * Composable SQL fragments for CAVE's shared read semantics.
+ *
+ * These functions return SQL only; callers own the outer SELECT, ordering,
+ * and additional predicates. Transaction boundaries contain only validated
+ * UUIDv7 text generated here, so their literal form remains safe inside
+ * nested CTEs where positional-parameter ordering would be fragile.
+ */
+
+import { Time, Uuidv7 } from '@cavelang/core'
+import * as Row from './row.ts'
+
+export type TransactionBounds = {
+  readonly lo: string
+  readonly hi: string
+}
+
+export type AsOfBoundary = {
+  readonly operator: '<' | '<='
+  readonly tx: string
+}
+
+/** UUIDv7 interval `[lo, hi)` for a UTC period or one-second timestamp. */
+export const transactionBounds = (text: string): TransactionBounds | undefined => {
+  const boundary = Time.parseBoundary(text)
+  if (boundary === undefined) return undefined
+  return {
+    lo: Uuidv7.at(boundary.start, 0, new Uint8Array(8)),
+    hi: Uuidv7.at(boundary.end, 0, new Uint8Array(8)),
+  }
+}
+
+/**
+ * Inclusive transaction boundary: an exact UUID includes that append; a
+ * period/timestamp includes its whole UTC period/second through an exclusive high
+ * bound. Returns `undefined` for text that is neither form.
+ */
+export const asOfBoundary = (text: string): AsOfBoundary | undefined => {
+  const id = text.toLowerCase()
+  if (Uuidv7.is(id)) return { operator: '<=', tx: id }
+  const bounds = transactionBounds(text)
+  return bounds === undefined ? undefined : { operator: '<', tx: bounds.hi }
+}
+
+/** A validated as-of predicate, optionally qualified with a table alias. */
+export const asOfCondition = (boundary: AsOfBoundary, column = 'tx'): string =>
+  `${column} ${boundary.operator} '${boundary.tx}'`
+
+/** Every claim, optionally bounded in transaction time. */
+export const claims = (boundary?: AsOfBoundary): string =>
+  boundary === undefined ? 'cave_claim' :
+    `(SELECT * FROM cave_claim WHERE ${asOfCondition(boundary)})`
+
+/**
+ * Latest transaction per claim key. `source` selects the eligible
+ * `cave_claim` rows (for example `claims(asOfBoundary(...))`); the outer row
+ * comes from the base table so the source fragment appears only once.
+ */
+export const current = (source: string = claims()): string => `
+SELECT c.* FROM cave_claim c
+JOIN (
+  SELECT claim_key, MAX(tx) AS max_tx
+  FROM ${source} GROUP BY claim_key
+) latest ON c.claim_key = latest.claim_key AND c.tx = latest.max_tx
+`
+
+/** Current, positive, entity-to-entity ALIAS edges in both directions. */
+export const aliasEdges = (currentSql: string = current()): string => `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')}
+)`
+
+/** Full transitive alias closure as ordered pairs. Requires `WITH RECURSIVE`. */
+export const aliasPairs = (currentSql: string = current()): string => `${aliasEdges(currentSql)},
+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
+)`
+
+/** Seeded alias closure. Its first SELECT consumes one positional parameter. */
+export const aliasSeed = (): string => `alias_closure(name) AS (
+  SELECT ?
+  UNION
+  SELECT e.b FROM alias_closure s JOIN alias_edge e ON e.a = s.name
+)`
+
+/** Ready-to-prefix seeded closure; the caller supplies the seed parameter. */
+export const aliasClosure = (currentSql: string = current()): string =>
+  `WITH RECURSIVE ${aliasEdges(currentSql)}, ${aliasSeed()}\n`
+
+/** SQL equality widened through an `alias_pair` CTE already in scope. */
+export const aliasSame = (left: string, right: string): string =>
+  `(${left} = ${right} OR EXISTS (SELECT 1 FROM alias_pair p WHERE p.a = ${left} AND p.b = ${right}))`

package/src/record.ts

@@ -0,0 +1,82 @@
+/** Versioned, storage-independent claim and transaction records. */
+
+import { Key, Uuidv7 } from '@cavelang/core'
+import type { Claim } from '@cavelang/core'
+import { emitClaim } from '@cavelang/canonical'
+import type * as Provenance from './provenance.ts'
+import type * as Row from './row.ts'
+
+export const format = 'cave.claim' as const
+export const version = 1 as const
+
+/**
+ * Public JSON representation. It deliberately contains semantic domain
+ * values rather than `cave_claim` column names, so storage migrations do not
+ * silently revise serialized APIs.
+ */
+export type V1 = {
+  readonly format: typeof format
+  readonly version: typeof version
+  readonly id: string
+  readonly tx: string
+  readonly key: string
+  /** Canonical primary-direction CAVE text. */
+  readonly canonical: string
+  /** Semantic claim; `claim.raw` retains the authored spelling. */
+  readonly claim: Claim.t
+  readonly provenance: Provenance.t
+}
+
+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 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')
+
+/** 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
+  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'])) {
+    throw new Error(`CAVE record: malformed ${format}/v${version}`)
+  }
+  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`)
+  }
+  if (Key.of(decoded.claim) !== decoded.key || emitClaim(decoded.claim) !== decoded.canonical) {
+    throw new Error(`CAVE record: malformed ${format}/v${version} semantic identity`)
+  }
+  return decoded
+}
+
+export const encode = (record: t, space?: number): string =>
+  JSON.stringify(record, undefined, space)