Skip to content

Commit c7bab75

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
feat(verisim-core): productise VerisimCore as shippable Julia package
Promoted from verisim-modular-experiment/impl/ after Path B confirmation (145 assertions). Proper Julia package structure with module hierarchy: VerisimCore (umbrella, re-exports) ├── Core — Store, enrich!, attest, verify_attest ├── Crypto — Ed25519 via libsodium ├── Metrics — pairwise drift functions ├── Federation — Manager, DriftWeights, aggregate_drift ├── VectorPeers — example Federable peer (Vector) ├── DocumentPeers — example Federable peer (Document) ├── VCLQuery — PROOF clause AST ├── VCLProver — evaluator └── VCLParser — string parser for VCL PROOF subset 55 test assertions in test/runtests.jl cover: core lifecycle + enrichment atomicity, Ed25519 round-trip, attestation + tamper detection, federation parity (single + two peers), register_peer! runtime validation, Clause 1 renormalisation, VCL INTEGRITY/CONSISTENCY/FRESHNESS + parser + errors, multi-peer non-interference. Package loads as `using VerisimCore` with 47 top-level exports. Zero runtime dependency on main verisimdb — VerisimCore is standalone. Relationship to siblings: - verisimdb/ — canonical 8-shape octad (paved-road) - verisim-modular-experiment/ — research prototype (this was promoted from) - KRLAdapter.jl — demonstrated client (Phase 4 dogfood) Production readiness (deferred): persistence layer, network transport, Zig FFI port per hyperpolymath standard. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent b744433 commit c7bab75

19 files changed

Lines changed: 2245 additions & 0 deletions

‎verisim-core/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Manifest.toml
2+
*.cov
3+
deps/build.log

‎verisim-core/.machine_readable/6a2/ECOSYSTEM.a2ml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
;; SPDX-License-Identifier: PMPL-1.0-or-later
2+
(ecosystem
3+
(version "1.0.0")
4+
(last-updated "2026-04-05")
5+
6+
(name "VerisimCore.jl")
7+
(type "julia-package")
8+
(purpose "Shippable slim identity-core of VeriSimDB for clients that need
9+
identity + audit trail without the full 8-shape octad.")
10+
11+
(position-in-ecosystem
12+
(parent "nextgen-databases")
13+
(siblings
14+
(sibling "verisimdb"
15+
(relationship "reference-implementation")
16+
(description "Canonical paved-road 8-shape octad. VerisimCore is a slim
17+
escape hatch; clients choose one or the other."))
18+
(sibling "verisim-modular-experiment"
19+
(relationship "parent-experiment")
20+
(description "Research prototype this package was promoted from.
21+
Contains Idris2 ABI, 145-assertion proof, Phase 5 findings."))
22+
(sibling "typeql-experimental"
23+
(relationship "sibling-experiment"))))
24+
25+
(consumers
26+
(consumer "KRLAdapter.jl"
27+
(relationship "demonstrated-client")
28+
(description "Knot-theory stack. Phase 4 dogfood confirmed that TangleIR
29+
lifecycle is satisfied by Core alone — no Federable peers needed.")
30+
(location "/var/mnt/eclipse/repos/KRLAdapter.jl")))
31+
32+
(standards-followed
33+
(standard "pmpl-1.0-license")
34+
(standard "a2ml-machine-readable")
35+
(standard "julia-package-layout" (description "src/ + test/runtests.jl + Project.toml"))))

‎verisim-core/.machine_readable/6a2/STATE.a2ml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
;; SPDX-License-Identifier: PMPL-1.0-or-later
2+
(state
3+
(metadata
4+
(version "0.1.0")
5+
(last-updated "2026-04-05")
6+
(status active))
7+
8+
(project-context
9+
(name "VerisimCore.jl")
10+
(purpose "Shippable Julia package: slim identity-core of VeriSimDB (3 shapes
11+
+ federation contract for optional peers).")
12+
(type "julia-package")
13+
(promoted-from "nextgen-databases/verisim-modular-experiment/impl/")
14+
(completion-percentage 85))
15+
16+
(components
17+
(component "core-module"
18+
(status complete)
19+
(description "src/Core.jl — Store, enrich!, attest, verify_attest, Ed25519-signed provenance.")
20+
(completion 100))
21+
(component "crypto-module"
22+
(status complete)
23+
(description "src/Crypto.jl — Ed25519 via libsodium (Sodium.jl).")
24+
(completion 100))
25+
(component "federation-module"
26+
(status complete)
27+
(description "src/Federation.jl — Manager, DriftWeights, renormalise, aggregate_drift.")
28+
(completion 100))
29+
(component "peer-modules"
30+
(status complete)
31+
(description "src/peers/{VectorPeer,DocumentPeer}.jl — example Federable peers.")
32+
(completion 100))
33+
(component "vcl-subset"
34+
(status complete)
35+
(description "src/vcl/{Query,Prover,Parser}.jl — PROOF INTEGRITY/CONSISTENCY/FRESHNESS.")
36+
(completion 100))
37+
(component "test-suite"
38+
(status complete)
39+
(description "test/runtests.jl — 55 assertions covering all public surfaces.")
40+
(completion 100))
41+
(component "production-readiness"
42+
(status pending)
43+
(description "Persistence layer, network transport, Zig FFI port.")
44+
(completion 0)))
45+
46+
(verified-results
47+
(result "package-tests"
48+
(command "julia --project=. -e 'using Pkg; Pkg.test(\"VerisimCore\")'")
49+
(status pass)
50+
(assertions 55)))
51+
52+
(critical-next-actions
53+
(action "Register to Julia General registry (if publishing publicly)")
54+
(action "Add persistence layer (file-backed or redb-backed)")
55+
(action "Add network transport for federation peers (mTLS)")
56+
(action "Zig FFI port per hyperpolymath standard"))
57+
58+
(ecosystem-position
59+
(parent-monorepo "nextgen-databases")
60+
(siblings "verisimdb" "verisim-modular-experiment" "typeql-experimental")))

‎verisim-core/0-AI-MANIFEST.a2ml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# STOP - CRITICAL READING REQUIRED
3+
4+
**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**
5+
6+
## WHAT IS THIS?
7+
8+
**VerisimCore.jl** — a shippable Julia package providing the slim
9+
identity-core of VeriSimDB. Promoted from the research prototype in
10+
`verisim-modular-experiment/impl/` after Path B was runtime-confirmed
11+
(145 assertions). This is NOT the full verisimdb octad — it's the
12+
minimum substrate (Core = {Semantic, Temporal, Provenance}) plus a
13+
federation contract for optional peers.
14+
15+
## WHEN TO ADOPT
16+
17+
Clients that need identity + audit trail only, without
18+
similarity/full-text/geospatial queries. Example satisfied client:
19+
KRLAdapter.jl (knot-theory stack).
20+
21+
For comprehensive 8-shape multimodal use, use main `verisimdb/` instead.
22+
23+
## STRUCTURE
24+
25+
- `src/VerisimCore.jl` — umbrella module; re-exports from submodules
26+
- `src/Core.jl` — identity-core primitives (Store, enrich!, attest)
27+
- `src/Crypto.jl` — Ed25519 (libsodium via Sodium.jl)
28+
- `src/Federation.jl` — Manager, DriftWeights, aggregate_drift
29+
- `src/drift/Metrics.jl` — pairwise drift functions
30+
- `src/peers/{VectorPeer,DocumentPeer}.jl` — example Federable peers
31+
- `src/vcl/{Query,Prover,Parser}.jl` — VCL PROOF subset
32+
- `test/runtests.jl` — 55 assertions
33+
34+
## CRITICAL INVARIANTS
35+
36+
1. Core shapes (Semantic, Temporal, Provenance) CANNOT be federated.
37+
`register_peer!` rejects them at runtime.
38+
2. `enrich!` writes to both Temporal AND Provenance atomically
39+
(def:enrichment from verisimdb's TeX data model).
40+
3. All signatures are real Ed25519 via libsodium. No placeholder crypto.
41+
4. All source files carry `SPDX-License-Identifier: PMPL-1.0-or-later`.
42+
43+
## HOW TO RUN TESTS
44+
45+
```bash
46+
julia --project=. -e 'using Pkg; Pkg.test("VerisimCore")'
47+
```
48+
49+
## RELATIONSHIP TO SIBLINGS
50+
51+
- `../verisimdb/` — canonical paved-road octad (8 shapes). Main.
52+
- `../verisim-modular-experiment/` — research prototype this was
53+
promoted from. Contains the Idris2 ABI (typechecks clean), the
54+
145-assertion proof suite, 6 test files, 5 phases, decision gates,
55+
and the Phase 5 findings document.
56+
- `../typeql-experimental/` — sibling experimental package.
57+
58+
## LIFECYCLE HOOKS
59+
60+
### on-enter
61+
62+
1. Read this manifest first.
63+
2. Read `.machine_readable/6a2/STATE.a2ml` for current status.
64+
3. Read `README.adoc` for quick start.
65+
4. If digging deep: read the experiment's `docs/FINDINGS.adoc`.
66+
67+
### on-exit
68+
69+
1. Update `.machine_readable/6a2/STATE.a2ml` if state changed.
70+
2. Run `Pkg.test("VerisimCore")` before committing code changes.

‎verisim-core/EXPLAINME.adoc‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= EXPLAINME — VerisimCore.jl
3+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
:toc: left
5+
6+
== What is this?
7+
8+
A Julia package implementing the slim identity-core of VeriSimDB:
9+
3 required shapes (Semantic, Temporal, Provenance) plus a federation
10+
contract for optional peers. Think of it as "VeriSimDB Lite" — the
11+
minimum substrate that preserves VCL's consonance guarantees.
12+
13+
== Why does it exist?
14+
15+
Main `verisimdb/` is a comprehensive 8-shape multimodal database.
16+
Many clients don't need all 8 shapes — they need identity + audit
17+
trail only. VerisimCore lets them have that without integrating the
18+
full octad.
19+
20+
This was proven by the sibling research experiment
21+
`verisim-modular-experiment/`:
22+
23+
* The octad decomposes into Core (3) + Federable (4) + Conditional (1).
24+
* VCL's aggregate-drift computation over the Core gives results
25+
numerically identical to the monolithic full-octad computation on
26+
the same data (145 test assertions).
27+
* A real client (KRLAdapter.jl) is satisfied by Core alone.
28+
29+
== How does it fit in the ecosystem?
30+
31+
[cols="1,3",options="header"]
32+
|===
33+
|Sibling |Relationship
34+
35+
|main `verisimdb/` |Canonical paved-road octad. VerisimCore is a slim escape hatch, not a replacement.
36+
|`verisim-modular-experiment/` |Research prototype this package was promoted from. Contains the Idris2 ABI, 145-assertion proof, and Phase 5 findings.
37+
|`typeql-experimental/` |Sibling experimental package in `nextgen-databases` exploring VCL type-theoretic extensions.
38+
|`KRLAdapter.jl` |First demonstrated client — knot-theory stack integration verified in `verisim-modular-experiment/examples/krladapter_integration.jl`.
39+
|===
40+
41+
== What do I do with it?
42+
43+
1. **Read `README.adoc`** for quick start + rule of thumb.
44+
2. **Look at `test/runtests.jl`** for working code exercising every
45+
public surface.
46+
3. **Read the experiment's `docs/FINDINGS.adoc`** if you want the full
47+
research record — why these 3 shapes, why this 5-clause contract,
48+
what the decision gates proved.
49+
4. **Adopt VerisimCore** if your workload matches identity + audit
50+
trail (no similarity/full-text/geospatial). If you need more, adopt
51+
one Federable peer at a time.
52+
53+
== Module map
54+
55+
[cols="2,3",options="header"]
56+
|===
57+
|Module |Responsibility
58+
59+
|`VerisimCore.Core` |Store, enrich!, attest, verify_attest. The identity-core primitives.
60+
|`VerisimCore.Crypto` |Ed25519 wrapper (libsodium via Sodium.jl).
61+
|`VerisimCore.Metrics` |Pairwise drift functions (d_SV, d_VD, d_SD).
62+
|`VerisimCore.Federation` |DriftWeights, Manager, renormalise, aggregate_drift, PeerAttestation.
63+
|`VerisimCore.VectorPeers` |Example Federable peer (Vector shape).
64+
|`VerisimCore.DocumentPeers`|Example Federable peer (Document shape).
65+
|`VerisimCore.VCLQuery` |PROOF clause AST.
66+
|`VerisimCore.VCLProver` |Evaluator routing to Core + Federation.
67+
|`VerisimCore.VCLParser` |String parser for a minimum VCL subset.
68+
|===
69+
70+
All public identifiers are re-exported at the top level, so
71+
`using VerisimCore` makes them available directly.
72+
73+
== What's NOT in here
74+
75+
* No full-text index (Document peer stores raw bytes; no search).
76+
* No HNSW / similarity index (Vector peer stores raw Float32 arrays).
77+
* No persistence (store is in-memory Dict).
78+
* No network transport (all peers are in-process Julia structs).
79+
* No Zig FFI (pure Julia).
80+
* No normalizer regeneration strategies (read-only drift measurement).
81+
82+
These are main `verisimdb/`'s job. VerisimCore intentionally stays
83+
slim.
84+
85+
== License
86+
87+
PMPL-1.0-or-later. See `LICENSE`.

‎verisim-core/LICENSE‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Palimpsest License, Version 1.0-or-later (PMPL-1.0-or-later)
2+
3+
Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
<j.d.a.jewell@open.ac.uk>
5+
6+
This file points to the parent monorepo's license. For the full
7+
PMPL-1.0-or-later text, see `../LICENSE` in the nextgen-databases
8+
monorepo.
9+
10+
SPDX-License-Identifier: PMPL-1.0-or-later
11+
12+
All source files in this directory carry an SPDX header declaring
13+
PMPL-1.0-or-later as their license. Third-party dependencies retain
14+
their original licenses (see Project.toml).

‎verisim-core/Project.toml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name = "VerisimCore"
2+
uuid = "c8f2e5a1-7b4d-4e6a-9c03-1f8d2a7e6b40"
3+
authors = ["Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"]
4+
version = "0.1.0"
5+
6+
[deps]
7+
Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
8+
SHA = "ea8e919c-243c-51af-8825-aaa63cd721ce"
9+
Sodium = "4f5b5e99-b0ad-42cd-b47a-334e172ec8bd"
10+
11+
[compat]
12+
julia = "1.10"
13+
14+
[extras]
15+
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
16+
17+
[targets]
18+
test = ["Test"]

0 commit comments

Comments
 (0)