Add workspace-level integration tests against the public API (#18 §E3)

.gitignore

@@ -6,6 +6,12 @@ target/
 **/*.rs.bk
 *.pdb
 
+# Stray build artifacts. Two 3.6 MB Linux ELF executables with debug info were
+# committed at the repository root before this entry existed; both were produced
+# by an ad-hoc build, referenced by nothing, and carried in every clone.
+/rust_out
+/tmp
+
 # Coverage output
 /coverage/
 *.profraw

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
-members = [".", "api", "core", "adapters/tinycortex", "adapters/remote"]
-default-members = [".", "api", "core", "adapters/tinycortex", "adapters/remote"]
+members = [".", "api", "core", "adapters/tinycortex", "adapters/remote", "conformance"]
+default-members = [".", "api", "core", "adapters/tinycortex", "adapters/remote", "conformance"]
 # `vendor/` holds engine submodules (tinycortex, tinybus, tinyagents), each of
 # which is its own workspace with its own lockfile. Same exclusion
 # `vendor/tinycortex` uses for its own nested vendor directory.
@@ -72,6 +72,10 @@ serde = { version = "1", features = ["derive"] }
 [dev-dependencies]
 # The mandatory-family tests are async.
 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+# The reference driver and the behavioural suite, for the workspace-level
+# integration tests. A dev-dependency only: the facade must not carry a test
+# harness into a consumer's dependency graph.
+tinymemory-conformance = { path = "conformance" }
 
 [features]
 default = []

README.md

@@ -21,14 +21,30 @@ src/
 │                       binds as, and the fail-closed external-driver gate
 └── mandatory/          the three mandatory capability families, composed once
                         over the `Memory` storage trait
+core/                   tinymemory-core — the substance: ingestion, the summary
+                        tree, chunk storage, entities, the graph, the diff
+                        ledger, goals, tool-memory, and the Composio sync layer.
+                        The largest crate here by a wide margin, and the one a
+                        real host actually depends on. Unlike `api/` it is not
+                        dependency-light: today it links the TinyCortex engine,
+                        a bundled SQLite, and an HTTP stack unconditionally.
 adapters/
 ├── tinycortex/         the TinyCortex engine seen through the contract
 └── remote/             native HTTP dialects for Supermemory, Mem0, and Cognee
+crates/
+└── tinymemory-module/  the TinyBus loadable-module driver. Excluded from the
+                        workspace on purpose — see the note in `Cargo.toml`.
 vendor/
 ├── tinycortex/         the engine, pinned as a submodule
+├── tinyagents/         pinned TinyAgents submodule
 └── tinybus/            pinned TinyBus submodule
 ```
 
+Run `git submodule update --init --recursive` after cloning. Nothing in the
+workspace builds without it — `core` names `tinyagents` and `tinycortex` by
+path through `vendor/`, so an uninitialized checkout fails at manifest
+resolution rather than at compile time, which reads as a confusing error.
+
 ## The contract
 
 `MemoryProvider` is an object-safe trait with **three mandatory** capability

adapters/remote/Cargo.toml

@@ -3,7 +3,7 @@ name = "tinymemory-remote"
 publish = false
 version = "0.1.0"
 edition = "2021"
-rust-version = "1.85"
+rust-version = "1.96"
 license = "MIT"
 description = "HTTP adapters for self-hosted Supermemory, Mem0, and Cognee"
 repository = "https://github.com/tinyhumansai/tinymemory"

adapters/tinycortex/Cargo.toml

@@ -6,7 +6,7 @@ name = "tinymemory-tinycortex"
 publish = false
 version = "0.1.0"
 edition = "2021"
-rust-version = "1.85"
+rust-version = "1.96"
 license = "MIT"
 description = "TinyCortex engine adapter for the TinyMemory contract"
 repository = "https://github.com/tinyhumansai/tinymemory"

api/Cargo.toml

@@ -6,6 +6,7 @@ name = "tinymemory-api"
 publish = false
 version = "0.1.1"
 edition = "2021"
+rust-version = "1.96"
 license = "MIT"
 repository = "https://github.com/tinyhumansai/tinymemory"
 description = "Stable public contracts for the TinyMemory memory system"

conformance/Cargo.toml

@@ -0,0 +1,39 @@
+[package]
+name = "tinymemory-conformance"
+publish = false
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.96"
+license = "MIT"
+description = "Behavioural conformance suite every MemoryProvider driver must pass"
+repository = "https://github.com/tinyhumansai/tinymemory"
+
+[dependencies]
+# The contract under test. This crate deliberately depends on NOTHING else of
+# substance: a conformance suite that pulled in an engine would be unable to
+# prove that a driver is interchangeable, because it would already have chosen
+# one. In particular it must not reach `tinymemory-core`, which links a bundled
+# SQLite and the embedded engine unconditionally (issue #18 §D).
+tinymemory-api = { path = "../api" }
+# `MemoryProvider` and its families are object-safe async traits.
+async-trait = "0.1"
+# `ExportRecord::payload` is a `serde_json::Value`, so the portability
+# assertions have to construct and compare one.
+serde_json = "1"
+# The reference driver maps a poisoned lock onto `MemoryError::Other`, which is
+# `#[from] anyhow::Error`.
+anyhow = "1"
+
+[dev-dependencies]
+# The suite's own tests drive it against the reference drivers.
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+
+[lints.rust]
+unsafe_code = "forbid"
+missing_docs = "warn"
+unreachable_pub = "warn"
+
+[lints.clippy]
+all = { level = "warn", priority = -1 }
+unwrap_used = "warn"
+expect_used = "warn"

conformance/src/lib.rs

@@ -0,0 +1,51 @@
+//! Behavioural conformance for `MemoryProvider` drivers.
+//!
+//! TinyMemory's premise is that an engine can be swapped without the host
+//! learning anything new. [`audit_provider`](tinymemory_api::provider::audit_provider)
+//! checks that a driver's advertised capabilities match its reachable
+//! accessors, which proves the *shape* is honest. Nothing checked that two
+//! drivers answer the same question the same way — and that is the claim the
+//! premise actually rests on.
+//!
+//! This crate is that check. Hand [`assert_provider`] any bound driver and it
+//! drives the contract: the mandatory three families, upsert semantics on
+//! `(namespace, key)`, namespace isolation, provenance preservation, recall
+//! limits, export pagination, and import round-tripping.
+//!
+//! ```no_run
+//! use std::sync::Arc;
+//! use tinymemory_conformance::{assert_provider, InMemoryProvider};
+//!
+//! # async fn run() {
+//! assert_provider(Arc::new(InMemoryProvider::new())).await;
+//! # }
+//! ```
+//!
+//! # What it deliberately does not depend on
+//!
+//! Only `tinymemory-api`. A conformance suite that pulled in an engine could
+//! not prove interchangeability, because it would already have chosen one — and
+//! reaching `tinymemory-core` would drag in a bundled SQLite and the embedded
+//! engine besides (issue #18 §D).
+//!
+//! # Provenance is the sharp one
+//!
+//! [`assert_taint_is_preserved`] is not a formality. A driver that reads back
+//! `Internal` for content stored as `ExternalSync` has laundered external
+//! content into internal-trust content, and every policy gate keyed on taint is
+//! then silently wrong. That failure is invisible until something acts on it.
+
+#![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+pub mod reference;
+pub mod suite;
+
+pub use reference::{InMemoryProvider, REFERENCE_DRIVER_ID};
+pub use suite::{
+    assert_awkward_content_round_trips, assert_capability_audit, assert_export_cursor_terminates,
+    assert_export_import_round_trip, assert_forget_is_idempotent, assert_list_filters_narrow,
+    assert_namespaces_are_isolated, assert_provider, assert_recall_respects_limit_and_namespace,
+    assert_store_get_round_trip, assert_taint_is_preserved,
+    assert_upsert_replaces_rather_than_duplicates,
+};