@cavelang/store 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @cavelang/store
+
+CAVE persistence on the **Node.js builtin `node:sqlite`** — no native
+dependencies. Implements the spec §13 storage model: the exact §13.1/§13.2
+schema (`cave_claim`, `cave_context`, `cave_tag`, `cave_edge`, `cave_fts`
+FTS5), append-only belief series, and inverse-aware reads.
+
+```ts
+import { open } from '@cavelang/store'
+
+const store = open('knowledge.db')          // or open() for in-memory
+store.ingest(`
+packages/api PART-OF monorepo @ 50%
+monorepo CONTAINS packages/api @ 90%
+`)
+store.currentBeliefs()                       // one row — one fact, one key, conf 0.9
+store.reverse('packages/api')                // [{ verb: 'CONTAINS', rel: 'PART-OF', source: 'monorepo' }]
+store.exportText({ current: true })          // canonical CAVE text back out
+```
+
+## Semantics
+
+- **Append-only** (§9.1): `ingest` only inserts; every row carries a
+  monotonic UUIDv7 in `id` and `tx`, so `MAX(tx)` per `claim_key` is the
+  current belief. Each ingest call is one SQLite transaction.
+- **One row per fact** (§13.3): inverse writes are canonicalized before
+  keying (`@cavelang/canonical`), inverse *reads* are query-time views —
+  `forward()` uses the subject index, `reverse()` the object index with the
+  relation named via the registry's `inverseOf`. Nothing is materialized.
+- **Registry persistence is in-band**: `REVERSE` and `X IS verb` claims are
+  ordinary rows; on open the store replays them (in tx order) on top of the
+  initial registry, which defaults to the standard §5.5 prelude pairs. The
+  replay predicate mirrors the canonicalizer exactly — qualifier-condition
+  rows never declare, and `X IS verb` needs a verb-shaped subject — so the
+  registry after reopen equals the registry at close.
+- **Traversal defaults**: `forward`/`reverse`/`topicMembers`/`topicsOf`
+  read *current beliefs* and skip negated (`VERB NOT`) and retracted
+  (`@ 0%`) rows; opt back in with `{ negated: true, retracted: true }`.
+  Contradictions still coexist as rows (§9.4) — resolution belongs to the
+  query layer.
+
+## API
+
+| Method | Spec | Purpose |
+|---|---|---|
+| `ingest(text, {strict})` | §13.4 | parse → canonicalize → append; lenient by default |
+| `insertResult(result)` | | append a pre-canonicalized `@cavelang/canonical` result |
+| `currentBeliefs({minConf})` | §13.5 | latest row per key |
+| `currentBelief(key)` / `history(key)` | §9.1 | one fact's belief series |
+| `claimsAbout(entity)` | §13.5 | both directions, all rows |
+| `forward(entity)` / `reverse(entity)` | §13.3 | named traversal, inverse-aware |
+| `byTag(key, value?)` | §13.5 | flat (`value` omitted → `IS NULL`) or scoped |
+| `byContext(ctx)` | §13.5 | context filter |
+| `topicMembers(t)` / `topicsOf(e)` | §11.2 | topic layer over `CONTAINS` |
+| `search(q, {raw})` | §13.2 | FTS5; literal phrase by default |
+| `edgesOf(id)` | §13.2 | qualifier/grouping edges with roles |
+| `toClaim(row)` | | reconstruct the canonical claim + side tables |
+| `exportText({current})` | | emit canonical CAVE text |
+| `db` | | raw `DatabaseSync` — used by `@cavelang/query` |
+
+## Storage decisions
+
+- **Terms are stored formatted**: entities as plain text (so the spec's
+  `WHERE subject = 'auth/middleware'` queries work verbatim), literals with
+  their delimiters (`` `<=` ``, `"…"`) so they never collide with
+  same-spelled entities and reconstruct losslessly.
+- **`value_text` is the value as written** (including `~`, multiplier
+  letters and literal delimiters); `value_num`/`value_unit` hold the
+  normalized §13.4 forms. Same for `delta_*`.
+- **`id` doubles as `tx`** by default: a UUIDv7 is both unique and
+  time-ordered, and per-row tx ids keep same-document belief updates
+  ordered by line.
+- **`search()` phrase-quotes by default** — FTS5 would parse
+  `token-expiry` as a column filter; `{ raw: true }` opts into full MATCH
+  syntax.
+- **Current-only export remaps edge endpoints** to the current row of each
+  endpoint's claim key: a superseded qualified parent keeps its `WHEN`
+  attached to the surviving belief, and orphaned condition claims are never
+  promoted to top-level facts.
+
+## Tests
+
+```
+pnpm --filter @cavelang/store test
+```
+
+Covers the §9.1 belief series, §5.5 one-fact-two-names invariants
+(unified belief through either name, negation riding the row, no
+materialized inverses), every §13.5 query, the §11.2 topic reads, edge
+persistence, registry rebuild across reopen, transactional strict ingest
+and export round-trips.

package/dist/src/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@cavelang/store` — CAVE persistence on the Node.js builtin `node:sqlite`
+ * (spec §13).
+ *
+ * ```ts
+ * import { open } from '@cavelang/store'
+ *
+ * const store = open('knowledge.db')
+ * store.ingest('monorepo CONTAINS packages/api')
+ * store.reverse('packages/api')
+ * // → [{ verb: 'CONTAINS', rel: 'PART-OF', source: 'monorepo', … }]
+ * ```
+ */
+export * as Row from './row.ts';
+export * as Schema from './schema.ts';
+export { open } from './store.ts';
+export type { ForwardFact, IngestResult, ReverseFact, Store, TraverseOptions } from './store.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@cavelang/store` — CAVE persistence on the Node.js builtin `node:sqlite`
+ * (spec §13).
+ *
+ * ```ts
+ * import { open } from '@cavelang/store'
+ *
+ * const store = open('knowledge.db')
+ * store.ingest('monorepo CONTAINS packages/api')
+ * store.reverse('packages/api')
+ * // → [{ verb: 'CONTAINS', rel: 'PART-OF', source: 'monorepo', … }]
+ * ```
+ */
+export * as Row from "./row.js";
+export * as Schema from "./schema.js";
+export { open } from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/row.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Row mapping — canonical claims ↔ `cave_claim` rows.
+ *
+ * Terms are stored *formatted* (delimiters preserved): entities as plain
+ * text so §13.5 queries like `WHERE subject = 'auth/middleware'` work, code
+ * literals as `` `<=` `` and text literals as `"…"` so a literal never
+ * collides with a same-spelled entity. Values are stored as written
+ * (`value_text`, incl. `~`, multiplier letters and delimiters) alongside
+ * the normalized numeric value and unit (spec §13.4 step 9).
+ */
+import { Claim, Value } from '@cavelang/core';
+/** A `cave_claim` row. */
+export type Row = {
+    readonly id: string;
+    readonly tx: string;
+    readonly subject: string;
+    readonly verb: string;
+    readonly negated: number;
+    readonly object: null | string;
+    readonly attribute: null | string;
+    readonly value_text: null | string;
+    readonly value_num: null | number;
+    readonly value_unit: null | string;
+    readonly value_approx: number;
+    readonly delta_text: null | string;
+    readonly delta_num: null | number;
+    readonly delta_unit: null | string;
+    readonly sigma_level: null | number;
+    readonly conf: number;
+    readonly importance: number;
+    readonly comment: null | string;
+    readonly raw_line: string;
+    readonly claim_key: string;
+};
+export type t = Row;
+/** @returns term parsed back from its stored formatted text. */
+export declare const parseTerm: (text: string) => Claim.Term;
+/** @returns value parsed back from its stored as-written text. */
+export declare const parseValue: (text: string) => Value.t;
+/** Column values of a claim, in `cave_claim` insert order (id/tx excluded). */
+export declare const toColumns: (claim: Claim.t) => {
+    subject: string;
+    verb: string;
+    negated: number;
+    object: null | string;
+    attribute: null | string;
+    valueText: null | string;
+    valueNum: null | number;
+    valueUnit: null | string;
+    valueApprox: number;
+    deltaText: null | string;
+    deltaNum: null | number;
+    deltaUnit: null | string;
+    sigmaLevel: number;
+    conf: number;
+    importance: number;
+    comment: null | string;
+    rawLine: string;
+    claimKey: string;
+};
+/**
+ * @returns canonical claim reconstructed from a row plus its side tables.
+ * `sigmaLevel` collapses to `undefined` at the semantic default of 2.
+ */
+export declare const toClaim: (row: Row, contexts: readonly string[], tags: readonly {
+    key: string;
+    value: null | string;
+}[]) => Claim.t;
+//# sourceMappingURL=row.d.ts.map

package/dist/src/row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"row.d.ts","sourceRoot":"","sources":["../../src/row.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE7C,0BAA0B;AAC1B,MAAM,MAAM,GAAG,GAAG;IAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,CAAA;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,CAAC,GAAG,GAAG,CAAA;AAEnB,gEAAgE;AAChE,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,IAQ9C,CAAA;AAED,kEAAkE;AAClE,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,CAQ/C,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,SAAS,GAAI,OAAO,KAAK,CAAC,CAAC,KAAG;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,IAAI,GAAG,MAAM,CAAA;IACrB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAA;IACxB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAA;IACxB,QAAQ,EAAE,IAAI,GAAG,MAAM,CAAA;IACvB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAA;IACxB,QAAQ,EAAE,IAAI,GAAG,MAAM,CAAA;IACvB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,IAAI,GAAG,MAAM,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CA2BjB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,GAClB,KAAK,GAAG,EACR,UAAU,SAAS,MAAM,EAAE,EAC3B,MAAM,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,IAAI,GAAG,MAAM,CAAA;CAAE,EAAE,KACrD,KAAK,CAAC,CAkBL,CAAA"}

package/dist/src/row.js

@@ -0,0 +1,80 @@
+/**
+ * Row mapping — canonical claims ↔ `cave_claim` rows.
+ *
+ * Terms are stored *formatted* (delimiters preserved): entities as plain
+ * text so §13.5 queries like `WHERE subject = 'auth/middleware'` work, code
+ * literals as `` `<=` `` and text literals as `"…"` so a literal never
+ * collides with a same-spelled entity. Values are stored as written
+ * (`value_text`, incl. `~`, multiplier letters and delimiters) alongside
+ * the normalized numeric value and unit (spec §13.4 step 9).
+ */
+import { Claim, Value } from '@cavelang/core';
+/** @returns term parsed back from its stored formatted text. */
+export const parseTerm = (text) => {
+    if (text.length >= 2 && text.startsWith('`') && text.endsWith('`')) {
+        return Claim.code(text.slice(1, -1));
+    }
+    if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+        return Claim.text(text.slice(1, -1));
+    }
+    return Claim.entity(text);
+};
+/** @returns value parsed back from its stored as-written text. */
+export const parseValue = (text) => {
+    if (text.length >= 2 && text.startsWith('`') && text.endsWith('`')) {
+        return Value.ofCode(text.slice(1, -1));
+    }
+    if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+        return Value.ofText(text.slice(1, -1));
+    }
+    return Value.parse(text);
+};
+/** Column values of a claim, in `cave_claim` insert order (id/tx excluded). */
+export const toColumns = (claim) => {
+    const payload = claim.payload;
+    const value = payload.kind === 'attribute' ? payload.value :
+        payload.kind === 'metric' ? payload.value :
+            undefined;
+    return {
+        subject: Claim.formatTerm(claim.subject),
+        verb: claim.verb,
+        negated: claim.negated ? 1 : 0,
+        object: payload.kind === 'relation' ? Claim.formatTerm(payload.object) : null,
+        attribute: payload.kind === 'attribute' ? payload.attribute : null,
+        valueText: value === undefined ? null : Value.format(value),
+        valueNum: value?.num ?? null,
+        valueUnit: value?.unit ?? null,
+        valueApprox: value?.approx === true ? 1 : 0,
+        deltaText: claim.delta === undefined ? null : Value.format(claim.delta),
+        deltaNum: claim.delta?.num ?? null,
+        deltaUnit: claim.delta?.unit ?? null,
+        sigmaLevel: claim.sigmaLevel ?? 2,
+        conf: claim.conf,
+        importance: claim.importance ? 1 : 0,
+        comment: claim.comment ?? null,
+        rawLine: claim.raw,
+        claimKey: '' // filled by the store with Key.of on the canonical claim
+    };
+};
+/**
+ * @returns canonical claim reconstructed from a row plus its side tables.
+ * `sigmaLevel` collapses to `undefined` at the semantic default of 2.
+ */
+export const toClaim = (row, contexts, tags) => Claim.of({
+    subject: parseTerm(row.subject),
+    verb: row.verb,
+    negated: row.negated !== 0,
+    payload: row.object !== null ? Claim.relation(parseTerm(row.object)) :
+        row.attribute !== null && row.value_text !== null ? Claim.attribute(row.attribute, parseValue(row.value_text)) :
+            row.value_text !== null ? Claim.metric(parseValue(row.value_text)) :
+                Claim.none,
+    contexts,
+    tags: tags.map(tag => tag.value === null ? { key: tag.key } : { key: tag.key, value: tag.value }),
+    conf: row.conf,
+    importance: row.importance !== 0,
+    ...row.delta_text !== null ? { delta: parseValue(row.delta_text) } : {},
+    ...row.sigma_level !== null && row.sigma_level !== 2 ? { sigmaLevel: row.sigma_level } : {},
+    ...row.comment !== null ? { comment: row.comment } : {},
+    raw: row.raw_line
+});
+//# sourceMappingURL=row.js.map

package/dist/src/row.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"row.js","sourceRoot":"","sources":["../../src/row.ts"],"names":[],"mappings":"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"}

package/dist/src/schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Storage schema (spec §13.1, §13.2) — verbatim from the specification,
+ * with `IF NOT EXISTS` added so opening an existing database is idempotent.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export declare const ddl = "\nCREATE TABLE IF NOT EXISTS cave_claim (\n  id            TEXT PRIMARY KEY,      -- UUIDv7\n  tx            TEXT NOT NULL,         -- UUIDv7, lexicographic = transaction order\n\n  subject       TEXT NOT NULL,         -- canonical (primary) direction\n  verb          TEXT NOT NULL,         -- canonical (primary) verb\n  negated       INTEGER NOT NULL DEFAULT 0,\n\n  object        TEXT,                  -- relation object, entity, literal\n  attribute     TEXT,                  -- for HAS attr: value\n  value_text    TEXT,                  -- value as written (incl. ~, multiplier, delimiters)\n  value_num     REAL,                  -- parsed numeric value when possible\n  value_unit    TEXT,                  -- normalized unit string\n  value_approx  INTEGER NOT NULL DEFAULT 0,\n\n  delta_text    TEXT,\n  delta_num     REAL,\n  delta_unit    TEXT,\n  sigma_level   REAL DEFAULT 2.0,\n\n  conf          REAL NOT NULL DEFAULT 1.0,\n  importance    INTEGER NOT NULL DEFAULT 0,\n\n  comment       TEXT,\n  raw_line      TEXT NOT NULL,         -- exactly as written, incl. inverse form\n\n  claim_key     TEXT NOT NULL          -- normalized key; shared by forward/inverse readings\n);\n\nCREATE INDEX IF NOT EXISTS idx_cave_claim_key_tx ON cave_claim (claim_key, tx);\nCREATE INDEX IF NOT EXISTS idx_cave_subject   ON cave_claim (subject);\nCREATE INDEX IF NOT EXISTS idx_cave_verb      ON cave_claim (verb);\nCREATE INDEX IF NOT EXISTS idx_cave_object    ON cave_claim (object);\nCREATE INDEX IF NOT EXISTS idx_cave_attribute ON cave_claim (attribute);\nCREATE INDEX IF NOT EXISTS idx_cave_conf      ON cave_claim (conf);\n\nCREATE TABLE IF NOT EXISTS cave_context (\n  claim_id TEXT NOT NULL,\n  context  TEXT NOT NULL,\n  FOREIGN KEY (claim_id) REFERENCES cave_claim(id)\n);\nCREATE INDEX IF NOT EXISTS idx_cave_context ON cave_context (context);\n\nCREATE TABLE IF NOT EXISTS cave_tag (\n  claim_id TEXT NOT NULL,\n  key      TEXT NOT NULL,\n  value    TEXT,                       -- NULL for flat tags (spec \u00A713.2)\n  FOREIGN KEY (claim_id) REFERENCES cave_claim(id)\n);\nCREATE INDEX IF NOT EXISTS idx_cave_tag_key ON cave_tag (key, value);\n\nCREATE TABLE IF NOT EXISTS cave_edge (\n  parent_id TEXT NOT NULL,\n  role      TEXT NOT NULL,             -- WHEN, VIA, BECAUSE, QUALIFIES\n  child_id  TEXT NOT NULL,\n  FOREIGN KEY (parent_id) REFERENCES cave_claim(id),\n  FOREIGN KEY (child_id)  REFERENCES cave_claim(id)\n);\nCREATE INDEX IF NOT EXISTS idx_cave_edge_parent ON cave_edge (parent_id);\nCREATE INDEX IF NOT EXISTS idx_cave_edge_child  ON cave_edge (child_id);\nCREATE INDEX IF NOT EXISTS idx_cave_edge_role   ON cave_edge (role);\n\nCREATE VIRTUAL TABLE IF NOT EXISTS cave_fts USING fts5(\n  claim_id, subject, verb, object, attribute, value_text, comment, raw_line\n);\n";
+/** Creates all tables and indexes. */
+export declare const init: (db: DatabaseSync) => void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/src/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,eAAO,MAAM,GAAG,uvFAkEf,CAAA;AAED,sCAAsC;AACtC,eAAO,MAAM,IAAI,GAAI,IAAI,YAAY,KAAG,IAEvC,CAAA"}

package/dist/src/schema.js

@@ -0,0 +1,76 @@
+/**
+ * Storage schema (spec §13.1, §13.2) — verbatim from the specification,
+ * with `IF NOT EXISTS` added so opening an existing database is idempotent.
+ */
+export const ddl = `
+CREATE TABLE IF NOT EXISTS cave_claim (
+  id            TEXT PRIMARY KEY,      -- UUIDv7
+  tx            TEXT NOT NULL,         -- UUIDv7, lexicographic = transaction order
+
+  subject       TEXT NOT NULL,         -- canonical (primary) direction
+  verb          TEXT NOT NULL,         -- canonical (primary) verb
+  negated       INTEGER NOT NULL DEFAULT 0,
+
+  object        TEXT,                  -- relation object, entity, literal
+  attribute     TEXT,                  -- for HAS attr: value
+  value_text    TEXT,                  -- value as written (incl. ~, multiplier, delimiters)
+  value_num     REAL,                  -- parsed numeric value when possible
+  value_unit    TEXT,                  -- normalized unit string
+  value_approx  INTEGER NOT NULL DEFAULT 0,
+
+  delta_text    TEXT,
+  delta_num     REAL,
+  delta_unit    TEXT,
+  sigma_level   REAL DEFAULT 2.0,
+
+  conf          REAL NOT NULL DEFAULT 1.0,
+  importance    INTEGER NOT NULL DEFAULT 0,
+
+  comment       TEXT,
+  raw_line      TEXT NOT NULL,         -- exactly as written, incl. inverse form
+
+  claim_key     TEXT NOT NULL          -- normalized key; shared by forward/inverse readings
+);
+
+CREATE INDEX IF NOT EXISTS idx_cave_claim_key_tx ON cave_claim (claim_key, tx);
+CREATE INDEX IF NOT EXISTS idx_cave_subject   ON cave_claim (subject);
+CREATE INDEX IF NOT EXISTS idx_cave_verb      ON cave_claim (verb);
+CREATE INDEX IF NOT EXISTS idx_cave_object    ON cave_claim (object);
+CREATE INDEX IF NOT EXISTS idx_cave_attribute ON cave_claim (attribute);
+CREATE INDEX IF NOT EXISTS idx_cave_conf      ON cave_claim (conf);
+
+CREATE TABLE IF NOT EXISTS cave_context (
+  claim_id TEXT NOT NULL,
+  context  TEXT NOT NULL,
+  FOREIGN KEY (claim_id) REFERENCES cave_claim(id)
+);
+CREATE INDEX IF NOT EXISTS idx_cave_context ON cave_context (context);
+
+CREATE TABLE IF NOT EXISTS cave_tag (
+  claim_id TEXT NOT NULL,
+  key      TEXT NOT NULL,
+  value    TEXT,                       -- NULL for flat tags (spec §13.2)
+  FOREIGN KEY (claim_id) REFERENCES cave_claim(id)
+);
+CREATE INDEX IF NOT EXISTS idx_cave_tag_key ON cave_tag (key, value);
+
+CREATE TABLE IF NOT EXISTS cave_edge (
+  parent_id TEXT NOT NULL,
+  role      TEXT NOT NULL,             -- WHEN, VIA, BECAUSE, QUALIFIES
+  child_id  TEXT NOT NULL,
+  FOREIGN KEY (parent_id) REFERENCES cave_claim(id),
+  FOREIGN KEY (child_id)  REFERENCES cave_claim(id)
+);
+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(
+  claim_id, subject, verb, object, attribute, value_text, comment, raw_line
+);
+`;
+/** Creates all tables and indexes. */
+export const init = (db) => {
+    db.exec(ddl);
+};
+//# sourceMappingURL=schema.js.map

package/dist/src/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,CAAC,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkElB,CAAA;AAED,sCAAsC;AACtC,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EAAgB,EAAQ,EAAE;IAC7C,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACd,CAAC,CAAA"}

package/dist/src/store.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The CAVE store (spec §13) — append-only claim persistence on the Node.js
+ * builtin `node:sqlite`.
+ *
+ * - 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;
+ * - full-text search over subjects, objects, values, comments and raw
+ *   lines via FTS5.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { Claim } from '@cavelang/core';
+import * as Canonical from '@cavelang/canonical';
+import * as Row from './row.ts';
+export type IngestResult = {
+    /** ids of inserted claim rows, in document order. */
+    readonly ids: readonly string[];
+    readonly edges: number;
+    readonly problems: readonly Canonical.Problem[];
+};
+export type ForwardFact = {
+    /** Canonical (primary) verb. */
+    readonly verb: string;
+    readonly target: string;
+    readonly row: Row.t;
+};
+export type ReverseFact = {
+    /** Canonical (primary) verb of the stored row. */
+    readonly verb: string;
+    /** Inverse relation name, `undefined` when none is declared (spec §5.5). */
+    readonly rel?: string;
+    readonly source: string;
+    readonly row: Row.t;
+};
+export type TraverseOptions = {
+    /** Include `VERB NOT` rows (default `false`). */
+    readonly negated?: boolean;
+    /** Include rows whose current belief is `@ 0%` (default `false`). */
+    readonly retracted?: boolean;
+};
+export type Store = ReturnType<typeof open>;
+/**
+ * Opens (creating if necessary) a CAVE store. The registry defaults to the
+ * standard §5.5 prelude pairs and is extended by any declaration claims
+ * already stored; pass `Canonical.Registry.empty` for a declaration-free
+ * start.
+ */
+export declare const open: (path?: string, options?: {
+    registry?: Canonical.Registry.t;
+}) => {
+    /** Raw database handle — used by `@cavelang/query`; treat as read-only. */
+    db: DatabaseSync;
+    /** Current verb registry (input registry + stored + ingested declarations). */
+    registry: () => Canonical.Registry.t;
+    /**
+     * Parses, canonicalizes and appends CAVE text. Lenient by default —
+     * problems are returned, valid lines still land (spec §1.6); pass
+     * `strict` to throw instead.
+     */
+    ingest(text: string, options_?: {
+        strict?: boolean;
+    }): IngestResult;
+    /** Appends an already-canonicalized result. */
+    insertResult: (result: Canonical.Result) => IngestResult;
+    /** Latest row per claim key (spec §13.5), oldest first. */
+    currentBeliefs(options_?: {
+        minConf?: number;
+    }): Row.t[];
+    /** Current belief for one claim key, `undefined` if the fact is unknown. */
+    currentBelief(claimKey: string): undefined | Row.t;
+    /** Full belief series of one claim key, oldest first (spec §9.1). */
+    history(claimKey: string): Row.t[];
+    /** All rows about an entity, both directions, newest first (spec §13.5). */
+    claimsAbout(entity: string): Row.t[];
+    /** Forward reads: current relational facts with `entity` as subject (spec §13.3). */
+    forward(entity: string, options_?: TraverseOptions): ForwardFact[];
+    /**
+     * Inverse reads (spec §13.3): current relational facts
+     * with `entity` as object, relation named via the registry's inverse
+     * when one is declared.
+     */
+    reverse(entity: string, options_?: TraverseOptions): ReverseFact[];
+    /** Flat tag (`value` omitted → `value IS NULL`) or scoped tag rows (spec §13.5). */
+    byTag(key: string, value?: string): Row.t[];
+    /** Rows carrying a context (spec §13.5), newest first. */
+    byContext(context: string): Row.t[];
+    /** Members of a topic — forward `CONTAINS` traversal (spec §11.2). */
+    topicMembers(topic: string, options_?: TraverseOptions): string[];
+    /** Topics containing an entity — the inverse `CONTAINS` read (spec §11.2). */
+    topicsOf(entity: string, options_?: TraverseOptions): string[];
+    /**
+     * Full-text search, newest first. The query is treated as a literal
+     * phrase by default (safe for terms like `token-expiry`, which FTS5
+     * would otherwise parse as a column filter); pass `raw` to use full
+     * FTS5 MATCH syntax.
+     */
+    search(query: string, options_?: {
+        raw?: boolean;
+    }): Row.t[];
+    /** Qualifier/grouping edges of a claim row (spec §13.2). */
+    edgesOf(parentId: string): {
+        role: string;
+        child: Row.t;
+    }[];
+    /** Reconstructs the full canonical claim of a row (side tables included). */
+    toClaim: (row: Row.t) => Claim.t;
+    /**
+     * Emits the store as canonical CAVE text — all rows in transaction
+     * order, or only current beliefs with `current`.
+     *
+     * In current-only export an edge endpoint may be a superseded row;
+     * dropping such edges would silently un-condition current claims and
+     * promote orphaned WHEN conditions to top-level facts. Instead each
+     * endpoint resolves to the *current row of its claim key*, and the
+     * resulting edges are deduplicated.
+     */
+    exportText(options_?: {
+        current?: boolean;
+    }): string;
+    close(): void;
+};
+//# sourceMappingURL=store.d.ts.map

package/dist/src/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"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"}