Add workspace-level integration tests against the public API

Issue #18 §E3. `AGENTS.md` mandates a `tests/` directory exercising only the
public API; the repository had none at the root, and `core/tests/` holds
fixtures with no test files.

Four targets, matching the four §E3 names:

`driver_selection.rs` pins admission: reserved ids resolve to fixed classes, an
external driver with no entry is refused fail-closed, an untrusted external
driver is refused even with one, a reserved id's class cannot be overridden by
config, and a class typo is echoed back so the operator can find the line.

`capability_negotiation.rs` covers both directions of the bind-time
negotiation, including a deliberately lying provider that advertises a summary
tree it has no accessor for — the failure `audit_provider` exists to catch, and
which was previously asserted only in unit tests inside the contract crate.

`taint_end_to_end.rs` drives provenance through store, get, list, recall, and
the export/import round trip, at every driver this workspace ships. It also
pins the fail-closed reading of an unknown persisted value, which is the one
direction that cannot be undone.

`null_provider.rs` asserts the compiled-out configuration is genuinely usable:
every mandatory method answers rather than panicking, it reports Ready rather
than a fault, and no optional family is either advertised or reachable.

Two of the four are deliberately narrower than §E3 describes, and both say so
in their module docs. `driver_selection.rs` cannot yet assert that a bound
provider's `driver_id()` matches configuration, because nothing selects an
engine from config — that is §A5. `taint_end_to_end.rs` cannot drive the sync
path, because sync is welded to the engine until §B. Both are written against
current behaviour, per the sequencing note in the issue, and each names where
its missing leg joins.

Refs #18 (§E3)

Author: YellowSnnowmann

Cargo.lock

@@ -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 = []

Cargo.toml

@@ -0,0 +1,197 @@
+//! Capability negotiation: what a host may trust a driver's advertisement for,
+//! and what happens when the advertisement is wrong.
+//!
+//! The contract's premise is that a host negotiates once at bind time and then
+//! filters its own surface from the cached set. That is only safe if the set is
+//! honest, which is what `audit_provider` is for — so these tests pin both the
+//! honest path and the dishonest one.
+
+// A failing assertion in a test *is* a panic; the crate-wide `expect_used` /
+// `unwrap_used` / `panic` lints exist to keep the library from panicking, not
+// the tests. Same allowance, and same reasoning, as `src/registry/test.rs`.
+#![allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
+
+use std::sync::Arc;
+
+use tinymemory::api::capabilities::{Capabilities, Capability};
+use tinymemory::api::health::MemoryHealth;
+use tinymemory::api::null::NullMemoryProvider;
+use tinymemory::api::provider::{audit_provider, MemoryProvider, MemoryTree};
+use tinymemory_conformance::InMemoryProvider;
+
+#[test]
+fn the_reference_drivers_advertise_exactly_what_they_reach() {
+    for provider in [
+        Arc::new(InMemoryProvider::new()) as Arc<dyn MemoryProvider>,
+        Arc::new(NullMemoryProvider::new()),
+    ] {
+        assert!(
+            audit_provider(provider.as_ref()).is_ok(),
+            "driver `{}` failed its audit",
+            provider.driver_id()
+        );
+    }
+}
+
+#[test]
+fn a_host_can_filter_its_surface_from_the_cached_capability_set() {
+    // This is the whole point of negotiating once: a host reads the set at bind
+    // time and never asks again, so the set has to answer both directions.
+    let provider = InMemoryProvider::new();
+    let caps = provider.capabilities();
+
+    for mandatory in Capability::MANDATORY {
+        assert!(
+            caps.contains(mandatory),
+            "{} must be advertised",
+            mandatory.as_str()
+        );
+        assert!(
+            provider.provides(mandatory),
+            "{} must be reachable",
+            mandatory.as_str()
+        );
+    }
+
+    // An optional family this driver does not serve is absent from the set AND
+    // unreachable through its accessor. A host that registered an RPC method
+    // from the set alone would otherwise expose a method that answers errors.
+    assert!(!caps.contains(Capability::Tree));
+    assert!(provider.as_tree().is_none());
+    assert!(!provider.provides(Capability::Tree));
+}
+
+/// A driver that claims a family it cannot serve.
+///
+/// Exists to prove the audit catches it. This is the failure mode the audit was
+/// written for: the claim is cheap to make and, without a check, only surfaces
+/// on the first call — which for a memory family may be days later, on a path
+/// nobody is watching.
+#[derive(Debug, Default)]
+struct LyingProvider(InMemoryProvider);
+
+#[async_trait::async_trait]
+impl tinymemory::api::provider::MemoryCore for LyingProvider {
+    async fn store(
+        &self,
+        namespace: &str,
+        key: &str,
+        content: &str,
+        category: tinymemory::types::MemoryCategory,
+        session_id: Option<&str>,
+        taint: tinymemory::types::MemoryTaint,
+    ) -> Result<(), tinymemory::error::MemoryError> {
+        self.0
+            .store(namespace, key, content, category, session_id, taint)
+            .await
+    }
+    async fn get(
+        &self,
+        namespace: &str,
+        key: &str,
+    ) -> Result<Option<tinymemory::types::MemoryEntry>, tinymemory::error::MemoryError> {
+        self.0.get(namespace, key).await
+    }
+    async fn forget(
+        &self,
+        namespace: &str,
+        key: &str,
+    ) -> Result<bool, tinymemory::error::MemoryError> {
+        self.0.forget(namespace, key).await
+    }
+    async fn list(
+        &self,
+        namespace: Option<&str>,
+        category: Option<&tinymemory::types::MemoryCategory>,
+        session_id: Option<&str>,
+    ) -> Result<Vec<tinymemory::types::MemoryEntry>, tinymemory::error::MemoryError> {
+        self.0.list(namespace, category, session_id).await
+    }
+    async fn namespaces(
+        &self,
+    ) -> Result<Vec<tinymemory::types::NamespaceSummary>, tinymemory::error::MemoryError> {
+        self.0.namespaces().await
+    }
+}
+
+#[async_trait::async_trait]
+impl tinymemory::api::provider::MemoryRecall for LyingProvider {
+    async fn recall(
+        &self,
+        query: &str,
+        limit: usize,
+        opts: &tinymemory::recall::OwnedRecallOpts,
+        scope: Option<&tinymemory::api::provider::SourceScope>,
+    ) -> Result<Vec<tinymemory::types::MemoryEntry>, tinymemory::error::MemoryError> {
+        self.0.recall(query, limit, opts, scope).await
+    }
+}
+
+#[async_trait::async_trait]
+impl tinymemory::api::provider::MemoryPortability for LyingProvider {
+    async fn export_page(
+        &self,
+        cursor: Option<&str>,
+        limit: usize,
+    ) -> Result<tinymemory::api::provider::ExportPage, tinymemory::error::MemoryError> {
+        self.0.export_page(cursor, limit).await
+    }
+    async fn import_records(
+        &self,
+        records: Vec<tinymemory::api::provider::ExportRecord>,
+    ) -> Result<tinymemory::api::provider::ImportOutcome, tinymemory::error::MemoryError> {
+        self.0.import_records(records).await
+    }
+}
+
+#[async_trait::async_trait]
+impl MemoryProvider for LyingProvider {
+    fn driver_id(&self) -> &'static str {
+        "liar"
+    }
+
+    fn capabilities(&self) -> Capabilities {
+        // Claims a summary tree it has no accessor for.
+        Capabilities::mandatory().with(Capability::Tree)
+    }
+
+    async fn health(&self) -> MemoryHealth {
+        MemoryHealth::Ready
+    }
+
+    // `as_tree` deliberately left at its `None` default.
+}
+
+#[test]
+fn a_driver_that_advertises_a_family_it_cannot_serve_fails_the_audit() {
+    let liar = LyingProvider::default();
+    let audit = audit_provider(&liar).expect_err("the audit must catch an overstated capability");
+    assert!(
+        audit.advertised_but_absent.contains(&Capability::Tree),
+        "the audit should name the family: {audit:?}"
+    );
+    assert!(
+        audit.present_but_unadvertised.is_empty(),
+        "nothing was under-advertised here: {audit:?}"
+    );
+}
+
+#[test]
+fn the_audit_failure_renders_something_an_operator_can_act_on() {
+    let audit = audit_provider(&LyingProvider::default())
+        .expect_err("the audit must fail")
+        .to_string();
+    assert!(
+        audit.contains("tree"),
+        "the message should name the family: {audit}"
+    );
+}
+
+/// Compile-time proof that `as_tree` returning `Some` is what "reachable"
+/// means, so the audit is checking the accessor and not a second declaration.
+#[test]
+fn reachability_is_the_accessor_not_a_second_declaration() {
+    let provider = InMemoryProvider::new();
+    let tree: Option<&dyn MemoryTree> = provider.as_tree();
+    assert!(tree.is_none());
+}

tests/capability_negotiation.rs

@@ -0,0 +1,161 @@
+//! Driver admission: which ids exist, what class each binds as, and what is
+//! refused.
+//!
+//! Exercises only the public surface of the `tinymemory` facade.
+//!
+//! # Scope note
+//!
+//! Issue #18 §E3 describes this file as also asserting that "the bound
+//! provider's `driver_id()` matches" the configured id. That step needs
+//! `MemoryHostConfig::memory_provider()` to actually select an engine, which is
+//! §A5 and does not exist yet — `create_memory_client_with_local_ai` still
+//! constructs TinyCortex unconditionally. The issue's own sequencing says to
+//! write these tests "against the *current* behaviour first", so this file
+//! pins what admission does today. The binding half joins it when §A5 lands,
+//! and this file is where it goes.
+
+// A failing assertion in a test *is* a panic; the crate-wide `expect_used` /
+// `unwrap_used` / `panic` lints exist to keep the library from panicking, not
+// the tests. Same allowance, and same reasoning, as `src/registry/test.rs`.
+#![allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
+
+use tinymemory::registry::{
+    ConfigLabels, DriverClass, DriverEntry, DriverRegistry, COGNEE_DRIVER_ID, MEM0_DRIVER_ID,
+    SUPERMEMORY_DRIVER_ID, TINYCORTEX_DRIVER_ID, TRUSTED,
+};
+
+fn labels() -> ConfigLabels<'static> {
+    ConfigLabels {
+        section: "[memory]",
+        drivers: "[memory.drivers]",
+        driver_entry: "[memory.drivers.<id>]",
+    }
+}
+
+fn trusted_external() -> DriverEntry<'static> {
+    DriverEntry {
+        class: None,
+        trust_state: TRUSTED,
+    }
+}
+
+#[test]
+fn a_reserved_embedded_id_is_admitted_without_any_config_entry() {
+    // The embedded default's options live in the host's own config blocks, so
+    // it must not require a `drivers` entry to be selectable at all.
+    let admission = DriverRegistry::builtin()
+        .admit(TINYCORTEX_DRIVER_ID, None, labels())
+        .expect("the built-in embedded engine is admitted");
+    assert_eq!(admission.id, TINYCORTEX_DRIVER_ID);
+    assert_eq!(admission.class, DriverClass::Embedded);
+}
+
+#[test]
+fn the_null_driver_is_admitted_and_is_class_null() {
+    let admission = DriverRegistry::builtin()
+        .admit(tinymemory::registry::NULL_DRIVER_ID, None, labels())
+        .expect("the null driver is admitted");
+    assert_eq!(admission.class, DriverClass::Null);
+}
+
+#[test]
+fn every_reserved_external_id_resolves_to_the_external_class() {
+    let registry = DriverRegistry::builtin();
+    for id in [SUPERMEMORY_DRIVER_ID, MEM0_DRIVER_ID, COGNEE_DRIVER_ID] {
+        let admission = registry
+            .admit(id, Some(trusted_external()), labels())
+            .unwrap_or_else(|reason| panic!("{id} was refused: {}", reason.reason));
+        assert_eq!(admission.class, DriverClass::External, "{id}");
+        assert_eq!(admission.id, id);
+    }
+}
+
+#[test]
+fn an_external_driver_without_an_entry_is_refused_fail_closed() {
+    // The fail-closed half: an external engine needs endpoint, credential and
+    // trust configuration, so admitting it implicitly would bind an
+    // out-of-process backend nobody configured.
+    let reason = DriverRegistry::builtin()
+        .admit(SUPERMEMORY_DRIVER_ID, None, labels())
+        .expect_err("an external driver with no entry must be refused");
+    assert_eq!(reason.configured_driver, SUPERMEMORY_DRIVER_ID);
+    assert!(
+        reason.reason.contains("external"),
+        "the refusal should say why: {}",
+        reason.reason
+    );
+}
+
+#[test]
+fn an_untrusted_external_driver_is_refused_even_with_an_entry() {
+    let entry = DriverEntry {
+        class: None,
+        trust_state: "untrusted",
+    };
+    let reason = DriverRegistry::builtin()
+        .admit(SUPERMEMORY_DRIVER_ID, Some(entry), labels())
+        .expect_err("trust must be raised explicitly before an external bind");
+    assert!(
+        reason.reason.contains(TRUSTED),
+        "the refusal should name the value to set: {}",
+        reason.reason
+    );
+}
+
+#[test]
+fn a_reserved_id_cannot_have_its_class_overridden_by_config() {
+    // A reserved id names a fixed implementation. An explicit `class` line may
+    // confirm it but never override it — otherwise config could run the
+    // embedded engine under the checks meant for an external one.
+    let entry = DriverEntry {
+        class: Some("external"),
+        trust_state: TRUSTED,
+    };
+    let reason = DriverRegistry::builtin()
+        .admit(TINYCORTEX_DRIVER_ID, Some(entry), labels())
+        .expect_err("a reserved id's class must not be overridable");
+    assert!(
+        reason.reason.contains("built in"),
+        "the refusal should explain why: {}",
+        reason.reason
+    );
+}
+
+#[test]
+fn an_unknown_driver_id_is_refused_rather_than_defaulted() {
+    let reason = DriverRegistry::builtin()
+        .admit("not-an-engine", None, labels())
+        .expect_err("an unreserved id with no entry must be refused");
+    assert_eq!(reason.configured_driver, "not-an-engine");
+}
+
+#[test]
+fn an_empty_driver_id_is_refused() {
+    let reason = DriverRegistry::builtin()
+        .admit("   ", None, labels())
+        .expect_err("a blank driver id must be refused");
+    assert!(
+        reason.reason.contains("empty"),
+        "the refusal should name the problem: {}",
+        reason.reason
+    );
+}
+
+#[test]
+fn a_config_class_typo_is_echoed_back_to_the_operator() {
+    // The offending value comes from the host's own config file, not from a
+    // driver or the network, so echoing it discloses nothing the reader did not
+    // write — and without it the message cannot point at the line to fix.
+    let entry = DriverEntry {
+        class: Some("embeded"),
+        trust_state: TRUSTED,
+    };
+    let reason = DriverRegistry::builtin()
+        .admit("some-driver", Some(entry), labels())
+        .expect_err("an unparseable class must be refused");
+    assert!(
+        reason.reason.contains("embeded"),
+        "the refusal should quote the typo: {}",
+        reason.reason
+    );
+}