⚡ @trap_stevo/vericore

The next-generation cryptographic engine for deterministic persistence, adaptive sharding, and self-stabilizing data orchestration.

Deliver consistent, zero-trust reliability through precision indexing and atomic write flows. Scale seamlessly across nodes, sustain real-time performance under load, and preserve data integrity through autonomous synchronization.

🚀 Features

• ⚡ High-Throughput Writes – Append-optimized pipelines sustain heavy concurrency with steady latency
• 🧭 Precision Indexing (optional) – Private, prefix-scoped discovery without exposing plaintext keys
• 🔒 Zero-Trust at Rest (optional) – Seamless at-rest protection with machine-bound keying
• 🧱 Deterministic Persistence – Atomic record flow with crash-safe recovery patterns
• 🧵 Adaptive Sharding – Distribute load across multiple segments for parallel I/O
• 🧼 Self-Stabilizing Orchestration – Background synchronization and debounced index consolidation
• 🧪 Namespace Isolation – Partition data for multi-tenant and multi-service deployments
• 🧰 Minimal, Powerful API – get, set, delete, keys (+ optional prefix APIs)

⚙️ System Requirements

| Requirement | Version | |---|---| | Node.js | ≥ 18.x (recommended ≥ 20.x) | | npm | ≥ 9.x | | OS | Windows, macOS, Linux | | Disk | SSD/NVMe recommended |

🛠️ Constructor

const VeriCore = require("@trap_stevo/vericore");

const core = VeriCore("./storage", {
     namespace        : "app",
     encrypt          : false,     // enable for at-rest protection
     offset           : "",        // optional entropy for keying
     lockprint        : null,      // inject your own fingerprint if desired
     lockprintOptions : {          // used only when lockprint not provided
          filename    : ".fingerprint",
          printDNA    : 32
     },
     shardCount       : 32,        // tune for your medium (16–64 typical)
     domain           : "VeriCore",
     // Optional discovery features:
     prefixIndex      : false,     // enable secure prefix lookups
     prefixFlushMs    : 50         // debounce for index consolidation
});

Options

| Key | Type | Description | Default | |---|---|---|---| | namespace | string | Logical partition for data | "default" | | encrypt | boolean | At-rest protection toggle | false | | offset | string | Extra entropy for keying | "" | | lockprint | string \| null | Fixed device fingerprint | null | | lockprintOptions.filename | string | Fingerprint path | .fingerprint | | lockprintOptions.printDNA | number | Randomness for fingerprint generation | 32 | | shardCount | number | Count of storage segments | 16 | | domain | string | Derivation namespace | "VeriCore" | | prefixIndex | boolean | Private prefix discovery toggle | false | | prefixFlushMs | number | Debounce window for discovery consolidation | 50 |

🔑 Core Methods

| Method | Signature | Sync/Async | |---------|----------------------------------------------------------------------|------------| | get | get(key: string, opts?: { locked?: boolean }) => Promise<any \| null> | Async | | set | set(key: string, value: any) => Promise<void> | Async | | delete| delete(key: string) => Promise<void> | Async | | keys | keys() => Promise<string[]> | Async |

VeriCore avoids plaintext keys on disk and inside keys() output. Treat keys() as an administrative surface.

🧭 Optional Prefix API (Private Discovery)

Enable with { prefixIndex: true }. Secure, prefix-scoped discovery without plaintext exposure.

| Method | Signature | Sync/Async | |--------------------|----------------------------------------------------------------------------------------------------------|------------| | countPrefix | countPrefix(prefix: string) => Promise<number> | Async | | valuesByPrefix | valuesByPrefix(prefix: string, limit?: number) => Promise<any[]> | Async | | entriesByPrefix | entriesByPrefix(prefix: string, options?: { withKeyHash?: boolean, limit?: number }) => Promise<Array<{ value: any } \| { keyHash: string, value: any }>> | Async | | flushPrefixIndex | flushPrefixIndex(options?: { all?: boolean }) => Promise<void> | Async |

Discovery runs in eventual-consistency mode for peak throughput. For strict, point-in-time counts or exports, call flushPrefixIndex({ all: true }) before measurement.

📦 Installation

npm install @trap_stevo/vericore

💡 Example Usage

High-throughput write & read

const path = require("path");
const VeriCore = require("@trap_stevo/vericore");

function chunk(items, size) {
     const out = [];
     for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
     return out;
}

(async () => {
     const storage = path.resolve("./storage");
     const core = VeriCore(storage, {
          namespace    : "app",
          encrypt      : false,
          shardCount   : 32,
          prefixIndex  : true,   // enable discovery
          prefixFlushMs: 50
     });

     const total = 10_000;
     const concurrency = 64;

     const users = Array.from({ length: total }, (_, i) => ({
          key: `Users/u:${String(i + 1).padStart(5, "0")}`,
          value: {
               id: i + 1,
               name: `User ${i + 1}`,
               email: `user${i + 1}@example.com`,
               roles: (i % 10 === 0) ? ["admin"] : ["member"]
          }
     }));

     const t0 = Date.now();
     for (const group of chunk(users, concurrency)) {
          await Promise.all(group.map(u => core.set(u.key, u.value)));
     }
     const t1 = Date.now();

     console.log("[wrote]", total, "users in", (t1 - t0) + "ms");

     // Direct reads
     console.log(await core.get("Users/u:00001"));
     console.log(await core.get("Users/u:10000"));

     // Consolidate discovery view before measurement
     await core.flushPrefixIndex({ all: true });

     // Private discovery
     console.log("count", await core.countPrefix("Users/"));
     console.log("values", await core.valuesByPrefix("Users/", 3));
     console.log("entries", await core.entriesByPrefix("Users/", { withKeyHash: true, limit: 2 }));
})();

🧯 Operational Guidance

• Throughput Tuning

  • Start with shardCount: 32 on SSD/NVMe. Test 16–64 to locate median latency.
  • Batch writes with Promise.all at 32–128 concurrency per process.

• Consistency

  • Discovery uses eventual consistency. For strict snapshots, call flushPrefixIndex({ all:true }).

• Graceful Shutdown

  • Flush discovery during teardown:

    const flushAll = async () => {
         if (typeof core.flushPrefixIndex === "function") {
              try { await core.flushPrefixIndex({ all: true }); } catch {}
         }
    };
    process.on("beforeExit", flushAll);
    process.on("SIGINT", async () => { await flushAll(); process.exit(0); });
    process.on("SIGTERM", async () => { await flushAll(); process.exit(0); });

• Namespaces

  • Separate namespace values for modules or tenants to isolate data and maintenance windows.

🔐 Security Posture

• No plaintext keys on disk
• Optional at-rest protection per instance
• Discovery operates on private tokens and internal identifiers
• Implementation details remain abstract to reduce attack surface

Pair VeriCore with OS hardening, least-privilege access, and regular rotation of surrounding secrets.

📊 Benchmarks (indicative)

Environment: Node 20.x, Windows 11 / macOS 14, consumer NVMe SSD, single process, shardCount=32, concurrency=64.
Payload: 10k JSON records (~85–90 B each). Total data written (including storage overhead) ≈ 1.5–2.0 MB.

Write throughput

• 10k writes in ~1.5–1.9s (≈ 6k–7k ops/sec)
• Consistency: eventual (discovery enabled, debounced)
• Encryption: off (toggle on typically reduces throughput modestly)

Read latency (random lookups)

• p50: <1 ms per get
• p95: 1–3 ms per get
• Cache warm after first access

Discovery (prefix)

• countPrefix("Users/"): O(1) feel in practice; negligible overhead
• valuesByPrefix(..., limit=3): completes in low ms

Results vary by hardware, filesystem, payload size, and concurrency strategy.
For strict point-in-time counts/exports, call flushPrefixIndex({ all: true }) prior to measurement.

📜 License

See LICENSE.md.

⚡ Persist with Precision

VeriCore delivers deterministic persistence, adaptive sharding, and private discovery without operational friction. Run fast, stay consistent, and keep secrets secret.