kweb-db-core 0.2.0

Storage-only SQLite and artifact library for a provenance-backed knowledge web
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# Kweb DB Core Agent Integration Reference

`kweb-db-core` is a synchronous, storage-only Rust library for a provenance-backed
knowledge web. It owns one SQLite database and an immutable artifact directory.
The integrating application owns concurrency, authentication, authorization,
HTTP, graph policy, and multi-call orchestration.

The Cargo package name is `kweb-db-core`; its Rust crate path is
`kweb_db_core`.

```rust
use kweb_db_core::{IdempotencyId, Kmap, NewProvenance};

let mut kweb = Kmap::open("kweb.sqlite3")?;
let provenance_id = kweb.create_provenance(
    IdempotencyId::random(),
    NewProvenance {
        data: "Imported source material".into(),
        source: "example".into(),
        source_created_at: "2026-07-18T00:00:00Z".into(),
    },
)?;
# Ok::<(), kweb_db_core::Error>(())
```

`Kmap::open(path)` creates or opens the database and derives a sibling artifact
directory. For example, `kweb.sqlite3` uses `kweb-provenance-artifacts/`.
`Kmap::open_with_artifacts` accepts an explicit artifact location.

Every mutation requires a caller-retained `IdempotencyId`. Replaying the same
identifier with the same operation and normalized input succeeds without
another mutation. Reusing it with different input returns `Error::Conflict`.

Create immutable source records with `create_provenance` or
`create_provenance_with_storage`. The latter accepts attached byte artifacts
and an explicit filename for large provenance data. Use the returned
`ProvenanceId` when calling `create_node` or `update_node`.

Node creates and updates accept complete owner, text, attribution, provenance,
fixed-connection, and recent-connection state. Connections are ordered stored
identifiers; the library assigns them no graph semantics. `get_node` returns
current state, `get_provenance` returns immutable source data and artifact
metadata, and `get_node_history` returns provenance identifiers newest first.
`stats` returns typed aggregate statistics for current node text.

The caller must serialize access to a `Kmap`. One library call is internally
atomic where documented, but multiple calls cannot share a transaction. Keep
idempotency receipts for as long as retries can arrive. Artifact bytes may be
written before their SQLite metadata transaction, so interrupted operations can
leave harmless unreferenced immutable files.

See `Specification.md` for validation limits, persistence details, artifact
naming, schema guarantees, and deliberate limitations.