Merge pull request #20 from YellowSnnowmann/feat/18-e1-conformance-suite

Add a behavioural conformance suite for MemoryProvider drivers (#18 §E1)

Author: senamakel

Cargo.lock

@@ -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.

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/Cargo.toml

@@ -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,
+};