Skip to content

Commit 0c18c24

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
feat: update VeriSimDB ReScript client connectors and manifest
Expand ReScript client APIs for drift, federation, hexad, provenance, search, and VQL modules. Add Deno build config and gitignore for build output. Update AI manifest and CLAUDE.md with project context. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 73069ff commit 0c18c24

13 files changed

Lines changed: 274 additions & 41 deletions

File tree

‎verisimdb/.claude/CLAUDE.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,37 @@
11
# CLAUDE.md - VeriSimDB AI Assistant Instructions
22

3+
## CRITICAL: Instance Policy (Read First)
4+
5+
**This repository is SOURCE CODE and EXAMPLE DATA. It is NOT a database instance.**
6+
7+
If you are integrating VeriSimDB into another project (IDApTIK, Burble, etc.):
8+
9+
1. **NEVER** store application data in this repo's VeriSimDB instance
10+
2. **NEVER** point application code at `localhost:8080` expecting a shared server
11+
3. **ALWAYS** create a dedicated VeriSimDB instance in the consuming project
12+
4. **ALWAYS** use a unique port per project (not 8080)
13+
5. **ALWAYS** copy the client SDK (`connectors/clients/<lang>/`) into your project
14+
15+
**Correct pattern:**
16+
```
17+
your-project/
18+
├── containers/
19+
│ └── verisimdb.Containerfile ← YOUR instance
20+
├── src/verisimdb/
21+
│ └── VeriSimClient.res ← Copied SDK files
22+
└── podman-compose.yml ← YOUR port + volume
23+
```
24+
25+
**Port assignments:**
26+
| Project | Port | Volume |
27+
|---------|------|--------|
28+
| VeriSimDB dev/test | 8080 | (in-memory, ephemeral) |
29+
| IDApTIK | 8090 | idaptik-verisimdb-data |
30+
| Burble | 8091 | burble-verisimdb-data |
31+
| Hypatia | 8092 | hypatia-verisimdb-data |
32+
33+
The `examples/` directory contains example/demo data only. Never treat it as live storage.
34+
335
## Project Overview
436

537
VeriSimDB (Veridical Simulacrum Database) is a cross-system entity consistency engine with drift detection, self-normalisation, and formally verified queries. Each entity exists simultaneously across 8 modalities — the octad (Graph, Vector, Tensor, Semantic, Document, Temporal, Provenance, Spatial) — with drift detection and automatic consistency maintenance. Operates as standalone database OR heterogeneous federation coordinator over existing databases.

‎verisimdb/0-AI-MANIFEST.a2ml‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,43 @@
8080
(rule "Container runtime is Podman — never Docker")
8181
(rule "VQL is the query language — never raw SQL")
8282
(rule "Octad entities must maintain 8-modality consistency")
83-
(rule "Drift thresholds gate all automatic normalization"))
83+
(rule "Drift thresholds gate all automatic normalization")
84+
85+
;; INSTANCE POLICY — MOST IMPORTANT RULE FOR CONSUMERS
86+
(rule "NEVER store application data in this repository's VeriSimDB instance")
87+
(rule "NEVER point application code at localhost:8080 expecting a shared VeriSimDB")
88+
(rule "Each consuming project MUST run its OWN dedicated VeriSimDB instance")
89+
(rule "Each instance MUST have its own port, data directory, and container volume")
90+
(rule "Copy the client SDK files into your project — do NOT import from this repo")
91+
(rule "This repo contains ONLY source code and EXAMPLE data — not live application data"))
92+
93+
;; ═══════════════════════════════════════════════════════════════════
94+
;; DEPLOYMENT MODEL — READ THIS BEFORE INTEGRATING
95+
;; ═══════════════════════════════════════════════════════════════════
96+
;;
97+
;; This repository is the VeriSimDB SOURCE CODE and EXAMPLE DATA.
98+
;; It is NOT a shared database instance. It is NOT a data store.
99+
;;
100+
;; If your project needs VeriSimDB:
101+
;; 1. Copy the client SDK (connectors/clients/<lang>/) into your project
102+
;; 2. Add a VeriSimDB Containerfile to YOUR project's container stack
103+
;; 3. Choose a UNIQUE port for your instance (not 8080)
104+
;; 4. Create a DEDICATED data volume for your instance
105+
;; 5. Configure YOUR client to point at YOUR instance
106+
;;
107+
;; Example per-project instance setup:
108+
;; IDApTIK (game saves) → port 8090, volume idaptik-verisimdb-data
109+
;; Burble (voice audit) → port 8091, volume burble-verisimdb-data
110+
;; Hypatia (scan results) → port 8092, volume hypatia-verisimdb-data
111+
;;
112+
;; The examples/ directory contains EXAMPLE data for testing and demos.
113+
;; Do NOT treat it as a database. Do NOT store application data here.
114+
;; ═══════════════════════════════════════════════════════════════════
115+
(deployment-model
116+
(type "source-code-and-examples-only")
117+
(not "shared-database-instance")
118+
(not "central-data-store")
119+
(consumer-pattern "copy-sdk-run-own-instance"))
84120

85121
(container-ecosystem
86122
(selur "container/compose.toml — deployment orchestration")

‎verisimdb/connectors/clients/rescript/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# ReScript build output
2+
/lib/
3+
node_modules/

‎verisimdb/connectors/clients/rescript/deno.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"name": "@hyperpolymath/verisimdb-client",
3+
"version": "0.1.1",
4+
"license": "MPL-2.0",
5+
"description": "ReScript client SDK for VeriSimDB — the 8-modality database with drift detection and self-normalisation. CRUD, search, drift scoring, provenance tracking, VQL queries, and federation. Zero npm dependencies.",
6+
"exports": {
7+
".": "./src/VeriSimClient.res.mjs",
8+
"./types": "./src/VeriSimTypes.res.mjs",
9+
"./hexad": "./src/VeriSimHexad.res.mjs",
10+
"./search": "./src/VeriSimSearch.res.mjs",
11+
"./drift": "./src/VeriSimDrift.res.mjs",
12+
"./provenance": "./src/VeriSimProvenance.res.mjs",
13+
"./vql": "./src/VeriSimVql.res.mjs",
14+
"./federation": "./src/VeriSimFederation.res.mjs",
15+
"./error": "./src/VeriSimError.res.mjs"
16+
},
17+
"publish": {
18+
"include": [
19+
"src/*.res.mjs",
20+
"src/*.res",
21+
"LICENSE",
22+
"README.adoc",
23+
"deno.json"
24+
],
25+
"exclude": [
26+
"!src/*.res.mjs"
27+
]
28+
}
29+
}

‎verisimdb/connectors/clients/rescript/rescript.json‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
{
22
"name": "verisimdb-client",
3-
"version": "0.1.0",
43
"sources": [{ "dir": "src", "subdirs": true }],
5-
"package-specs": [{ "module": "es6", "in-source": true }],
4+
"package-specs": [{ "module": "esmodule", "in-source": true }],
65
"suffix": ".res.mjs",
7-
"bs-dependencies": []
6+
"dependencies": []
87
}

‎verisimdb/connectors/clients/rescript/src/VeriSimClient.res‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@
2424
/** Read the response body as a UTF-8 string. */
2525
@send external textBody: VeriSimTypes.fetchResponse => promise<string> = "text"
2626

27+
/** External binding to btoa for Base64 encoding (available in browser and Deno). */
28+
@val external btoa: string => string = "btoa"
29+
2730
// --------------------------------------------------------------------------
2831
// Authentication types
2932
// --------------------------------------------------------------------------
@@ -84,9 +87,6 @@ let authHeaders = (client: t): Dict.t<string> => {
8487
headers
8588
}
8689

87-
/** External binding to btoa for Base64 encoding (available in browser and Deno). */
88-
@val external btoa: string => string = "btoa"
89-
9090
/** Perform a GET request to the given path on the client's base URL. */
9191
let doGet = async (client: t, path: string): VeriSimTypes.fetchResponse => {
9292
let headers = authHeaders(client)

‎verisimdb/connectors/clients/rescript/src/VeriSimDrift.res‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@
88
// query drift scores, check drift status classifications, and trigger
99
// re-normalisation of drifted hexads.
1010

11+
/// JSON boundary cast — used at the HTTP response boundary where we trust
12+
/// the VeriSimDB server's JSON schema matches our ReScript types.
13+
/// This replaces Obj.magic with an explicit, auditable cast point.
14+
external fromJson: JSON.t => 'a = "%identity"
15+
external toJson: 'a => JSON.t = "%identity"
16+
1117
/** Retrieve the current drift score for a specific hexad.
1218
*
1319
* The drift score is a floating-point value between 0.0 (no drift) and
@@ -25,7 +31,7 @@ let getScore = async (
2531
let resp = await VeriSimClient.doGet(client, `/api/v1/hexads/${hexadId}/drift`)
2632
if resp.ok {
2733
let json = await VeriSimClient.jsonBody(resp)
28-
Ok(json->Obj.magic)
34+
Ok(json->fromJson)
2935
} else {
3036
Error(VeriSimError.fromStatus(resp.status))
3137
}
@@ -51,7 +57,7 @@ let status = async (
5157
let resp = await VeriSimClient.doGet(client, `/api/v1/hexads/${hexadId}/drift/status`)
5258
if resp.ok {
5359
let json = await VeriSimClient.jsonBody(resp)
54-
Ok(json->Obj.magic)
60+
Ok(json->fromJson)
5561
} else {
5662
Error(VeriSimError.fromStatus(resp.status))
5763
}
@@ -82,7 +88,7 @@ let normalize = async (
8288
)
8389
if resp.ok {
8490
let json = await VeriSimClient.jsonBody(resp)
85-
Ok(json->Obj.magic)
91+
Ok(json->fromJson)
8692
} else {
8793
Error(VeriSimError.fromStatus(resp.status))
8894
}

‎verisimdb/connectors/clients/rescript/src/VeriSimFederation.res‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@
77
// sharing and synchronising hexad data across peers. This module provides functions
88
// to register and manage peers and to execute cross-node queries.
99

10+
/// JSON boundary cast — used at the HTTP response boundary where we trust
11+
/// the VeriSimDB server's JSON schema matches our ReScript types.
12+
/// This replaces Obj.magic with an explicit, auditable cast point.
13+
external fromJson: JSON.t => 'a = "%identity"
14+
external toJson: 'a => JSON.t = "%identity"
15+
1016
/** Peer registration input. */
1117
type peerRegistration = {
1218
name: string,
@@ -33,11 +39,14 @@ let registerPeer = async (
3339
input: peerRegistration,
3440
): result<VeriSimTypes.federationPeer, VeriSimError.t> => {
3541
try {
36-
let body = input->Obj.magic->JSON.stringify->JSON.parseExn
42+
let body = switch JSON.stringifyAny(input) {
43+
| Some(s) => JSON.parseExn(s)
44+
| None => JSON.parseExn("{}")
45+
}
3746
let resp = await VeriSimClient.doPost(client, "/api/v1/federation/peers", body)
3847
if resp.status == 201 {
3948
let json = await VeriSimClient.jsonBody(resp)
40-
Ok(json->Obj.magic)
49+
Ok(json->fromJson)
4150
} else {
4251
Error(VeriSimError.fromStatus(resp.status))
4352
}
@@ -58,7 +67,7 @@ let listPeers = async (
5867
let resp = await VeriSimClient.doGet(client, "/api/v1/federation/peers")
5968
if resp.ok {
6069
let json = await VeriSimClient.jsonBody(resp)
61-
Ok(json->Obj.magic)
70+
Ok(json->fromJson)
6271
} else {
6372
Error(VeriSimError.fromStatus(resp.status))
6473
}
@@ -80,11 +89,14 @@ let federatedQuery = async (
8089
input: federatedQueryRequest,
8190
): result<VeriSimTypes.federatedQueryResult, VeriSimError.t> => {
8291
try {
83-
let body = input->Obj.magic->JSON.stringify->JSON.parseExn
92+
let body = switch JSON.stringifyAny(input) {
93+
| Some(s) => JSON.parseExn(s)
94+
| None => JSON.parseExn("{}")
95+
}
8496
let resp = await VeriSimClient.doPost(client, "/api/v1/federation/query", body)
8597
if resp.ok {
8698
let json = await VeriSimClient.jsonBody(resp)
87-
Ok(json->Obj.magic)
99+
Ok(json->fromJson)
88100
} else {
89101
Error(VeriSimError.fromStatus(resp.status))
90102
}

‎verisimdb/connectors/clients/rescript/src/VeriSimHexad.res‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@
77
// operations for VeriSimDB hexad entities. All functions are async and
88
// communicate with the VeriSimDB REST API via VeriSimClient's HTTP helpers.
99

10+
/// JSON boundary cast — used at the HTTP response boundary where we trust
11+
/// the VeriSimDB server's JSON schema matches our ReScript types.
12+
/// This replaces Obj.magic with an explicit, auditable cast point.
13+
external fromJson: JSON.t => 'a = "%identity"
14+
external toJson: 'a => JSON.t = "%identity"
15+
1016
/** Create a new hexad on the VeriSimDB server.
1117
*
1218
* @param client The authenticated client configuration.
@@ -18,11 +24,14 @@ let create = async (
1824
input: VeriSimTypes.hexadInput,
1925
): result<VeriSimTypes.hexad, VeriSimError.t> => {
2026
try {
21-
let body = input->Obj.magic->JSON.stringify->JSON.parseExn
27+
let body = switch JSON.stringifyAny(input) {
28+
| Some(s) => JSON.parseExn(s)
29+
| None => JSON.parseExn("{}")
30+
}
2231
let resp = await VeriSimClient.doPost(client, "/api/v1/hexads", body)
2332
if resp.status == 201 {
2433
let json = await VeriSimClient.jsonBody(resp)
25-
Ok(json->Obj.magic)
34+
Ok(json->fromJson)
2635
} else {
2736
Error(VeriSimError.fromStatus(resp.status))
2837
}
@@ -45,7 +54,7 @@ let get = async (
4554
let resp = await VeriSimClient.doGet(client, `/api/v1/hexads/${id}`)
4655
if resp.ok {
4756
let json = await VeriSimClient.jsonBody(resp)
48-
Ok(json->Obj.magic)
57+
Ok(json->fromJson)
4958
} else {
5059
Error(VeriSimError.fromStatus(resp.status))
5160
}
@@ -69,11 +78,14 @@ let update = async (
6978
input: VeriSimTypes.hexadInput,
7079
): result<VeriSimTypes.hexad, VeriSimError.t> => {
7180
try {
72-
let body = input->Obj.magic->JSON.stringify->JSON.parseExn
81+
let body = switch JSON.stringifyAny(input) {
82+
| Some(s) => JSON.parseExn(s)
83+
| None => JSON.parseExn("{}")
84+
}
7385
let resp = await VeriSimClient.doPut(client, `/api/v1/hexads/${id}`, body)
7486
if resp.ok {
7587
let json = await VeriSimClient.jsonBody(resp)
76-
Ok(json->Obj.magic)
88+
Ok(json->fromJson)
7789
} else {
7890
Error(VeriSimError.fromStatus(resp.status))
7991
}
@@ -125,7 +137,7 @@ let list = async (
125137
)
126138
if resp.ok {
127139
let json = await VeriSimClient.jsonBody(resp)
128-
Ok(json->Obj.magic)
140+
Ok(json->fromJson)
129141
} else {
130142
Error(VeriSimError.fromStatus(resp.status))
131143
}

‎verisimdb/connectors/clients/rescript/src/VeriSimProvenance.res‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@
77
// linked sequence of events recording every mutation applied to it. This module
88
// provides functions to query chains, record new events, and verify integrity.
99

10+
/// JSON boundary cast — used at the HTTP response boundary where we trust
11+
/// the VeriSimDB server's JSON schema matches our ReScript types.
12+
/// This replaces Obj.magic with an explicit, auditable cast point.
13+
external fromJson: JSON.t => 'a = "%identity"
14+
external toJson: 'a => JSON.t = "%identity"
15+
1016
/** Retrieve the complete provenance chain for a hexad.
1117
*
1218
* The chain is returned in chronological order (oldest first) and includes
@@ -24,7 +30,7 @@ let getChain = async (
2430
let resp = await VeriSimClient.doGet(client, `/api/v1/hexads/${hexadId}/provenance`)
2531
if resp.ok {
2632
let json = await VeriSimClient.jsonBody(resp)
27-
Ok(json->Obj.magic)
33+
Ok(json->fromJson)
2834
} else {
2935
Error(VeriSimError.fromStatus(resp.status))
3036
}
@@ -49,11 +55,14 @@ let recordEvent = async (
4955
input: VeriSimTypes.provenanceEventInput,
5056
): result<VeriSimTypes.provenanceEvent, VeriSimError.t> => {
5157
try {
52-
let body = input->Obj.magic->JSON.stringify->JSON.parseExn
58+
let body = switch JSON.stringifyAny(input) {
59+
| Some(s) => JSON.parseExn(s)
60+
| None => JSON.parseExn("{}")
61+
}
5362
let resp = await VeriSimClient.doPost(client, `/api/v1/hexads/${hexadId}/provenance`, body)
5463
if resp.status == 201 {
5564
let json = await VeriSimClient.jsonBody(resp)
56-
Ok(json->Obj.magic)
65+
Ok(json->fromJson)
5766
} else {
5867
Error(VeriSimError.fromStatus(resp.status))
5968
}
@@ -84,7 +93,7 @@ let verify = async (
8493
)
8594
if resp.ok {
8695
let json = await VeriSimClient.jsonBody(resp)
87-
let chain: VeriSimTypes.provenanceChain = json->Obj.magic
96+
let chain: VeriSimTypes.provenanceChain = json->fromJson
8897
Ok(chain.verified)
8998
} else {
9099
Error(VeriSimError.fromStatus(resp.status))

0 commit comments

Comments
 (0)