cryptodb 2.4.3__py3-none-any.whl

cryptodb-2.4.3.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: cryptodb
+Version: 2.4.3
+Summary: NEDB — a versioned, self-compressing, time-traveling embedded database (replay-protected, idempotent, relational, searchable) with durable AOF persistence and a server daemon (nedbd).
+Project-URL: Homepage, https://github.com/aiassistsecure/nedb
+Project-URL: Repository, https://github.com/aiassistsecure/nedb
+Author: Eth-Interchained
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: compression,database,dedup,embedded,git,graph,mvcc,persistence,redis,search,server,time-travel,versioning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database :: Database Engines/Servers
+Requires-Python: >=3.8
+Requires-Dist: pycryptodome>=3.19
+Provides-Extra: encryption
+Requires-Dist: cryptography>=41; extra == 'encryption'
+Description-Content-Type: text/markdown
+
+<h1 align="center">CryptoDB</h1>
+<p align="center"><b>The database that can prove it never lied.</b></p>
+
+---
+
+CryptoDB is a **content-addressed, hash-chained, time-traveling** datastore. Every version of every record is an immutable, **BLAKE2b-verified** object in a Merkle DAG — nothing is ever overwritten, and the store can prove its own integrity on demand.
+
+If your data is evidence — ledgers, audit trails, provenance, anything you may one day have to *defend* — CryptoDB makes the history itself tamper-evident and replayable.
+
+## Why CryptoDB
+
+- 🔒 **Tamper-evident by construction.** `verify()` re-hashes every object against its content address. Flip a single byte on disk and it's caught — silently impossible to forge history.
+- ⏪ **Time-travel is a query.** `AS OF <seq>` returns the exact state at any point. `VALID AS OF <time>` adds bi-temporal validity — *what was true, as of when.*
+- 🧬 **Causal provenance.** `caused_by` links every record to the facts that produced it; `TRACE` walks the graph. Audit **why**, not just **what**.
+- 🔐 **Encrypted at rest** (AES-256-GCM), RESP2 wire protocol, SQL / Redis / Mongo adapters, a `nedbd-v2` server daemon.
+
+## Install
+
+```bash
+npm install cryptodb        # Node (native addon)
+pip install cryptodb        # Python
+cargo add cryptodb          # Rust
+```
+
+## Reach for it when
+
+Audit logs · financial & token ledgers · compliance trails · supply-chain provenance · anything where **provable, replayable history is the product**, not a nice-to-have.
+
+```js
+import { NedbCore } from "cryptodb";
+const db = new NedbCore();
+db.put("ledger", "acct:alice", JSON.stringify({ balance: 100 }));
+db.put("ledger", "acct:alice", JSON.stringify({ balance: 250 }));
+db.getAsOf("ledger", "acct:alice", 0n);   // → balance 100, the past, intact
+db.verify();                               // → true: nothing was tampered
+```
+
+---
+
+<sub>CryptoDB is a distribution of the **NEDB** engine, tuned for verifiability. Engine development happens upstream at [Eth-Interchained/nedb](https://github.com/Eth-Interchained/nedb). © Interchained LLC.</sub>

cryptodb-2.4.3.dist-info/RECORD

@@ -0,0 +1,27 @@
+nedb/__init__.py,sha256=F0EzI9xFniLDwrMqzyYn_JRfi2S2YcsOVkv8AL7I8eM,4498
+nedb/autoindex.py,sha256=vzaPYisirBAW2gjdqu-b7xg6d4NledE17f5dOqRtcSM,5711
+nedb/cascade.py,sha256=qHvBivx4xbrAesGz3X27aJPo5bppgvukEZhw-qumHgo,4436
+nedb/concurrent.py,sha256=97NmtkipEagk9vdriSwiNhLFqIGbv6CzRLQjSTZJBf8,8453
+nedb/crypto.py,sha256=vA1TI48EvdyWBEnpMm0oX8mQ-EopeBbtnhm3kCpUxiA,11540
+nedb/engine.py,sha256=dD6Pz3zQYepWlLBFWDHF5ASM5Jp00dSVTjVUXvQ-jM8,35581
+nedb/index.py,sha256=vrBPWlcXN25AhvuQsqX-0Y3x3o-FwvZYKQmvSjXGD4Q,4020
+nedb/log.py,sha256=PlEPpv70P1MCYyWPozxLSIOLHcN6Q6qR0TLeQ-AyvQQ,9246
+nedb/merkle.py,sha256=dVZZTXlcXiAj-9WfFzmfnCsAl_9Bq-p7dWL2_sMNkbA,1947
+nedb/mongo.py,sha256=ANN9WcW3TvTyfkkUyRZzRu_6zibMkxe2sfJCg_tGdFo,33542
+nedb/proof.py,sha256=NKiS64H0Z7d5JR9YvKB9M3L4OijdVYz3N4T78N46T0Y,5135
+nedb/query.py,sha256=h6549FohvQF4mBI0ZAdGbaoRkXUrxJo8WEnnJwUeCgg,9222
+nedb/redis_compat.py,sha256=Gx8XENApoUaW2WoATDYH0W3oVvVdW1sZa4upwP0EXIs,19783
+nedb/relations.py,sha256=howNwh8q2mLv6jFc_jhyXXlJY--e_4eJAGRIFf6OBko,2050
+nedb/resp2.py,sha256=AATG29fGJoax_1zDSiVo-tOgiw2zPt-RiKtzP1bxUYE,10087
+nedb/server.py,sha256=G_czcSIOn5HuBLimdCivlMcIjXa8hvkz5EtjUcQK7MI,50951
+nedb/snapshot.py,sha256=4pMfFfp6cIS3zGmCXV1ccO2UuhUq67F_lAnRxNJ5jys,8867
+nedb/sql.py,sha256=0gHL9vibLJVHN1OV04cB5NPDJvZEPid5aXPzYn1dGBI,13539
+nedb/store.py,sha256=mxuyEeQAF-BCW0xVHiJz9iDR1UjzWCPQPX8fa1Hbo0o,2648
+nedb/wrap_redis.py,sha256=wd13lLJLp6GAkIyi5dDsOdzrFDUUe1siKoK9i02LQGE,30208
+nedb/backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nedb/backends/redis_backend.py,sha256=FrRkJ5_H-qLt8AH7mYMmTQaG1Sf-5LqLIOtSmyYVR_I,4950
+cryptodb-2.4.3.dist-info/METADATA,sha256=JPNNeG7Zrb5eozbCApmzkGwM7KwUisLZLWWhGLB6LMs,3117
+cryptodb-2.4.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cryptodb-2.4.3.dist-info/entry_points.txt,sha256=KcR6tni6CeAIvIuv7HPWBTaxEP4jT6e7I_5a7jCIXew,43
+cryptodb-2.4.3.dist-info/licenses/LICENSE,sha256=A8BP4sCOVNtv_n14Vf3obmmdNkM9vrxbyZmjS9wnVug,6607
+cryptodb-2.4.3.dist-info/RECORD,,

cryptodb-2.4.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cryptodb-2.4.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nedbd = nedb.server:main

cryptodb-2.4.3.dist-info/licenses/LICENSE

@@ -0,0 +1,65 @@
+Business Source License 1.1
+
+Licensor: Interchained LLC, VibeCode 101, and/or the applicable copyright holders of NEDB
+
+Licensed Work: NEDB, including all source code, documentation, examples, tests, build scripts, specifications, APIs, SDKs, packages, binaries, and derivative works distributed from or based on the NEDB repository.
+
+Copyright: Copyright (c) 2026 Interchained LLC, VibeCode 101, and contributors. All rights reserved.
+
+Change Date: Four years after the first publicly available distribution of each specific version of the Licensed Work under this License.
+
+Change License: GNU Affero General Public License v3.0 or later.
+
+Additional Use Grant:
+
+You may use the Licensed Work only for non-production purposes, including evaluation, development, testing, research, local experimentation, security review, benchmarking, and personal learning.
+
+No production use is granted automatically.
+
+For clarity, the following uses are not permitted unless you have prior written permission from the Licensor:
+
+1. Using the Licensed Work in production.
+2. Using the Licensed Work to store, process, serve, index, replicate, query, or manage production data.
+3. Offering the Licensed Work, or any derivative work, as a hosted, managed, embedded, bundled, white-labeled, commercial, paid, revenue-generating, or customer-facing product or service.
+4. Offering database-as-a-service, storage-as-a-service, cache-as-a-service, search-as-a-service, analytics-as-a-service, AI-memory-as-a-service, agent-memory-as-a-service, blockchain-indexing-as-a-service, or any substantially similar service using the Licensed Work.
+5. Using the Licensed Work to compete with NEDB, Interchained LLC, VibeCode 101, AiAssist Secure, or any affiliated product, service, infrastructure platform, database engine, AI runtime, agent platform, or hosted developer infrastructure.
+6. Embedding the Licensed Work into commercial software, SaaS products, internal business systems, enterprise systems, hosted infrastructure, blockchain infrastructure, AI-agent infrastructure, or customer deliverables.
+7. Removing, hiding, modifying, or misrepresenting this License, copyright notices, attribution notices, authorship notices, repository references, or licensing notices.
+8. Circumventing license checks, access controls, paid licensing requirements, commercial-use restrictions, attribution requirements, or technical protections included with the Licensed Work.
+9. Using the Licensed Work in a way that implies endorsement, partnership, sponsorship, certification, or approval by the Licensor without written permission.
+10. Reselling, relicensing, sublicensing, renting, leasing, or otherwise commercially exploiting the Licensed Work except as expressly authorized in writing.
+
+Additional production, commercial, hosted, enterprise, embedded, OEM, resale, white-label, managed-service, competitive, or otherwise restricted use grants are available only by separate written permission from the Licensor.
+
+Written permission must be obtained from at least one of the following authorized licensing contacts:
+
+[founders@vibecode-101.com](mailto:founders@vibecode-101.com)
+[dev@interchained.org](mailto:dev@interchained.org)
+
+Permission is valid only if it is expressly granted in writing by an authorized representative of the Licensor and specifically identifies the permitted use, scope, duration, parties, and any applicable commercial terms.
+
+A general email conversation, informal message, pull request, issue comment, social media message, verbal discussion, repository access, package download, or contribution acceptance does not create a production, commercial, hosted, enterprise, resale, or competitive use license.
+
+Terms:
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work. The Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first, the Licensor hereby grants you rights under the terms of the Change License, and the rights granted in the paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently in effect as described in this License, you must purchase or obtain a separate commercial license from the Licensor, its affiliated entities, or authorized resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are subject to this License. This License applies separately for each version of the Licensed Work, and the Change Date may vary for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of the Licensed Work. If you receive the Licensed Work in original or modified form from a third party, the terms and conditions set forth in this License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically terminate your rights under this License for the current and all other versions of the Licensed Work.
+
+This License does not grant you any right in any trademark, service mark, trade name, logo, domain name, brand identity, product name, project name, or other identifier of Licensor or its affiliates, except as expressly required to preserve legally required notices.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, TITLE, SECURITY, ACCURACY, AVAILABILITY, DATA INTEGRITY, PERFORMANCE, AND FITNESS FOR PRODUCTION USE.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, LOSSES, COSTS, EXPENSES, BUSINESS INTERRUPTION, LOST PROFITS, LOST REVENUE, LOST DATA, SECURITY INCIDENTS, SERVICE OUTAGES, OR OTHER LIABILITY ARISING FROM OR RELATED TO THE LICENSED WORK OR YOUR USE OF THE LICENSED WORK.
+
+Notice:
+
+The Business Source License is not an Open Source license. However, each version of the Licensed Work will become available under the Change License on the applicable Change Date, or on the fourth anniversary of the first publicly available distribution of that version under this License, whichever comes first.

nedb/__init__.py

@@ -0,0 +1,92 @@
+"""
+NEDB — a versioned, self-compressing, time-traveling embedded database.
+
+  * Replay-protected & idempotent: every write carries a monotonic nonce and an
+    optional idempotency key, enforced by a hash-chained append-only log.
+  * Time-travel: read the database AS OF any past sequence number.
+  * Relational: first-class, time-travel-aware relations with O(1) traversal.
+  * Filterable / sortable / searchable: equality, ordered, and full-text indexes.
+  * Queryable: NQL text queries and a fluent builder that share one plan.
+  * git-style files with Cascade compression: content-defined chunking + dedup +
+    temperature tiers, with a Merkle root per version anchorable on-chain.
+
+The pure-Python package is the reference implementation and the always-works
+fallback. When installed from a platform wheel, the compiled Rust core is available
+as ``nedb._native`` (``nedb.__has_native__`` reports whether it loaded).
+"""
+from __future__ import annotations
+
+from .engine import NEDB
+from .log import Op, OpLog, ReplayError
+from .query import Query, parse_nql
+from .snapshot import save_snapshot, load_snapshot
+from .crypto import resolve_tmk, rewrap_dek
+from .sql import sql_exec, sql_to_nql, SQLError, SQLUnsupportedError
+from .redis_compat import RedisCompat, RedisError, RedisUnsupportedError
+from .mongo import (
+    MongoCompat, MongoClient, MongoError, MongoUnsupportedError, ObjectId,
+)
+from .autoindex import AutoIndexDB
+from .concurrent import Sequencer
+from .wrap_redis import wrap_redis, WrappedRedis
+from .proof import verify_proof, fold_head
+
+try:  # compiled Rust core, present in platform wheels (PyO3 via maturin)
+    from . import _native  # type: ignore
+    __has_native__ = True
+except ImportError:  # pure-Python install (sdist / unsupported platform)
+    # Provide a stub module so `from nedb._native import NedbCore` raises an
+    # informative error instead of a bare ImportError with no guidance.
+    import types as _types, sys as _sys
+
+    import sys as _sys_tmp, os as _os_tmp
+    _is_msys2 = bool(_os_tmp.environ.get("MSYSTEM")) or "mingw" in _sys_tmp.executable.lower()
+    del _sys_tmp, _os_tmp
+
+    class _NativeStub(_types.ModuleType):
+        # Primary fix: install the Rust crate → get the nedbd server → use HTTP mode.
+        # Secondary fix (CPython only): pip reinstall to get the platform wheel with _native embedded.
+        _MSG_MSYS2 = (
+            "\n\n"
+            "  nedb._native (embedded v2 DAG core) is not available on MSYS2/MinGW Python.\n\n"
+            "  To use NEDB v2 features, install the server binary and use HTTP mode:\n\n"
+            "    cargo install nedb-engine          # install nedbd v2 server\n"
+            "    nedbd --dag ./data                 # start DAG server\n"
+            "    NEDB_URL=http://localhost:7070 python3 your_script.py\n\n"
+            "  Run 'nedbd --doctor' for a full diagnosis.\n"
+        )
+        _MSG_OTHER = (
+            "\n\n"
+            "  nedb._native (embedded v2 DAG core) is not available.\n"
+            "  You have the universal wheel — reinstall to get the platform wheel:\n\n"
+            "    pip install --force-reinstall --no-cache-dir nedb-engine\n\n"
+            "  Or install the server binary and use HTTP mode (works everywhere):\n\n"
+            "    cargo install nedb-engine          # install nedbd v2 server\n"
+            "    nedbd --dag ./data                 # start DAG server\n"
+            "    NEDB_URL=http://localhost:7070 python3 your_script.py\n\n"
+            "  Run 'nedbd --doctor' for a full diagnosis.\n"
+        )
+        _MSG = _MSG_MSYS2 if _is_msys2 else _MSG_OTHER
+
+        def __getattr__(self, name: str):
+            raise ImportError(f"nedb._native.{name} is not available.{self._MSG}")
+
+    _native_stub = _NativeStub("nedb._native")
+    _native_stub.__package__ = "nedb"
+    _sys.modules["nedb._native"] = _native_stub  # type: ignore
+    _native = _native_stub  # type: ignore
+    __has_native__ = False
+    del _types, _sys, _NativeStub, _native_stub
+
+__all__ = [
+    "NEDB", "OpLog", "Op", "ReplayError", "Query", "parse_nql",
+    "save_snapshot", "load_snapshot",
+    "sql_exec", "sql_to_nql", "SQLError", "SQLUnsupportedError",
+    "RedisCompat", "RedisError", "RedisUnsupportedError",
+    "MongoCompat", "MongoClient", "MongoError", "MongoUnsupportedError", "ObjectId",
+    "AutoIndexDB", "Sequencer",
+    "wrap_redis", "WrappedRedis",
+    "verify_proof", "fold_head",
+    "_native", "__has_native__",
+]
+__version__ = "2.4.3"

nedb/autoindex.py

@@ -0,0 +1,142 @@
+"""
+nedb.autoindex — automatic index management.
+
+Wraps a NEDB instance and intercepts query() calls. It tracks which fields are
+used in WHERE and ORDER BY clauses per collection. Once a field reaches the
+usage threshold it auto-creates the appropriate index:
+
+  - Equality conditions (= / !=)   → "eq"    index
+  - Ordered comparisons (< > ≤ ≥) → "ordered" index
+  - ORDER BY field                  → "ordered" index
+  - SEARCH clause on a field        → deferred (no per-field signal in NQL)
+
+Usage::
+
+    from nedb import NEDB
+    from nedb.autoindex import AutoIndexDB
+
+    db = AutoIndexDB(NEDB("./data"), threshold=3)
+    db.query('FROM users WHERE status = "active"')   # tallied
+    db.query('FROM users WHERE status = "active"')
+    db.query('FROM users WHERE status = "active"')   # threshold reached → index created
+"""
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from typing import Any, Dict, List, Optional, Tuple
+
+
+_WHERE_RE = re.compile(r"\bWHERE\b([\s\S]*?)(?:\bSEARCH\b|\bORDER\b|\bTRAVERSE\b|\bLIMIT\b|$)", re.IGNORECASE)
+_ORDER_RE = re.compile(r"\bORDER\s+BY\s+(\w+)", re.IGNORECASE)
+_FROM_RE  = re.compile(r"\bFROM\s+(\w+)", re.IGNORECASE)
+_COND_RE  = re.compile(r"(\w+)\s*(=|!=|<>|<=|>=|<|>)", re.IGNORECASE)
+
+
+def _parse_signals(nql: str) -> List[Tuple[str, str, str]]:
+    """Return [(collection, field, 'eq'|'ordered')] from a NQL query string."""
+    signals = []
+    fm = _FROM_RE.search(nql)
+    if not fm:
+        return signals
+    coll = fm.group(1)
+
+    wm = _WHERE_RE.search(nql)
+    if wm:
+        for m in _COND_RE.finditer(wm.group(1)):
+            field, op = m.group(1), m.group(2)
+            kind = "eq" if op in ("=", "!=", "<>") else "ordered"
+            signals.append((coll, field, kind))
+
+    om = _ORDER_RE.search(nql)
+    if om:
+        signals.append((coll, om.group(1), "ordered"))
+
+    return signals
+
+
+class AutoIndexDB:
+    """
+    NEDB wrapper that creates indexes automatically based on query usage.
+
+    Parameters
+    ----------
+    db : NEDB
+        A NEDB database instance (embedded or opened with a path).
+    threshold : int
+        Number of times a (collection, field, kind) combination must be
+        observed before the index is created. Default: 5.
+    verbose : bool
+        Print a message when an index is auto-created. Default: False.
+    """
+
+    def __init__(self, db: Any, threshold: int = 5, verbose: bool = False):
+        self._db = db
+        self.threshold = threshold
+        self.verbose = verbose
+        # counts[(coll, field, kind)] = n
+        self._counts: Dict[Tuple[str, str, str], int] = defaultdict(int)
+        # indexes already created so we don't re-create
+        self._created: set = set()
+        # Seed from existing index config if available
+        if hasattr(db, "indexes") and hasattr(db.indexes, "config"):
+            for coll, field, kind in db.indexes.config:
+                self._created.add((coll, field, kind))
+
+    # ── Proxy every NEDB attribute ────────────────────────────────────────────
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._db, name)
+
+    # ── Instrumented query ────────────────────────────────────────────────────
+
+    def query(self, nql: str) -> List[dict]:
+        """Execute a NQL query, tally field usage, and auto-create indexes."""
+        signals = _parse_signals(nql)
+        for coll, field, kind in signals:
+            key = (coll, field, kind)
+            if key in self._created:
+                continue
+            # "ordered" supersedes "eq" — if we already have eq, upgrade to ordered
+            eq_key = (coll, field, "eq")
+            if kind == "ordered" and eq_key not in self._created:
+                self._counts[key] += 1
+            elif kind == "eq" and (coll, field, "ordered") not in self._created:
+                self._counts[key] += 1
+            else:
+                self._counts[key] += 1
+
+            if self._counts[key] >= self.threshold:
+                self._auto_create(coll, field, kind)
+
+        return self._db.query(nql)
+
+    def _auto_create(self, coll: str, field: str, kind: str) -> None:
+        key = (coll, field, kind)
+        if key in self._created:
+            return
+        # Don't index internal NEDB fields
+        if field.startswith("_") and field not in ("_id",):
+            return
+        self._db.create_index(coll, field, kind)
+        self._created.add(key)
+        if self.verbose:
+            print(f"[autoindex] created {kind} index on {coll}.{field} (threshold={self.threshold})")
+
+    # ── Manual analysis ───────────────────────────────────────────────────────
+
+    def analyze(self) -> Dict[str, Any]:
+        """Return current tallies and the indexes already created."""
+        return {
+            "tallies": {f"{c}.{f} ({k})": n for (c, f, k), n in self._counts.items()},
+            "indexes_created": [f"{c}.{f} ({k})" for (c, f, k) in sorted(self._created)],
+            "threshold": self.threshold,
+        }
+
+    def suggest(self) -> List[str]:
+        """Return suggestions for indexes that are close to the threshold."""
+        out = []
+        for (coll, field, kind), count in sorted(self._counts.items(), key=lambda x: -x[1]):
+            if (coll, field, kind) not in self._created:
+                out.append(f"{coll}.{field} ({kind}) — {count}/{self.threshold} queries")
+        return out

nedb/backends/redis_backend.py

@@ -0,0 +1,115 @@
+"""
+nedb.backends.redis_backend — Redis Streams as the NEDB append-only log.
+
+Alice's existing Redis keys are NEVER touched. NEDB operates in a strictly
+isolated namespace:
+
+    nedb:{db_name}:oplog       Redis Stream  — hash-chained op log
+    nedb:{db_name}:snapshot    Redis Hash    — checkpoint for fast restart
+    nedb:{db_name}:events      Pub/Sub chan  — live subscriptions (future)
+    nedb:{db_name}:meta        Redis Hash    — version, index config
+
+On startup NEDB replays the stream to rebuild its in-memory MVCC store.
+On every write a new entry is XADD'd. One Redis connection, zero impact on
+the user's existing keys.
+
+© INTERCHAINED LLC × Claude Sonnet 4.6
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+
+class RedisBackend:
+    """
+    Redis-Streams-backed persistence for NEDB.
+
+    Pass an instance to NEDB as the `backend` parameter::
+
+        import redis
+        from nedb.backends.redis_backend import RedisBackend
+        from nedb import NEDB
+
+        r = redis.Redis("localhost", 6379)
+        db = NEDB(backend=RedisBackend(r, "rideshare"))
+    """
+
+    def __init__(self, r: Any, db_name: str):
+        self._r        = r
+        self.db_name   = db_name
+        self.stream    = f"nedb:{db_name}:oplog"
+        self.snap_key  = f"nedb:{db_name}:snapshot"
+        self.meta_key  = f"nedb:{db_name}:meta"
+        self.events_ch = f"nedb:{db_name}:events"
+
+    # ── Op log ──────────────────────────────────────────────────────────────────
+
+    def append(self, op_json: str) -> None:
+        """Append one JSON-serialised op to the stream."""
+        self._r.xadd(self.stream, {"op": op_json})
+
+    def append_batch(self, ops: List[str]) -> None:
+        """Append multiple ops in a single pipeline (one round-trip)."""
+        pipe = self._r.pipeline(transaction=False)
+        for op_json in ops:
+            pipe.xadd(self.stream, {"op": op_json})
+        pipe.execute()
+
+    def read_all(self) -> List[str]:
+        """Return all ops from the stream in insertion order."""
+        entries = self._r.xrange(self.stream, "-", "+")
+        return [e[1][b"op"].decode() for e in entries]
+
+    def read_after(self, last_id: str = "0") -> List[str]:
+        """Return ops appended after `last_id` (for incremental replay)."""
+        entries = self._r.xrange(self.stream, f"({last_id}", "+")
+        return [e[1][b"op"].decode() for e in entries]
+
+    # ── Snapshot / checkpoint ────────────────────────────────────────────────────
+
+    def save_snapshot(self, data: Dict[str, Any]) -> None:
+        """Persist a checkpoint so restart replay only needs the delta."""
+        self._r.hset(self.snap_key, mapping={
+            k: json.dumps(v, separators=(",", ":"), default=str)
+            for k, v in data.items()
+        })
+
+    def load_snapshot(self) -> Optional[Dict[str, Any]]:
+        """Load the last checkpoint, or None if none exists."""
+        raw = self._r.hgetall(self.snap_key)
+        if not raw:
+            return None
+        return {k.decode(): json.loads(v) for k, v in raw.items()}
+
+    # ── Pub/sub live events ──────────────────────────────────────────────────────
+
+    def publish_ops(self, ops: List[str]) -> None:
+        """Publish committed ops to the events channel for live subscribers."""
+        if ops:
+            payload = json.dumps(ops, separators=(",", ":"))
+            self._r.publish(self.events_ch, payload)
+
+    # ── Meta ─────────────────────────────────────────────────────────────────────
+
+    def save_meta(self, meta: Dict[str, Any]) -> None:
+        self._r.hset(self.meta_key, mapping={
+            k: json.dumps(v, separators=(",", ":"), default=str)
+            for k, v in meta.items()
+        })
+
+    def load_meta(self) -> Dict[str, Any]:
+        raw = self._r.hgetall(self.meta_key)
+        if not raw:
+            return {}
+        return {k.decode(): json.loads(v) for k, v in raw.items()}
+
+    # ── Utility ──────────────────────────────────────────────────────────────────
+
+    def stream_len(self) -> int:
+        return self._r.xlen(self.stream)
+
+    def flush(self) -> None:
+        """Delete all NEDB shadow keys for this database (non-destructive to user keys)."""
+        for key in [self.stream, self.snap_key, self.meta_key]:
+            self._r.delete(key)

nedb/cascade.py

@@ -0,0 +1,130 @@
+"""
+nedb.cascade — the Cascade compression pipeline + content-addressed blob store.
+
+This is what makes NEDB double as a git-style file manager with maximum compression
+WITHOUT inventing a new entropy coder. The novelty is the pipeline composition:
+
+  1. Content-defined chunking (Gear rolling hash) — boundaries follow content, so a
+     one-byte insert only changes the chunk(s) around it, not everything after it.
+  2. Content-addressed dedup (BLAKE) — identical chunks across all files and all
+     versions are stored exactly once.
+  3. Temperature tiers — warm data uses a fast codec (zstd in prod; zlib in this
+     reference), cold/archival history uses a maximum-ratio codec (LZMA).
+
+The production pipeline adds similarity-picked binary deltas (zstd --patch-from) and
+schema-aware columnar transforms before the entropy stage; both are documented in
+docs/SPEC.md and stubbed for the reference engine.
+"""
+from __future__ import annotations
+
+import hashlib
+import lzma
+import random
+import zlib
+from typing import Dict, List
+
+from .merkle import merkle_root
+
+# --- Gear-hash content-defined chunking -------------------------------------
+_MASK = (1 << 13) - 1            # ~8 KiB average chunk
+_MIN = 2 * 1024
+_MAX = 64 * 1024
+_M64 = 0xFFFFFFFFFFFFFFFF
+_GEAR = [random.Random(0x12345678 + i).getrandbits(64) for i in range(256)]
+
+
+def chunk(data: bytes) -> List[bytes]:
+    chunks: List[bytes] = []
+    n = len(data)
+    i = 0
+    while i < n:
+        limit = min(i + _MAX, n)
+        h = 0
+        pos = i
+        cut = limit
+        while pos < limit:
+            h = ((h << 1) + _GEAR[data[pos]]) & _M64
+            pos += 1
+            if (pos - i) >= _MIN and (h & _MASK) == 0:
+                cut = pos
+                break
+        chunks.append(data[i:cut])
+        i = cut
+    return chunks
+
+
+def _blake(b: bytes) -> str:
+    return hashlib.blake2b(b, digest_size=32).hexdigest()
+
+
+# --- temperature tiers ------------------------------------------------------
+def warm_compress(b: bytes) -> bytes:    # zstd stand-in in the reference
+    return zlib.compress(b, 6)
+
+
+def warm_decompress(b: bytes) -> bytes:
+    return zlib.decompress(b)
+
+
+def cold_compress(b: bytes) -> bytes:    # real LZMA — the maximum-ratio archival tier
+    return lzma.compress(b, preset=9 | lzma.PRESET_EXTREME)
+
+
+def cold_decompress(b: bytes) -> bytes:
+    return lzma.decompress(b)
+
+
+class BlobStore:
+    """Content-addressed, deduplicated, tiered blob store with versioned files."""
+
+    def __init__(self, tier: str = "warm") -> None:
+        self.tier = tier
+        self.chunks: Dict[str, bytes] = {}                      # hash -> compressed bytes
+        self.files: Dict[str, Dict[str, list]] = {}            # name -> {versions, roots}
+        self.logical_bytes = 0
+        self.dedup_hits = 0
+
+    def _compress(self, b: bytes) -> bytes:
+        return cold_compress(b) if self.tier == "cold" else warm_compress(b)
+
+    def _decompress(self, b: bytes) -> bytes:
+        return cold_decompress(b) if self.tier == "cold" else warm_decompress(b)
+
+    def put_file(self, name: str, data: bytes) -> int:
+        recipe: List[str] = []
+        for c in chunk(data):
+            hh = _blake(c)
+            recipe.append(hh)
+            if hh in self.chunks:
+                self.dedup_hits += 1
+            else:
+                self.chunks[hh] = self._compress(c)
+        self.logical_bytes += len(data)
+        f = self.files.setdefault(name, {"versions": [], "roots": []})
+        f["versions"].append(recipe)
+        f["roots"].append(merkle_root(recipe))
+        return len(f["versions"]) - 1
+
+    def get_file(self, name: str, version: int = -1) -> bytes:
+        recipe = self.files[name]["versions"][version]
+        out = bytearray()
+        for hh in recipe:
+            out += self._decompress(self.chunks[hh])
+        return bytes(out)
+
+    def root(self, name: str, version: int = -1) -> str:
+        return self.files[name]["roots"][version]
+
+    def stored_bytes(self) -> int:
+        return sum(len(v) for v in self.chunks.values())
+
+    def stats(self) -> dict:
+        stored = self.stored_bytes()
+        return {
+            "tier": self.tier,
+            "unique_chunks": len(self.chunks),
+            "dedup_hits": self.dedup_hits,
+            "logical_bytes": self.logical_bytes,
+            "stored_bytes": stored,
+            "ratio": round(self.logical_bytes / stored, 2) if stored else 0.0,
+        }