From dbdb4e86f885da082938eb3826d36101258d3943 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 05:30:48 +0200 Subject: [PATCH 01/11] Huginn holds an instance's persona document, validated and receipted put_persona replaces the mind's gamecult.persona_state.v0 whole through the commit primitive: schema-valid against the published file, personaId is the instance, canonical provenance, CAS on updatedAt, monotone updatedAt. The document is an opaque seventeenth stored type, one per mind. Wire operations persona_get and persona_put, MindStatus.persona, HuginnClient methods and the eureka-state persona tools. Published wire schemas follow in the next commit. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 386 +++++++++++++++++- crates/eureka-state/Cargo.toml | 2 +- crates/eureka-state/src/lib.rs | 25 +- crates/eureka-state/src/main.rs | 72 +++- crates/eureka-state/tests/client.rs | 48 ++- crates/eureka-state/tests/common/mod.rs | 48 ++- crates/eureka-state/tests/mcp.rs | 51 ++- crates/huginn-daemon/src/daemon.rs | 33 ++ crates/huginn-mind/Cargo.toml | 3 +- crates/huginn-mind/src/admission.rs | 82 ++++ crates/huginn-mind/src/envelope.rs | 1 + crates/huginn-mind/src/lib.rs | 2 + crates/huginn-mind/src/mind.rs | 17 +- crates/huginn-mind/src/persona.rs | 506 ++++++++++++++++++++++++ crates/huginn-mind/src/receipt.rs | 10 +- crates/huginn-mind/src/refusal.rs | 13 + crates/huginn-mind/src/wire.rs | 52 ++- 17 files changed, 1309 insertions(+), 42 deletions(-) create mode 100644 crates/huginn-mind/src/persona.rs diff --git a/Cargo.lock b/Cargo.lock index a46de8b..e288372 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -48,6 +48,35 @@ dependencies = [ "version_check", ] +[[package]] +name = "ahash" +version = "0.8.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75" +dependencies = [ + "cfg-if", + "getrandom 0.3.4", + "once_cell", + "serde", + "version_check", + "zerocopy", +] + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "allocator-api2" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923" + [[package]] name = "android_system_properties" version = "0.1.6" @@ -98,6 +127,21 @@ version = "1.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06" +[[package]] +name = "bit-set" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3" +dependencies = [ + "bit-vec", +] + +[[package]] +name = "bit-vec" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7" + [[package]] name = "bitflags" version = "1.3.2" @@ -119,6 +163,12 @@ dependencies = [ "generic-array", ] +[[package]] +name = "borrow-or-share" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc0b364ead1874514c8c2855ab558056ebfeb775653e7ae45ff72f28f8f3166c" + [[package]] name = "borsh" version = "1.8.1" @@ -149,6 +199,12 @@ version = "3.20.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" +[[package]] +name = "bytecount" +version = "0.6.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "175812e0be2bccb6abe50bb8d566126198344f707e304f45c648fd8f2cc0365e" + [[package]] name = "bytes" version = "1.12.1" @@ -357,6 +413,12 @@ dependencies = [ "syn 2.0.119", ] +[[package]] +name = "data-encoding" +version = "2.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06" + [[package]] name = "der" version = "0.7.10" @@ -408,6 +470,15 @@ dependencies = [ "zeroize", ] +[[package]] +name = "email_address" +version = "0.2.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e079f19b08ca6239f47f8ba8509c11cf3ea30095831f7fed61441475edd8c449" +dependencies = [ + "serde", +] + [[package]] name = "equivalent" version = "1.0.2" @@ -455,6 +526,17 @@ dependencies = [ "tokio", ] +[[package]] +name = "fancy-regex" +version = "0.19.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d301f5bf187b3c295fce6468d3875037a0bccc5f6b151c63cac2f85babf21912" +dependencies = [ + "bit-set", + "regex-automata", + "regex-syntax", +] + [[package]] name = "fastrand" version = "2.5.0" @@ -473,6 +555,33 @@ version = "0.1.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3e0f1c7c3a72c66fd80abe965175f7523475c0489a87d3ff9d6e8c87d87a9d2d" +[[package]] +name = "fluent-uri" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bc74ac4d8359ae70623506d512209619e5cf8f347124910440dbc221714b328e" +dependencies = [ + "borrow-or-share", + "ref-cast", + "serde", +] + +[[package]] +name = "foldhash" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb" + +[[package]] +name = "fraction" +version = "0.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e246562084dde8ebbcc943b261c406ce4f68e5032ec28029a251a47d6a295500" +dependencies = [ + "num", + "num-bigint", +] + [[package]] name = "fs2" version = "0.4.3" @@ -599,9 +708,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" dependencies = [ "cfg-if", + "js-sys", "libc", "r-efi 5.3.0", "wasip2", + "wasm-bindgen", ] [[package]] @@ -631,7 +742,7 @@ version = "0.12.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888" dependencies = [ - "ahash", + "ahash 0.7.8", ] [[package]] @@ -639,6 +750,17 @@ name = "hashbrown" version = "0.17.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" +dependencies = [ + "allocator-api2", + "equivalent", + "foldhash", +] + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" [[package]] name = "hmac" @@ -693,6 +815,7 @@ dependencies = [ "cultcache-rs", "cultnet-rs", "eureka-pipeline", + "jsonschema", "rmp-serde", "schemars", "serde", @@ -776,6 +899,59 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "jsonschema" +version = "0.58.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f622c574a29fb3034a0a90645afee194dfedc75fc124228801b6e77041075bd1" +dependencies = [ + "ahash 0.8.12", + "bytecount", + "data-encoding", + "email_address", + "fancy-regex", + "fraction", + "getrandom 0.3.4", + "itoa", + "jsonschema-regex", + "jsonschema-value", + "num-cmp", + "num-traits", + "percent-encoding", + "referencing", + "regex", + "serde", + "serde_json", + "strum", + "unicode-general-category", + "uuid-simd", +] + +[[package]] +name = "jsonschema-regex" +version = "0.58.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a968fffd387b2ab005bf00c1851f5d26e90df05b6f7ad609ed0d620033cca5e7" +dependencies = [ + "regex-syntax", +] + +[[package]] +name = "jsonschema-value" +version = "0.58.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39b7670345e5ce87371339d13705dbb9276b7e3e934bbe1efa2c6734a1f65a96" +dependencies = [ + "ahash 0.8.12", + "bytecount", + "fraction", + "getrandom 0.3.4", + "num-cmp", + "num-traits", + "serde_json", + "zmij", +] + [[package]] name = "libc" version = "0.2.189" @@ -824,6 +1000,12 @@ version = "2.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" +[[package]] +name = "micromap" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a86d3146ed3995b5913c414f6664344b9617457320782e64f0bb44afd49d74" + [[package]] name = "mind-body" version = "0.1.0" @@ -838,6 +1020,75 @@ dependencies = [ "tempfile", ] +[[package]] +name = "num" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "35bd024e8b2ff75562e5f34e7f4905839deb4b22955ef5e73d2fea1b9813cb23" +dependencies = [ + "num-bigint", + "num-complex", + "num-integer", + "num-iter", + "num-rational", + "num-traits", +] + +[[package]] +name = "num-bigint" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367" +dependencies = [ + "num-integer", + "num-traits", +] + +[[package]] +name = "num-cmp" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63335b2e2c34fae2fb0aa2cecfd9f0832a1e24b3b32ecec612c3426d46dc8aaa" + +[[package]] +name = "num-complex" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-integer" +version = "0.1.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-iter" +version = "0.1.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c92800bd69a1eac91786bcfe9da64a897eb72911b8dc3095decbd07429e8048b" +dependencies = [ + "num-integer", + "num-traits", +] + +[[package]] +name = "num-rational" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824" +dependencies = [ + "num-bigint", + "num-integer", + "num-traits", +] + [[package]] name = "num-traits" version = "0.2.19" @@ -859,6 +1110,12 @@ version = "0.3.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381" +[[package]] +name = "outref" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e" + [[package]] name = "parking_lot" version = "0.11.2" @@ -867,7 +1124,17 @@ checksum = "7d17b78036a60663b797adeaee46f5c9dfebb86948d1255007a1d6be0271ff99" dependencies = [ "instant", "lock_api", - "parking_lot_core", + "parking_lot_core 0.8.6", +] + +[[package]] +name = "parking_lot" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a" +dependencies = [ + "lock_api", + "parking_lot_core 0.9.12", ] [[package]] @@ -879,11 +1146,24 @@ dependencies = [ "cfg-if", "instant", "libc", - "redox_syscall", + "redox_syscall 0.2.16", "smallvec", "winapi", ] +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall 0.5.18", + "smallvec", + "windows-link", +] + [[package]] name = "pastey" version = "0.2.3" @@ -1049,6 +1329,15 @@ dependencies = [ "bitflags 1.3.2", ] +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags 2.13.2", +] + [[package]] name = "reed-solomon-erasure" version = "6.0.0" @@ -1057,7 +1346,7 @@ checksum = "7263373d500d4d4f505d43a2a662d475a894aa94503a1ee28e9188b5f3960d4f" dependencies = [ "libm", "lru", - "parking_lot", + "parking_lot 0.11.2", "smallvec", "spin", ] @@ -1082,6 +1371,52 @@ dependencies = [ "syn 3.0.5", ] +[[package]] +name = "referencing" +version = "0.58.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "558f3855529c0a7e78a48e409fa653456e55f1b167eab4109c16a255b7727e3f" +dependencies = [ + "ahash 0.8.12", + "fluent-uri", + "getrandom 0.3.4", + "hashbrown 0.17.1", + "itoa", + "micromap", + "parking_lot 0.12.5", + "percent-encoding", + "serde_json", +] + +[[package]] +name = "regex" +version = "1.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + [[package]] name = "rmcp" version = "2.2.0" @@ -1383,6 +1718,27 @@ version = "0.11.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" +[[package]] +name = "strum" +version = "0.28.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9628de9b8791db39ceda2b119bbe13134770b56c138ec1d3af810d045c04f9bd" +dependencies = [ + "strum_macros", +] + +[[package]] +name = "strum_macros" +version = "0.28.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab85eea0270ee17587ed4156089e10b9e6880ee688791d45a905f5b1ca36f664" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "subtle" version = "2.6.1" @@ -1547,6 +1903,12 @@ version = "1.20.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" +[[package]] +name = "unicode-general-category" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b993bddc193ae5bd0d623b49ec06ac3e9312875fdae725a975c51db1cc1677f" + [[package]] name = "unicode-ident" version = "1.0.24" @@ -1605,12 +1967,28 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "uuid-simd" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23b082222b4f6619906941c17eb2297fff4c2fb96cb60164170522942a200bd8" +dependencies = [ + "outref", + "vsimd", +] + [[package]] name = "version_check" version = "0.9.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" +[[package]] +name = "vsimd" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c3082ca00d5a5ef149bb8b555a72ae84c9c59f7250f013ac822ac2e49b19c64" + [[package]] name = "wasi" version = "0.11.1+wasi-snapshot-preview1" diff --git a/crates/eureka-state/Cargo.toml b/crates/eureka-state/Cargo.toml index 71ddd71..a1c5fb6 100644 --- a/crates/eureka-state/Cargo.toml +++ b/crates/eureka-state/Cargo.toml @@ -12,7 +12,7 @@ publish.workspace = true # verification are `cultnet-rs`'s. # # The MCP server (`main.rs`, the `eureka-state` binary) is the client's one -# consumer: four tools over stdio, one per wire operation, holding no state. +# consumer: six tools over stdio, one per wire operation, holding no state. [dependencies] anyhow = "1" cultnet-rs.workspace = true diff --git a/crates/eureka-state/src/lib.rs b/crates/eureka-state/src/lib.rs index 5d0d502..c73300b 100644 --- a/crates/eureka-state/src/lib.rs +++ b/crates/eureka-state/src/lib.rs @@ -27,7 +27,8 @@ use cultnet_rs::{ }; use huginn_mind::envelope::{OperationFailure, decode_response, encode_request}; use huginn_mind::eureka_pipeline::Slug; -use huginn_mind::{HuginnMindRequest, HuginnMindResponse, MAX_DEFERRED_BODY_BYTES}; +use huginn_mind::{HuginnMindRequest, HuginnMindResponse, MAX_DEFERRED_BODY_BYTES, PipelineProvenance}; +use serde_json::Value; /// The correlation key of the one request a session carries. const MESSAGE_ID: &str = "eureka-state-call"; @@ -108,6 +109,28 @@ impl HuginnClient { &self.instance } + /// The mind's persona document: `Persona(None)` until the first put. + pub fn persona_get(&self) -> Result { + self.call(HuginnMindRequest::PersonaGet { instance: self.instance.clone() }) + } + + /// Replaces the mind's persona document whole. `expected_updated_at` is + /// the stored document's `updatedAt`, none for the first put; a stale one + /// comes back as `PersonaPut(Refused(PersonaStale { .. }))`, an answer. + pub fn persona_put( + &self, + provenance: PipelineProvenance, + state: Value, + expected_updated_at: Option, + ) -> Result { + self.call(HuginnMindRequest::PersonaPut { + instance: self.instance.clone(), + provenance, + state, + expected_updated_at, + }) + } + pub fn call(&self, request: HuginnMindRequest) -> Result { let deadline = Instant::now() + self.timeout; let unavailable = diff --git a/crates/eureka-state/src/main.rs b/crates/eureka-state/src/main.rs index f48b8a0..2138fa5 100644 --- a/crates/eureka-state/src/main.rs +++ b/crates/eureka-state/src/main.rs @@ -1,7 +1,7 @@ -//! `eureka-state`: Huginn's mind as four MCP tools over stdio. +//! `eureka-state`: Huginn's mind as six MCP tools over stdio. //! -//! One tool per wire operation (`whoami`, `admit`, `view`, `query`), each a -//! `HuginnClient` call and nothing else. The declared identity is this +//! One tool per wire operation (`whoami`, `admit`, `view`, `query`, +//! `persona_get`, `persona_put`), each a `HuginnClient` call and nothing else. The declared identity is this //! process's configuration, not a per-call argument: `EUREKA_INSTANCE` names //! the mind and `HUGINN_ENDPOINT` (`rudp://host:port`) the daemon that holds //! it. The server fills in `instance` and `provenance.tool`, so a caller can @@ -73,6 +73,21 @@ struct AdmitInput { documents: Vec, } +#[derive(Deserialize, JsonSchema)] +struct PersonaPutInput { + /// The faculty the put is attributed to. Attribution, not authority. + faculty: Faculty, + /// The putting agent's name. + agent: Short, + /// The putting session, recorded on the receipt. + session: Short, + /// The whole `gamecult.persona_state.v0` document. It replaces the stored + /// one; there is no partial write. + state: Value, + /// The stored document's `updatedAt`; omit it for the first put. + expected_updated_at: Option, +} + #[derive(Deserialize, JsonSchema)] struct ViewInput { /// The document's id, as a query or an admission returned it. @@ -166,17 +181,32 @@ impl EurekaState { /// One wire call for the configured instance. The request is built from /// that instance, never from anything the caller sent. - async fn call(&self, request: impl FnOnce(Slug) -> HuginnMindRequest) -> Result { + async fn call( + &self, + request: impl FnOnce(Slug) -> HuginnMindRequest + Send + 'static, + ) -> Result { + self.ask(move |client| client.call(request(client.instance().clone()))).await + } + + /// One `HuginnClient` call for the configured instance, off the async + /// thread. + async fn ask( + &self, + call: impl FnOnce(&HuginnClient) -> Result + Send + 'static, + ) -> Result { let client = self.settings.client.as_ref().map_err(|detail| Trouble::Misconfigured(detail.clone()))?.clone(); - let request = request(client.instance().clone()); - tokio::task::spawn_blocking(move || client.call(request)) + tokio::task::spawn_blocking(move || call(&client)) .await .map_err(|error| Trouble::Internal(error.to_string()))? .map_err(Trouble::Client) } - async fn answer(&self, request: impl FnOnce(Slug) -> HuginnMindRequest) -> CallToolResult { - match self.call(request).await { + async fn answer(&self, request: impl FnOnce(Slug) -> HuginnMindRequest + Send + 'static) -> CallToolResult { + Self::replied(self.call(request).await) + } + + fn replied(result: Result) -> CallToolResult { + match result { Ok(response) => reply(payload(response), false), Err(trouble) => reply(trouble.body(), true), } @@ -191,6 +221,8 @@ fn payload(response: HuginnMindResponse) -> Value { HuginnMindResponse::Admit(outcome) => serde_json::to_value(outcome), HuginnMindResponse::View(view) => serde_json::to_value(view), HuginnMindResponse::Query(page) => serde_json::to_value(page), + HuginnMindResponse::Persona(view) => serde_json::to_value(view), + HuginnMindResponse::PersonaPut(outcome) => serde_json::to_value(outcome), other => serde_json::to_value(other), }; value.expect("wire types serialize") @@ -259,6 +291,28 @@ impl EurekaState { }) .await } + + #[tool( + description = "The mind's persona document (gamecult.persona_state.v0) with its updatedAt and the receipt of the put that wrote it. null until the first put." + )] + async fn persona_get(&self) -> CallToolResult { + Self::replied(self.ask(HuginnClient::persona_get).await) + } + + #[tool( + description = "Replace the mind's persona document whole. The document must pass the published schema, name this instance as personaId, carry provenance.authority canonical, and have an updatedAt later than the stored one; expected_updated_at must be the stored updatedAt (omit it for the first put). A refusal is an answer; a stale put names the stored updatedAt to retry against." + )] + async fn persona_put(&self, Parameters(input): Parameters) -> CallToolResult { + let provenance = PipelineProvenance { + faculty: input.faculty, + agent: input.agent, + session: input.session, + tool: Short(TOOL.into()), + }; + Self::replied( + self.ask(move |client| client.persona_put(provenance, input.state, input.expected_updated_at)).await, + ) + } } /// Every tool error is a typed JSON body. The ones this server writes already @@ -289,7 +343,7 @@ impl ServerHandler for EurekaState { fn get_info(&self) -> ServerInfo { ServerInfo::new(ServerCapabilities::builder().enable_tools().build()).with_instructions( - "Huginn's typed mind for this instance: whoami, admit, view, query. Refusals are answers; isError means the daemon could not be reached or rejected the request.", + "Huginn's typed mind for this instance: whoami, admit, view, query, persona_get, persona_put. Refusals are answers; isError means the daemon could not be reached or rejected the request.", ) } } diff --git a/crates/eureka-state/tests/client.rs b/crates/eureka-state/tests/client.rs index 123c508..38550b9 100644 --- a/crates/eureka-state/tests/client.rs +++ b/crates/eureka-state/tests/client.rs @@ -19,7 +19,9 @@ use huginn_mind::eureka_pipeline::{ PipelineCutSpec, PipelineDocument, PipelineKind, PipelineRef, Short, StructuralDelta, Title, VerificationTest, }; -use huginn_mind::{DeferredAnswer, HuginnMindRequest, HuginnMindResponse, MindRefusal, PipelineAdmissionOutcome}; +use huginn_mind::{ + DeferredAnswer, HuginnMindRequest, HuginnMindResponse, MindRefusal, PersonaPutOutcome, PipelineAdmissionOutcome, +}; mod common; use common::*; @@ -195,6 +197,50 @@ fn every_operation_round_trips_against_a_live_daemon() { assert_eq!(view.id, campaign_ref); } +/// The persona methods against a live daemon over the socket: put then get +/// returns the value and the receipt, and a stale put or another mind's name is +/// an answer, not an error. +#[test] +fn client_persona_round_trip_against_a_live_daemon() { + const T1: &str = "2026-10-10T10:00:00Z"; + const T2: &str = "2026-10-10T10:00:01Z"; + let (root, daemon) = mind(vec![]); + let server = serve(root, daemon); + let client = client(server.addr); + + assert_eq!(client.persona_get().unwrap(), HuginnMindResponse::Persona(None)); + let HuginnMindResponse::PersonaPut(PersonaPutOutcome::Committed { receipt_id }) = + client.persona_put(provenance(), persona(INSTANCE, T1), None).unwrap() + else { + panic!("the first put commits"); + }; + let HuginnMindResponse::Persona(Some(view)) = client.persona_get().unwrap() else { panic!("the persona is stored") }; + assert_eq!(view.value, persona(INSTANCE, T1)); + assert_eq!((view.updated_at.as_str(), view.receipt_id.as_str()), (T1, receipt_id.as_str())); + let HuginnMindResponse::Whoami(status) = client.call(HuginnMindRequest::Whoami).unwrap() else { panic!("a status") }; + assert_eq!(status.persona.as_deref(), Some(T1)); + + // A stale put is an answer. + assert_eq!( + client.persona_put(provenance(), persona(INSTANCE, T2), None).unwrap(), + HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(MindRefusal::PersonaStale { stored: Some(T1.into()) })) + ); + let HuginnMindResponse::PersonaPut(PersonaPutOutcome::Committed { .. }) = + client.persona_put(provenance(), persona(INSTANCE, T2), Some(T1.into())).unwrap() + else { + panic!("a put that read the stored document commits"); + }; + + // Another mind's name is an answer too. + let other = HuginnClient::new(server.addr, slug(OTHER), TIMEOUT); + let foreign = MindRefusal::ForeignInstance { declared: OTHER.into(), mind: INSTANCE.into() }; + assert_eq!(other.persona_get().unwrap(), HuginnMindResponse::Refused(foreign.clone())); + assert_eq!( + other.persona_put(provenance(), persona(INSTANCE, "2026-10-10T10:00:02Z"), Some(T2.into())).unwrap(), + HuginnMindResponse::Refused(foreign) + ); +} + /// A refusal is data. A read that names another mind, a write that declares /// another mind, and a document the mind does not hold each come back as `Ok`. #[test] diff --git a/crates/eureka-state/tests/common/mod.rs b/crates/eureka-state/tests/common/mod.rs index ca0e19b..cb09085 100644 --- a/crates/eureka-state/tests/common/mod.rs +++ b/crates/eureka-state/tests/common/mod.rs @@ -21,6 +21,7 @@ use huginn_mind::{ Faculty, HuginnMindRequest, HuginnMindResponse, IndexStatus, Mind, MindStore, OwnedRedbMessagePackBackingStore, PipelineAdmissionBatch, PipelineAdmissionOutcome, PipelineProvenance, }; +use serde_json::{Value, json}; use tempfile::TempDir; pub const INSTANCE: &str = "eureka"; @@ -38,19 +39,46 @@ pub fn identity(name: &str) -> PipelineDocument { }) } -pub fn batch(instance: &str, documents: Vec) -> PipelineAdmissionBatch { - PipelineAdmissionBatch { - instance: slug(instance), - provenance: PipelineProvenance { - faculty: Faculty::Hands, - agent: Short("claude".into()), - session: Short("session-1".into()), - tool: Short("admit".into()), - }, - documents, +pub fn provenance() -> PipelineProvenance { + PipelineProvenance { + faculty: Faculty::Hands, + agent: Short("claude".into()), + session: Short("session-1".into()), + tool: Short("admit".into()), } } +pub fn batch(instance: &str, documents: Vec) -> PipelineAdmissionBatch { + PipelineAdmissionBatch { instance: slug(instance), provenance: provenance(), documents } +} + +/// A minimal `gamecult.persona_state.v0` document: the published schema's +/// required fields and nothing else. +pub fn persona(id: &str, updated_at: &str) -> Value { + json!({ + "schemaVersion": "gamecult.persona_state.v0", + "provenance": { + "sourceSystem": "huginn", "sourceDocumentId": id, "sourceUpdatedAt": updated_at, + "exportedAt": updated_at, "authority": "canonical" + }, + "personaId": id, + "publicName": "Test Persona", + "presentation": { "voiceSummary": "plain" }, + "activationProfile": { + "underlyingOrganization": {}, "stableDispositions": {}, "behavioralDimensions": {}, + "presentationStrategy": {}, "voiceStyle": {}, "situationalState": {} + }, + "thoughtMemory": { "shortTerm": [], "memories": [], "incubation": [] }, + "agencyPressure": { "pressures": [] }, + "candidateActions": { "actions": [] }, + "affect": { + "needs": [], "socialBonds": [], "statusReads": [], "moodDimensions": [], + "socialBiases": [], "doctrineStances": [] + }, + "updatedAt": updated_at + }) +} + /// No index: the client's subject is the transport, not the projection. pub struct Inert; diff --git a/crates/eureka-state/tests/mcp.rs b/crates/eureka-state/tests/mcp.rs index adfc2f8..f4b96d3 100644 --- a/crates/eureka-state/tests/mcp.rs +++ b/crates/eureka-state/tests/mcp.rs @@ -148,15 +148,15 @@ fn keys_below_root(schema: &Value, key: &str) -> usize { schema.as_object().unwrap().values().map(|inner| count(inner, key)).sum() } -/// Four tools, each input schema a self-contained document: every `$ref` is +/// Six tools, each input schema a self-contained document: every `$ref` is /// internal and resolves, and the selection's definitions are bundled in. #[test] -fn tools_list_offers_four_tools_with_self_contained_schemas() { +fn tools_list_offers_six_tools_with_self_contained_schemas() { let mut mcp = Mcp::at(INSTANCE, closed_port()); let listed = mcp.rpc("tools/list", json!({})); let tools = listed["result"]["tools"].as_array().expect("tools"); let names: BTreeSet<&str> = tools.iter().map(|tool| tool["name"].as_str().unwrap()).collect(); - assert_eq!(names, BTreeSet::from(["whoami", "admit", "view", "query"])); + assert_eq!(names, BTreeSet::from(["whoami", "admit", "view", "query", "persona_get", "persona_put"])); for tool in tools { let schema = &tool["inputSchema"]; let mut found = Vec::new(); @@ -248,6 +248,49 @@ fn every_tool_round_trips_against_a_live_daemon() { assert_eq!(counted["status"]["receipts"], json!(3)); } +/// The persona tools against a live daemon: the document, the stale answer, +/// and `whoami` showing the stored `updatedAt`. The server fills in the +/// instance and the tool, so the asker names neither. +#[test] +fn the_persona_tools_round_trip_against_a_live_daemon() { + const T1: &str = "2026-10-10T10:00:00Z"; + const T2: &str = "2026-10-10T10:00:01Z"; + let (root, daemon) = mind(vec![]); + let server = serve(root, daemon); + let mut mcp = Mcp::at(INSTANCE, server.addr); + let put = |state: Value, expected: Option<&str>| { + let mut arguments = json!({ "faculty": "SelfFaculty", "agent": "claude", "session": "session-7", "state": state }); + if let Some(expected) = expected { + arguments["expected_updated_at"] = json!(expected); + } + arguments + }; + + let (error, nothing) = mcp.call("persona_get", json!({})); + assert!(!error); + assert_eq!(nothing, Value::Null); + let (_, whoami) = mcp.call("whoami", json!({})); + assert_eq!(whoami["status"]["persona"], Value::Null); + + let (error, committed) = mcp.call("persona_put", put(persona(INSTANCE, T1), None)); + assert!(!error); + let receipt = committed["Committed"]["receipt_id"].as_str().expect("committed").to_string(); + + let (error, view) = mcp.call("persona_get", json!({})); + assert!(!error); + assert_eq!(view["value"], persona(INSTANCE, T1)); + assert_eq!((view["updated_at"].as_str(), view["receipt_id"].as_str()), (Some(T1), Some(receipt.as_str()))); + let (_, whoami) = mcp.call("whoami", json!({})); + assert_eq!(whoami["status"]["persona"], json!(T1)); + + let (error, stale) = mcp.call("persona_put", put(persona(INSTANCE, T2), None)); + assert!(!error, "a stale put is an answer"); + assert_eq!(stale["Refused"]["PersonaStale"]["stored"], json!(T1)); + + let (_, page) = mcp.call("query", json!({ "selection": { "schemas": ["epiphany.pipeline.instance.v2"] } })); + assert_eq!(page["matched"], json!(1), "the persona is not a pipeline document"); +} + /// Declared identity is configuration, not a per-call argument. Input that /// names another instance, or another tool, changes neither: the batch is /// admitted for the configured instance, and the receipt says `eureka-state`. @@ -367,6 +410,8 @@ fn bad_configuration_is_served_and_reported() { ("view", json!({ "id": absent() })), ("query", json!({ "selection": {} })), ("admit", faculty_args(vec![])), + ("persona_get", json!({})), + ("persona_put", json!({ "faculty": "Hands", "agent": "claude", "session": "s", "state": {} })), ] { let (error, refusal) = mcp.call(tool, arguments); assert!(error, "{tool}: {expected}"); diff --git a/crates/huginn-daemon/src/daemon.rs b/crates/huginn-daemon/src/daemon.rs index 614129e..ef6f8b9 100644 --- a/crates/huginn-daemon/src/daemon.rs +++ b/crates/huginn-daemon/src/daemon.rs @@ -153,6 +153,13 @@ impl> Daemon { Ok(view) => HuginnMindResponse::View(view), Err(refusal) => HuginnMindResponse::Refused(refusal), }, + HuginnMindRequest::PersonaGet { .. } => match self.mind.persona() { + Ok(view) => HuginnMindResponse::Persona(view), + Err(refusal) => HuginnMindResponse::Refused(refusal), + }, + HuginnMindRequest::PersonaPut { instance, provenance, state, expected_updated_at } => { + HuginnMindResponse::PersonaPut(self.mind.put_persona(&instance, state, expected_updated_at, provenance, now)) + } HuginnMindRequest::Query { selection, semantic: None, .. } => match self.mind.query(&selection) { Ok(page) => HuginnMindResponse::Query(page), Err(refusal) => HuginnMindResponse::Refused(refusal), @@ -581,6 +588,7 @@ pub(crate) mod tests { documents: 1, receipts: 1, index: IndexStatus::Current, + persona: None, } ); assert_eq!(daemon.runtime_id(), "huginn-yggdrasil"); @@ -672,6 +680,31 @@ pub(crate) mod tests { assert_eq!(status(&mut daemon).documents, 1, "nothing landed"); } + /// The persona operations name an instance like every other read: another + /// mind's name is refused before the mind is asked, and a mind with no + /// persona answers `Persona(None)`. + #[test] + fn the_persona_operations_name_this_mind_and_an_empty_mind_has_none() { + let (_root, mut daemon) = seeded(); + assert_eq!( + daemon.handle(HuginnMindRequest::PersonaGet { instance: slug(INSTANCE) }, now()).answered(), + HuginnMindResponse::Persona(None) + ); + let foreign = MindRefusal::ForeignInstance { declared: OTHER.into(), mind: INSTANCE.into() }; + assert_eq!( + daemon.handle(HuginnMindRequest::PersonaGet { instance: slug(OTHER) }, now()).answered(), + HuginnMindResponse::Refused(foreign.clone()) + ); + let put = HuginnMindRequest::PersonaPut { + instance: slug(OTHER), + provenance: provenance(), + state: serde_json::Value::Null, + expected_updated_at: None, + }; + assert_eq!(daemon.handle(put, now()).answered(), HuginnMindResponse::Refused(foreign)); + assert_eq!(status(&mut daemon).persona, None); + } + /// A declared instance outside `Slug`'s grammar is refused by its own /// name, `InvalidFormat`, on the read path, before the identity /// comparison ever runs: it is not merely a foreign mind, it names no diff --git a/crates/huginn-mind/Cargo.toml b/crates/huginn-mind/Cargo.toml index 104665f..bcbfde6 100644 --- a/crates/huginn-mind/Cargo.toml +++ b/crates/huginn-mind/Cargo.toml @@ -21,13 +21,14 @@ chrono = "0.4.44" cultcache-rs.workspace = true cultnet-rs.workspace = true eureka-pipeline = { path = "../eureka-pipeline" } +jsonschema = { version = "0.58.6", default-features = false } rmp-serde = "1" schemars = "1" serde = { version = "1", features = ["derive"] } +serde_json = "1" sha2 = "0.10" [dev-dependencies] -serde_json = "1" tempfile = "3" # `test-support` exposes `Mind::store_path_for` and `Mind::open_with`, a diff --git a/crates/huginn-mind/src/admission.rs b/crates/huginn-mind/src/admission.rs index 5149f77..961b8b7 100644 --- a/crates/huginn-mind/src/admission.rs +++ b/crates/huginn-mind/src/admission.rs @@ -37,9 +37,11 @@ use eureka_pipeline::{ }; use schemars::JsonSchema; use serde::{Deserialize, Serialize}; +use serde_json::Value; use crate::docs::{CitationRole, Docs, Staged, citations, kind_of_id, outcome_citations}; use crate::mind::{HuginnMindEpoch, Mind, unavailable}; +use crate::persona::{self, HuginnPersonaEntry, PersonaPutOutcome}; use crate::receipt::{self, CommitOutcome, PipelineProvenance}; use crate::refusal::MindRefusal; use crate::store::MindStore; @@ -178,6 +180,86 @@ impl Mind { CommitOutcome::Conflict(identities) => Ok(PipelineAdmissionOutcome::Conflict { identities }), } } + + /// Replaces the mind's persona document whole, or refuses. One door for + /// the one document a mind holds, outside every pipeline batch: the same + /// instance and provenance checks as `admit`, then the persona's five + /// rules in order (schema-valid, `personaId` is this mind, canonical + /// provenance, `expected_updated_at` is the stored `updatedAt`, the new + /// `updatedAt` is later), then the same commit primitive. The stored + /// document is the commit's strong read, so the swap fails if it changed. + pub fn put_persona( + &mut self, + instance: &Slug, + state: Value, + expected_updated_at: Option, + provenance: PipelineProvenance, + now: DateTime, + ) -> PersonaPutOutcome { + match self.persona_steps(instance, state, expected_updated_at, provenance, now) { + Ok(receipt_id) => PersonaPutOutcome::Committed { receipt_id }, + Err(refusal) => PersonaPutOutcome::Refused(refusal), + } + } + + fn persona_steps( + &mut self, + instance: &Slug, + state: Value, + expected_updated_at: Option, + provenance: PipelineProvenance, + now: DateTime, + ) -> Result { + self.require_instance(instance)?; + refuse_provenance(&provenance)?; + // The persona rides a mind that has its identity (A6's analogue). + if self.is_empty() { + return Err(MindRefusal::MissingIdentity); + } + // P1 + persona::validate_shape(&state)?; + // P2 + let mind = self.instance().clone(); + if state.get("personaId").and_then(Value::as_str) != Some(mind.0.as_str()) { + return Err(MindRefusal::PersonaForeign { instance: mind.0 }); + } + // P3 + if state.pointer("/provenance/authority").and_then(Value::as_str) != Some("canonical") { + return Err(MindRefusal::PersonaNotCanonical); + } + // P4 + let stored = self.stored_updated_at()?; + if stored != expected_updated_at { + return Err(MindRefusal::PersonaStale { stored }); + } + // P5 + if let Some(stored) = &stored { + let instant = |stamp: &str| { + DateTime::parse_from_rfc3339(stamp).map_err(|_| MindRefusal::PersonaInvalid { + path: "/updatedAt".into(), + message: "is not an RFC 3339 date-time".into(), + }) + }; + let offered = state.get("updatedAt").and_then(Value::as_str).map(instant).transpose()?; + if offered <= Some(instant(stored)?) { + return Err(MindRefusal::PersonaInvalid { + path: "/updatedAt".into(), + message: "must be later than the stored updatedAt".into(), + }); + } + } + let (envelope, _) = self + .cache() + .prepare_entry_named(mind.0.clone(), &HuginnPersonaEntry { value: state }) + .map_err(unavailable)?; + let strong_reads = self.persona_envelope().cloned().into_iter().collect::>(); + let writes = vec![envelope]; + let candidate = receipt::candidate(&mind, provenance, &strong_reads, &writes, receipt::head(self)? + 1, now)?; + match receipt::commit(self, candidate, strong_reads, writes)? { + CommitOutcome::Committed(receipt) => Ok(receipt.receipt_id), + CommitOutcome::Conflict(_) => Err(MindRefusal::PersonaStale { stored: self.stored_updated_at()? }), + } + } } /// The bound `eureka_pipeline::Short` declares, in UTF-8 bytes. The leaf diff --git a/crates/huginn-mind/src/envelope.rs b/crates/huginn-mind/src/envelope.rs index 8152a54..a314e37 100644 --- a/crates/huginn-mind/src/envelope.rs +++ b/crates/huginn-mind/src/envelope.rs @@ -184,6 +184,7 @@ mod tests { documents: 0, receipts: 0, index: crate::wire::IndexStatus::Current, + persona: None, }), "accepted", ), diff --git a/crates/huginn-mind/src/lib.rs b/crates/huginn-mind/src/lib.rs index 5aa59f7..0e9dc19 100644 --- a/crates/huginn-mind/src/lib.rs +++ b/crates/huginn-mind/src/lib.rs @@ -30,6 +30,7 @@ mod docs; pub mod envelope; pub mod index; pub mod mind; +pub mod persona; mod rows; pub mod query; pub mod receipt; @@ -44,6 +45,7 @@ pub use docs::CitationRole; pub use index::{INDEX_TEXT_MAX_BYTES, INDEX_TEXT_VERSION, IndexEntry, index_text}; pub use admission::{BATCH_MAX, PipelineAdmissionBatch, PipelineAdmissionOutcome}; pub use mind::{HuginnMindEpoch, Mind}; +pub use persona::{PersonaPutOutcome, PersonaStateView}; pub use query::{ AdmissionFacts, PipelineDocumentSummary, PipelineDocumentView, PipelineEdge, PipelineFacts, PipelinePageItems, PipelineSelectionPage, PipelineStatus, PipelineStatusSummary, Ranked, SUMMARY_MAX_BYTES, SemanticQuery, diff --git a/crates/huginn-mind/src/mind.rs b/crates/huginn-mind/src/mind.rs index a026dd1..c33ee6a 100644 --- a/crates/huginn-mind/src/mind.rs +++ b/crates/huginn-mind/src/mind.rs @@ -15,6 +15,7 @@ use cultcache_rs::{CultCache, CultCacheEnvelope, DatabaseEntry, OwnedRedbMessage use cultnet_rs::CursorKey; use eureka_pipeline::{PIPELINE_SCHEMA_EPOCH, PipelineDocument, PipelineKind, Slug, register_pipeline_document_types}; +use crate::persona::HuginnPersonaEntry; use crate::receipt::HuginnCommitReceipt; use crate::refusal::MindRefusal; use crate::store::MindStore; @@ -71,20 +72,22 @@ fn require_grammatical_slug(field: &str, declared: &Slug) -> Result<(), MindRefu }) } -/// A cache that knows the sixteen types a mind's store may hold: the leaf's -/// fourteen through its registrar, the epoch record and the commit receipt. -/// It is the cache every envelope is prepared against. +/// A cache that knows the seventeen types a mind's store may hold: the leaf's +/// fourteen through its registrar, the epoch record, the commit receipt and +/// the persona entry. It is the cache every envelope is prepared against. pub(crate) fn schema_cache() -> Result { let mut cache = CultCache::new(); register_pipeline_document_types(&mut cache).map_err(unavailable)?; cache.register_entry_type::().map_err(unavailable)?; cache.register_entry_type::().map_err(unavailable)?; + cache.register_entry_type::().map_err(unavailable)?; Ok(cache) } fn is_known_type(type_id: &str) -> bool { type_id == HuginnMindEpoch::TYPE || type_id == HuginnCommitReceipt::TYPE + || type_id == HuginnPersonaEntry::TYPE || PipelineKind::ALL.iter().any(|kind| kind.type_id() == type_id) } @@ -168,7 +171,7 @@ impl Mind { /// Fail-closed, in this order, nothing attached until every step passes: /// pull the raw envelopes; if anything is stored, exactly one epoch - /// record at the current epoch; every type is one of the sixteen; and + /// record at the current epoch; every type is one of the seventeen; and /// exactly one `instance` document naming the declared instance; then /// register, attach and pull. The epoch gate runs first so a store /// written at a foreign epoch is refused as `ForeignEpoch`, never as @@ -276,11 +279,15 @@ impl Mind { } /// Step 3: a runtime store, a Mind store or any other file passed by mistake -/// dies on its first foreign type. +/// dies on its first foreign type, and a second persona envelope is no mind's: +/// a mind holds one. fn refuse_foreign_types(raw: &[CultCacheEnvelope]) -> Result<(), MindRefusal> { if let Some(foreign) = raw.iter().find(|envelope| !is_known_type(&envelope.r#type)) { return Err(MindRefusal::ForeignStore { r#type: foreign.r#type.clone() }); } + if raw.iter().filter(|envelope| envelope.r#type == HuginnPersonaEntry::TYPE).count() > 1 { + return Err(MindRefusal::ForeignStore { r#type: HuginnPersonaEntry::TYPE.into() }); + } Ok(()) } diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs new file mode 100644 index 0000000..37639aa --- /dev/null +++ b/crates/huginn-mind/src/persona.rs @@ -0,0 +1,506 @@ +//! The persona document: one `gamecult.persona_state.v0` per mind, stored +//! opaque and replaced whole. +//! +//! The shape is the published schema's, `schemas/cultnet/`, read here with +//! `include_bytes!`; the mind holds no Rust type for it, only the value that +//! passed the schema. `put_persona` (admission.rs) owns whether a document may +//! enter; this module owns what it is checked against and how it is stored and +//! read back. Nothing here echoes a caller's value: a refusal names a schema +//! location and a keyword, never the text that failed. + +use std::collections::BTreeSet; +use std::sync::OnceLock; + +use cultcache_rs::{CultCacheEnvelope, DatabaseEntry}; +use jsonschema::paths::LocationSegment; +use jsonschema::{ValidationErrorKind, Validator}; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use crate::mind::Mind; +use crate::receipt::HuginnCommitReceipt; +use crate::refusal::MindRefusal; +use crate::store::MindStore; + +const PERSONA_SCHEMA: &[u8] = include_bytes!("../../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); + +/// The stored envelope's payload: the document, one slot, keyed by the mind's +/// instance. The cache needs a registered entry type to hold the envelope; the +/// document inside stays a value. +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache(type = "gamecult.persona_state.v0", schema = "HuginnPersonaEntry")] +pub struct HuginnPersonaEntry { + #[cultcache(key = 0)] + pub value: Value, +} + +/// What `PersonaGet` answers: the stored document, its `updatedAt`, and the +/// receipt of the put that wrote it. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub struct PersonaStateView { + pub value: Value, + pub updated_at: String, + pub receipt_id: String, +} + +/// How a put ended. A refusal is an answer, as for `admit`. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum PersonaPutOutcome { + Committed { receipt_id: String }, + Refused(MindRefusal), +} + +struct Compiled { + validator: Validator, + /// Every property name the schema declares. A path segment outside this + /// set is a caller's key (`traitMap` keys are free), so it is withheld. + declared: BTreeSet, +} + +fn compiled() -> Result<&'static Compiled, MindRefusal> { + static COMPILED: OnceLock> = OnceLock::new(); + COMPILED + .get_or_init(|| { + let schema: Value = serde_json::from_slice(PERSONA_SCHEMA) + .map_err(|error| format!("the published persona schema does not parse: {error}"))?; + let validator = jsonschema::draft7::new(&schema) + .map_err(|error| format!("the published persona schema does not compile: {error}"))?; + let mut declared = BTreeSet::new(); + declared_names(&schema, &mut declared); + Ok(Compiled { validator, declared }) + }) + .as_ref() + .map_err(|detail| MindRefusal::Unavailable { detail: detail.clone() }) +} + +fn declared_names(node: &Value, names: &mut BTreeSet) { + match node { + Value::Object(map) => { + if let Some(Value::Object(properties)) = map.get("properties") { + names.extend(properties.keys().cloned()); + } + map.values().for_each(|child| declared_names(child, names)); + } + Value::Array(items) => items.iter().for_each(|child| declared_names(child, names)), + _ => {} + } +} + +/// Rule 1: the document is valid against the published schema. The first +/// failure is the refusal; it names where and which keyword, never the value. +pub(crate) fn validate_shape(state: &Value) -> Result<(), MindRefusal> { + let compiled = compiled()?; + let Err(error) = compiled.validator.validate(state) else { return Ok(()) }; + let mut path = error + .instance_path() + .segments() + .map(|segment| match segment { + LocationSegment::Index(index) => index.to_string(), + LocationSegment::Property(name) if compiled.declared.contains(name.as_ref()) => name.into_owned(), + LocationSegment::Property(_) => "*".to_string(), + }) + .collect::>(); + match error.kind() { + ValidationErrorKind::Required { property } => path.extend(property.as_str().map(str::to_string)), + ValidationErrorKind::AdditionalProperties { .. } => path.push("*".to_string()), + _ => {} + } + Err(MindRefusal::PersonaInvalid { + path: format!("/{}", path.join("/")), + message: format!("fails the published schema's {} rule", error.kind().keyword()), + }) +} + +/// A stored persona envelope's document. +pub(crate) fn decode(envelope: &CultCacheEnvelope) -> Result { + rmp_serde::from_slice::(&envelope.payload) + .map(|entry| entry.value) + .map_err(|error| MindRefusal::Unavailable { detail: format!("the stored persona does not decode: {error}") }) +} + +/// A document's `updatedAt`; the schema makes it a required string. +pub(crate) fn updated_at(value: &Value) -> Option<&str> { + value.get("updatedAt").and_then(Value::as_str) +} + +impl Mind { + /// This mind's persona envelope, if one is stored. + pub(crate) fn persona_envelope(&self) -> Option<&CultCacheEnvelope> { + self.raw_envelope(HuginnPersonaEntry::TYPE, &self.instance().0) + } + + /// The stored `updatedAt`; none when no persona is stored. + pub(crate) fn stored_updated_at(&self) -> Result, MindRefusal> { + let Some(envelope) = self.persona_envelope() else { return Ok(None) }; + let value = decode(envelope)?; + updated_at(&value) + .map(|stamp| Some(stamp.to_string())) + .ok_or_else(|| MindRefusal::Unavailable { detail: "the stored persona has no updatedAt".into() }) + } + + /// `PersonaGet`: the document, its `updatedAt` and the receipt of the put + /// that wrote exactly these bytes. + pub fn persona(&self) -> Result, MindRefusal> { + let Some(envelope) = self.persona_envelope() else { return Ok(None) }; + let value = decode(envelope)?; + let integrity = |detail: &str| MindRefusal::Unavailable { detail: detail.into() }; + let updated_at = updated_at(&value).ok_or_else(|| integrity("the stored persona has no updatedAt"))?.to_string(); + let receipt_id = self + .receipts()? + .into_iter() + .find(|receipt: &HuginnCommitReceipt| { + receipt.writes.iter().any(|write| { + write.document_type == envelope.r#type + && write.document_key == envelope.key + && write.payload_msgpack == envelope.payload + }) + }) + .ok_or_else(|| integrity("the stored persona has no receipt"))? + .receipt_id; + Ok(Some(PersonaStateView { value, updated_at, receipt_id })) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::fixtures::{INSTANCE, OTHER_INSTANCE, epoch, instance, opened, prepare, provenance, seed, slug}; + use crate::receipt::Faculty; + use crate::store::test_stores::{MemoryStore, RefusingStore, SwapCommand}; + use eureka_pipeline::PipelineKind; + use serde_json::json; + + const T1: &str = "2026-10-10T10:00:00Z"; + const T2: &str = "2026-10-10T10:00:01Z"; + const T3: &str = "2026-10-10T10:00:02Z"; + const CANARY: &str = "CANARY-7f3a91-do-not-echo"; + const NOT_LATER: &str = "must be later than the stored updatedAt"; + + /// A minimal document the published schema accepts. The test that follows + /// holds it to the schema file's own required list. + fn persona(id: &str, updated_at: &str) -> Value { + let traits = json!({ + "underlyingOrganization": {}, "stableDispositions": {}, "behavioralDimensions": {}, + "presentationStrategy": {}, "voiceStyle": {}, "situationalState": {} + }); + json!({ + "schemaVersion": "gamecult.persona_state.v0", + "provenance": { + "sourceSystem": "huginn", "sourceDocumentId": id, "sourceUpdatedAt": updated_at, + "exportedAt": updated_at, "authority": "canonical" + }, + "personaId": id, + "publicName": "Test Persona", + "presentation": { "voiceSummary": "plain" }, + "activationProfile": traits, + "thoughtMemory": { "shortTerm": [], "memories": [], "incubation": [] }, + "agencyPressure": { "pressures": [] }, + "candidateActions": { "actions": [] }, + "affect": { + "needs": [], "socialBonds": [], "statusReads": [], "moodDimensions": [], + "socialBiases": [], "doctrineStances": [] + }, + "updatedAt": updated_at + }) + } + + fn schema_file() -> Value { + let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); + serde_json::from_slice(&std::fs::read(path).unwrap()).unwrap() + } + + fn put(mind: &mut Mind, state: Value, expected: Option<&str>) -> PersonaPutOutcome { + let instance = mind.instance().clone(); + mind.put_persona(&instance, state, expected.map(str::to_string), provenance(Faculty::Hands), crate::fixtures::now()) + } + + fn committed(outcome: PersonaPutOutcome) -> String { + match outcome { + PersonaPutOutcome::Committed { receipt_id } => receipt_id, + other => panic!("expected a commit, got {other:?}"), + } + } + + fn refused(outcome: PersonaPutOutcome) -> MindRefusal { + match outcome { + PersonaPutOutcome::Refused(refusal) => refusal, + other => panic!("expected a refusal, got {other:?}"), + } + } + + fn invalid(path: &str, rule: &str) -> MindRefusal { + MindRefusal::PersonaInvalid { path: path.into(), message: format!("fails the published schema's {rule} rule") } + } + + fn not_later() -> MindRefusal { + MindRefusal::PersonaInvalid { path: "/updatedAt".into(), message: NOT_LATER.into() } + } + + fn stale(stored: Option<&str>) -> MindRefusal { + MindRefusal::PersonaStale { stored: stored.map(str::to_string) } + } + + fn seeded_over(store: &MemoryStore) -> Mind { + let mut mind = opened(store.clone(), INSTANCE); + seed(&mut mind); + mind + } + + fn persona_in_status(mind: &Mind) -> Option { + mind.status(crate::wire::IndexStatus::Current).persona + } + + #[test] + fn the_fixture_is_valid_against_the_published_file_and_covers_its_required_fields() { + let schema = schema_file(); + let validator = jsonschema::draft7::new(&schema).unwrap(); + let document = persona(INSTANCE, T1); + assert!(validator.is_valid(&document)); + for name in schema["required"].as_array().unwrap() { + assert!(document.get(name.as_str().unwrap()).is_some(), "the fixture lacks {name}"); + } + } + + #[test] + fn a_persona_document_is_validated_at_the_door() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + + for name in schema_file()["required"].as_array().unwrap() { + let name = name.as_str().unwrap(); + let mut document = persona(INSTANCE, T1); + document.as_object_mut().unwrap().remove(name); + assert_eq!(refused(put(&mut mind, document, None)), invalid(&format!("/{name}"), "required"), "{name}"); + } + + let mut extra = persona(INSTANCE, T1); + extra["notInTheSchema"] = json!(1); + assert_eq!(refused(put(&mut mind, extra, None)), invalid("/*", "additionalProperties")); + + let mut wrong_type = persona(INSTANCE, T1); + wrong_type["publicName"] = json!(5); + assert_eq!(refused(put(&mut mind, wrong_type, None)), invalid("/publicName", "type")); + + let mut bad_stamp = persona(INSTANCE, T1); + bad_stamp["updatedAt"] = json!("yesterday"); + assert_eq!(refused(put(&mut mind, bad_stamp, None)), invalid("/updatedAt", "format")); + + let mut nested = persona(INSTANCE, T1); + nested["thoughtMemory"]["memories"] = json!([7]); + assert_eq!(refused(put(&mut mind, nested, None)), invalid("/thoughtMemory/memories/0", "type")); + + let mut free_key = persona(INSTANCE, T1); + free_key["activationProfile"]["voiceStyle"]["any-key"] = json!({}); + assert_eq!( + refused(put(&mut mind, free_key, None)), + invalid("/activationProfile/voiceStyle/*/mean", "required"), + "a key the schema does not declare is withheld from the path" + ); + + assert_eq!(store.rows(), before, "no refusal wrote anything"); + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn a_refusal_never_echoes_what_the_caller_sent() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T2), None)); + + let mut free_key = persona(INSTANCE, T3); + free_key["activationProfile"]["voiceStyle"][CANARY] = json!({}); + let mut extra_key = persona(INSTANCE, T3); + extra_key[CANARY] = json!(CANARY); + let mut bad_value = persona(INSTANCE, T3); + bad_value["updatedAt"] = json!(CANARY); + let mut bad_enum = persona(INSTANCE, T3); + bad_enum["provenance"]["authority"] = json!(CANARY); + let mut foreign = persona(CANARY, T3); + foreign["publicName"] = json!(CANARY); + let mut imported = persona(INSTANCE, T3); + imported["provenance"]["authority"] = json!("import"); + imported["provenance"]["sourceSystem"] = json!(CANARY); + let mut late = persona(INSTANCE, T1); + late["publicName"] = json!(CANARY); + + let cases: Vec<(Value, Option<&str>)> = vec![ + (free_key, Some(T2)), + (extra_key, Some(T2)), + (bad_value, Some(T2)), + (bad_enum, Some(T2)), + (foreign, Some(T2)), + (imported, Some(T2)), + (late, Some(T2)), + (persona(INSTANCE, T3), Some(CANARY)), + ]; + for (document, expected) in cases { + let refusal = refused(put(&mut mind, document, expected)); + assert!(!format!("{refusal:?}").contains(CANARY), "{refusal:?}"); + assert!(!serde_json::to_string(&refusal).unwrap().contains(CANARY)); + } + } + + #[test] + fn persona_id_must_be_the_instance() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + let refusal = refused(put(&mut mind, persona(OTHER_INSTANCE, T1), None)); + assert_eq!(refusal, MindRefusal::PersonaForeign { instance: INSTANCE.into() }); + assert_eq!(store.rows(), before); + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn only_a_canonical_document_is_the_minds_persona() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + for authority in ["projection", "import"] { + let mut document = persona(INSTANCE, T1); + document["provenance"]["authority"] = json!(authority); + assert_eq!(refused(put(&mut mind, document, None)), MindRefusal::PersonaNotCanonical, "{authority}"); + } + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn a_persona_waits_for_the_minds_identity() { + let mut mind = opened(MemoryStore::new(), INSTANCE); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), None)), MindRefusal::MissingIdentity); + assert!(mind.is_empty()); + } + + #[test] + fn a_put_must_name_this_mind_and_a_named_asker() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + let other = slug(OTHER_INSTANCE); + let outcome = mind.put_persona(&other, persona(INSTANCE, T1), None, provenance(Faculty::Hands), crate::fixtures::now()); + assert!(matches!(refused(outcome), MindRefusal::ForeignInstance { .. })); + let mut unnamed = provenance(Faculty::Hands); + unnamed.agent = eureka_pipeline::Short(" ".into()); + let instance = mind.instance().clone(); + let outcome = mind.put_persona(&instance, persona(INSTANCE, T1), None, unnamed, crate::fixtures::now()); + assert!(matches!(refused(outcome), MindRefusal::Document(_))); + assert_eq!(store.rows(), before); + } + + #[test] + fn a_put_is_a_compare_and_swap_on_updated_at() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + assert_eq!(persona_in_status(&mind), None); + let receipts = |mind: &Mind| mind.receipts().unwrap().len(); + let base = receipts(&mind); + + // A first put expects nothing; claiming a stored document is stale. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T1))), stale(None)); + let first = committed(put(&mut mind, persona(INSTANCE, T1), None)); + assert_eq!(receipts(&mind), base + 1); + let view = mind.persona().unwrap().unwrap(); + assert_eq!((view.updated_at.as_str(), view.receipt_id.as_str()), (T1, first.as_str())); + assert_eq!(view.value, persona(INSTANCE, T1)); + assert_eq!(persona_in_status(&mind).as_deref(), Some(T1)); + + // Two puts that read the same stored document: the second loses. + let second = committed(put(&mut mind, persona(INSTANCE, T2), Some(T1))); + assert_eq!(receipts(&mind), base + 2); + let rows = store.rows(); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), Some(T1))), stale(Some(T2))); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), None)), stale(Some(T2))); + assert_eq!(store.rows(), rows, "a stale put wrote nothing"); + + // The right expectation with an updatedAt that is not later. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T2))), not_later()); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T2))), not_later()); + // Instants compare, not spellings: the same instant at another offset is not later. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:01+02:00"), Some(T2))), not_later()); + assert_eq!(store.rows(), rows); + assert_eq!(receipts(&mind), base + 2); + committed(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:02+02:00"), Some(T2))); + assert_eq!(receipts(&mind), base + 3); + + // The second put's receipt read the first document and wrote the second. + let receipt = mind.receipts().unwrap().into_iter().find(|receipt| receipt.receipt_id == second).unwrap(); + assert_eq!((receipt.strong_reads.len(), receipt.writes.len()), (1, 1)); + assert_eq!(receipt.strong_reads[0].document_key, INSTANCE); + assert_ne!(receipt.strong_reads[0].payload_msgpack, receipt.writes[0].payload_msgpack); + assert_eq!(receipt.provenance, provenance(Faculty::Hands)); + } + + #[test] + fn a_put_whose_swap_is_lost_is_stale_and_changes_nothing() { + let store = RefusingStore::new(); + let mut mind = opened(store.clone(), INSTANCE); + seed(&mut mind); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + let rows = store.rows(); + store.command(SwapCommand::Lose); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T1))), stale(Some(T1))); + assert_eq!(store.rows(), rows); + } + + #[test] + fn the_persona_is_not_a_pipeline_document_and_a_batch_cannot_carry_it() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let documents = mind.status(crate::wire::IndexStatus::Current).documents; + committed(put(&mut mind, persona(INSTANCE, T1), None)); + assert_eq!(mind.status(crate::wire::IndexStatus::Current).documents, documents); + assert!(PipelineKind::ALL.iter().all(|kind| kind.type_id() != HuginnPersonaEntry::TYPE)); + let forged = mind.persona_envelope().unwrap().clone(); + let instance = mind.instance().clone(); + let outcome = mind.admit_prepared(&instance, provenance(Faculty::Hands), vec![forged], crate::fixtures::now()); + assert!(matches!(outcome, crate::admission::PipelineAdmissionOutcome::Refused(_)), "{outcome:?}"); + } + + #[test] + fn one_persona_per_mind_and_the_store_still_opens() { + let yggdrasil = slug(INSTANCE); + let cache = crate::mind::schema_cache().unwrap(); + let entry = |key: &str, value: Value| cache.prepare_entry_named(key, &HuginnPersonaEntry { value }).unwrap().0; + let planted = |rows: Vec| { + let store = MemoryStore::new(); + rows.into_iter().for_each(|row| store.plant(row)); + store + }; + let base = || vec![epoch(), prepare(&instance(INSTANCE))]; + + // A store written before this type existed opens unchanged. + assert!(Mind::open_with(planted(base()), &yggdrasil).is_ok()); + + // One persona opens and reads back. + let mut with_one = base(); + with_one.push(entry(INSTANCE, persona(INSTANCE, T1))); + let mind = Mind::open_with(planted(with_one.clone()), &yggdrasil).unwrap(); + assert_eq!(mind.envelopes().len(), 3); + assert_eq!(persona_in_status(&mind).as_deref(), Some(T1)); + + // Two are no mind's. + with_one.push(entry("second", persona(INSTANCE, T2))); + assert_eq!( + Mind::open_with(planted(with_one), &yggdrasil).err(), + Some(MindRefusal::ForeignStore { r#type: HuginnPersonaEntry::TYPE.into() }) + ); + // The opener still refuses a type that is not one of the seventeen. + let mut stranger = base(); + let mut foreign = entry(INSTANCE, persona(INSTANCE, T1)); + foreign.r#type = "gamecult.persona_state.v1".into(); + stranger.push(foreign); + assert!(matches!(Mind::open_with(planted(stranger), &yggdrasil).err(), Some(MindRefusal::ForeignStore { .. }))); + } + + #[test] + fn the_stored_bytes_are_the_one_slot_array_the_catalogue_describes() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + let envelope = mind.persona_envelope().unwrap(); + assert_eq!((envelope.r#type.as_str(), envelope.key.as_str()), ("gamecult.persona_state.v0", INSTANCE)); + let slots: (Value,) = rmp_serde::from_slice(&envelope.payload).unwrap(); + assert_eq!(slots.0, persona(INSTANCE, T1)); + } +} diff --git a/crates/huginn-mind/src/receipt.rs b/crates/huginn-mind/src/receipt.rs index 35705d9..446786e 100644 --- a/crates/huginn-mind/src/receipt.rs +++ b/crates/huginn-mind/src/receipt.rs @@ -256,9 +256,15 @@ pub(crate) fn commit( .map(|(envelope, _)| envelope) .map_err(unavailable)?; // The store requires every expected identity to be replaced, so each - // strong read is re-inserted unchanged beside the writes. + // strong read is re-inserted unchanged beside the writes, unless a write + // replaces it (a persona put reads the document it overwrites). let mut replacements = writes.clone(); - replacements.extend(strong_reads.iter().cloned()); + replacements.extend( + strong_reads + .iter() + .filter(|read| !writes.iter().any(|write| write.r#type == read.r#type && write.key == read.key)) + .cloned(), + ); replacements.push(receipt_envelope); let expected: &[CultCacheEnvelope] = &strong_reads; let landed = MindStore::compare_and_swap_batch(mind.store(), expected, replacements).map_err(unavailable)?; diff --git a/crates/huginn-mind/src/refusal.rs b/crates/huginn-mind/src/refusal.rs index c771744..02f870f 100644 --- a/crates/huginn-mind/src/refusal.rs +++ b/crates/huginn-mind/src/refusal.rs @@ -55,6 +55,19 @@ pub enum MindRefusal { FindingWithoutEvidence, UnknownInvariant { label: String }, NotStewarded { repo: String }, + /// The persona document fails the published schema: `path` is the + /// document location (a key the schema does not declare is `*`) and + /// `message` the schema keyword that failed. Never the offending value. + PersonaInvalid { path: String, message: String }, + /// The document's `personaId` is not this mind's instance, which is + /// `instance`. + PersonaForeign { instance: String }, + /// The put's `expected_updated_at` is not the stored document's + /// `updatedAt`, which is `stored` (none when no persona is stored). + PersonaStale { stored: Option }, + /// The document's `provenance.authority` is not `canonical`: a projection + /// or an import is not the mind's persona. + PersonaNotCanonical, /// A run claims work another run in force already holds: `item` is the /// claimed document's id and `run` the id of the run that holds it. AlreadyClaimed { item: String, run: String }, diff --git a/crates/huginn-mind/src/wire.rs b/crates/huginn-mind/src/wire.rs index 5265c0d..10bbede 100644 --- a/crates/huginn-mind/src/wire.rs +++ b/crates/huginn-mind/src/wire.rs @@ -9,11 +9,13 @@ use cultnet_rs::{CultMeshCdnArtifactManifest, Selection}; use eureka_pipeline::{PIPELINE_SCHEMA_EPOCH, PipelineKind, PipelineRef, Slug}; use schemars::JsonSchema; use serde::{Deserialize, Serialize}; +use serde_json::Value; use crate::admission::{PipelineAdmissionBatch, PipelineAdmissionOutcome}; use crate::mind::Mind; +use crate::persona::{PersonaPutOutcome, PersonaStateView}; use crate::query::{PipelineDocumentView, PipelineSelectionPage, SemanticQuery}; -use crate::receipt::HuginnCommitReceipt; +use crate::receipt::{HuginnCommitReceipt, PipelineProvenance}; use crate::refusal::MindRefusal; use crate::store::MindStore; @@ -75,6 +77,17 @@ pub enum HuginnMindRequest { selection: Selection, semantic: Option, }, + /// The mind's persona document, if one is stored. + PersonaGet { instance: Slug }, + /// Replaces the mind's persona document whole. `expected_updated_at` is + /// the stored document's `updatedAt`, none for the first put. The + /// provenance is the asker's, as for `Admit`. + PersonaPut { + instance: Slug, + provenance: PipelineProvenance, + state: Value, + expected_updated_at: Option, + }, } impl HuginnMindRequest { @@ -85,6 +98,8 @@ impl HuginnMindRequest { Self::Admit(_) => "admit", Self::View { .. } => "view", Self::Query { .. } => "query", + Self::PersonaGet { .. } => "persona_get", + Self::PersonaPut { .. } => "persona_put", } } @@ -93,7 +108,10 @@ impl HuginnMindRequest { match self { Self::Whoami => None, Self::Admit(batch) => Some(&batch.instance), - Self::View { instance, .. } | Self::Query { instance, .. } => Some(instance), + Self::View { instance, .. } + | Self::Query { instance, .. } + | Self::PersonaGet { instance } + | Self::PersonaPut { instance, .. } => Some(instance), } } } @@ -109,6 +127,8 @@ pub enum HuginnMindResponse { View(Option), Query(PipelineSelectionPage), Refused(MindRefusal), + Persona(Option), + PersonaPut(PersonaPutOutcome), /// The answer did not fit one send and is being held for the client to /// fetch. Nothing in a mind produces this: the daemon's serve module does, /// in place of an answer, and the answer it stands for is the named @@ -135,7 +155,9 @@ impl HuginnMindResponse { /// envelope of a deferred answer to the status of the answer it stands for. pub fn status(&self) -> &'static str { match self { - Self::Refused(_) | Self::Admit(PipelineAdmissionOutcome::Refused(_)) => "rejected", + Self::Refused(_) + | Self::Admit(PipelineAdmissionOutcome::Refused(_)) + | Self::PersonaPut(PersonaPutOutcome::Refused(_)) => "rejected", _ => "accepted", } } @@ -171,6 +193,8 @@ pub struct MindStatus { pub documents: u32, pub receipts: u32, pub index: IndexStatus, + /// The stored persona document's `updatedAt`; none until the first put. + pub persona: Option, } impl Mind { @@ -192,6 +216,7 @@ impl Mind { documents, receipts, index, + persona: self.stored_updated_at().ok().flatten(), } } } @@ -214,6 +239,13 @@ mod tests { HuginnMindRequest::Admit(batch), HuginnMindRequest::View { instance: slug(INSTANCE), id: r(PipelineKind::Campaign, CAMPAIGN) }, HuginnMindRequest::Query { instance: slug(OTHER_INSTANCE), selection: Selection::default(), semantic: None }, + HuginnMindRequest::PersonaGet { instance: slug(INSTANCE) }, + HuginnMindRequest::PersonaPut { + instance: slug(INSTANCE), + provenance: provenance(Faculty::Hands), + state: serde_json::json!({ "updatedAt": "2026-10-10T10:00:00Z", "n": [1, 2.5, null, "x"] }), + expected_updated_at: Some("2026-10-10T09:00:00Z".into()), + }, ] } @@ -233,6 +265,14 @@ mod tests { edges: None, }), HuginnMindResponse::Refused(refusal), + HuginnMindResponse::Persona(None), + HuginnMindResponse::Persona(Some(PersonaStateView { + value: serde_json::json!({ "personaId": INSTANCE }), + updated_at: "2026-10-10T10:00:00Z".into(), + receipt_id: "mind-commit-1".into(), + })), + HuginnMindResponse::PersonaPut(PersonaPutOutcome::Committed { receipt_id: "mind-commit-2".into() }), + HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(MindRefusal::PersonaNotCanonical)), HuginnMindResponse::Deferred(DeferredAnswer { manifest: cultnet_rs::pack_content("huginn.mind_response", "package", "", "", "", b"body", 4) .unwrap() @@ -247,7 +287,7 @@ mod tests { #[test] fn the_wire_vocabulary_is_the_minds_methods_and_status_is_derived_from_the_response() { let names: Vec<&str> = requests().iter().map(|request| request.operation()).collect(); - assert_eq!(names, ["whoami", "admit", "view", "query"]); + assert_eq!(names, ["whoami", "admit", "view", "query", "persona_get", "persona_put"]); for request in requests() { let declared = request.instance().is_none(); assert_eq!(declared, matches!(request, HuginnMindRequest::Whoami), "{request:?}"); @@ -263,7 +303,9 @@ mod tests { for response in responses() { let rejected = matches!( response, - HuginnMindResponse::Refused(_) | HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(_)) + HuginnMindResponse::Refused(_) + | HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(_)) + | HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(_)) ); assert_eq!(response.status(), if rejected { "rejected" } else { "accepted" }, "{response:?}"); let bytes = rmp_serde::to_vec_named(&response).unwrap(); From 6fde91fe0a2e9f312b7471d8963cad7421059359 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 05:47:00 +0200 Subject: [PATCH 02/11] Persona: compile fixes and the regenerated wire schemas The jsonschema error kind lives in jsonschema::error; the eureka-state tool closures own their input; huginn.mind_request/response.v1 carry the persona operations (derived by the existing published_wire_schemas test). Co-Authored-By: Claude Opus 5.5 --- crates/eureka-state/src/main.rs | 6 +- crates/huginn-mind/src/persona.rs | 3 +- .../huginn.mind_request.v1.schema.json | 54 ++++++ .../huginn.mind_response.v1.schema.json | 165 ++++++++++++++++++ 4 files changed, 224 insertions(+), 4 deletions(-) diff --git a/crates/eureka-state/src/main.rs b/crates/eureka-state/src/main.rs index 2138fa5..dcf65c6 100644 --- a/crates/eureka-state/src/main.rs +++ b/crates/eureka-state/src/main.rs @@ -260,7 +260,7 @@ impl EurekaState { description = "Admit one batch of pipeline documents into the mind, whole or not at all. Returns the outcome: committed with a receipt, already admitted, conflict, or a typed refusal. The instance is this server's configuration; do not pass one." )] async fn admit(&self, Parameters(input): Parameters) -> CallToolResult { - self.answer(|instance| { + self.answer(move |instance| { HuginnMindRequest::Admit(PipelineAdmissionBatch { instance, provenance: PipelineProvenance { @@ -277,14 +277,14 @@ impl EurekaState { #[tool(description = "Read one document by id, with its admission facts and status. null when the mind has no such document.")] async fn view(&self, Parameters(input): Parameters) -> CallToolResult { - self.answer(|instance| HuginnMindRequest::View { instance, id: input.id }).await + self.answer(move |instance| HuginnMindRequest::View { instance, id: input.id }).await } #[tool( description = "Query the mind with a CultNet typed selection, optionally ranked by semantic nearness. Returns one page; pass its cursor back in the selection for the next." )] async fn query(&self, Parameters(input): Parameters) -> CallToolResult { - self.answer(|instance| HuginnMindRequest::Query { + self.answer(move |instance| HuginnMindRequest::Query { instance, selection: input.selection, semantic: input.semantic, diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs index 37639aa..f77a4a0 100644 --- a/crates/huginn-mind/src/persona.rs +++ b/crates/huginn-mind/src/persona.rs @@ -13,7 +13,8 @@ use std::sync::OnceLock; use cultcache_rs::{CultCacheEnvelope, DatabaseEntry}; use jsonschema::paths::LocationSegment; -use jsonschema::{ValidationErrorKind, Validator}; +use jsonschema::error::ValidationErrorKind; +use jsonschema::Validator; use schemars::JsonSchema; use serde::{Deserialize, Serialize}; use serde_json::Value; diff --git a/schemas/cultnet/huginn.mind_request.v1.schema.json b/schemas/cultnet/huginn.mind_request.v1.schema.json index 909a8a8..c075586 100644 --- a/schemas/cultnet/huginn.mind_request.v1.schema.json +++ b/schemas/cultnet/huginn.mind_request.v1.schema.json @@ -78,6 +78,60 @@ "required": [ "Query" ] + }, + { + "description": "The mind's persona document, if one is stored.", + "type": "object", + "properties": { + "PersonaGet": { + "type": "object", + "properties": { + "instance": { + "$ref": "#/$defs/Slug" + } + }, + "required": [ + "instance" + ] + } + }, + "additionalProperties": false, + "required": [ + "PersonaGet" + ] + }, + { + "description": "Replaces the mind's persona document whole. `expected_updated_at` is\nthe stored document's `updatedAt`, none for the first put. The\nprovenance is the asker's, as for `Admit`.", + "type": "object", + "properties": { + "PersonaPut": { + "type": "object", + "properties": { + "expected_updated_at": { + "type": [ + "string", + "null" + ] + }, + "instance": { + "$ref": "#/$defs/Slug" + }, + "provenance": { + "$ref": "#/$defs/PipelineProvenance" + }, + "state": true + }, + "required": [ + "instance", + "provenance", + "state" + ] + } + }, + "additionalProperties": false, + "required": [ + "PersonaPut" + ] } ], "$defs": { diff --git a/schemas/cultnet/huginn.mind_response.v1.schema.json b/schemas/cultnet/huginn.mind_response.v1.schema.json index 426cf7a..7e1eeda 100644 --- a/schemas/cultnet/huginn.mind_response.v1.schema.json +++ b/schemas/cultnet/huginn.mind_response.v1.schema.json @@ -70,6 +70,37 @@ "Refused" ] }, + { + "type": "object", + "properties": { + "Persona": { + "anyOf": [ + { + "$ref": "#/$defs/PersonaStateView" + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false, + "required": [ + "Persona" + ] + }, + { + "type": "object", + "properties": { + "PersonaPut": { + "$ref": "#/$defs/PersonaPutOutcome" + } + }, + "additionalProperties": false, + "required": [ + "PersonaPut" + ] + }, { "description": "The answer did not fit one send and is being held for the client to\nfetch. Nothing in a mind produces this: the daemon's serve module does,\nin place of an answer, and the answer it stands for is the named\nMessagePack of the `HuginnMindResponse` the mind gave.", "type": "object", @@ -1360,6 +1391,78 @@ "NotStewarded" ] }, + { + "description": "The persona document fails the published schema: `path` is the\ndocument location (a key the schema does not declare is `*`) and\n`message` the schema keyword that failed. Never the offending value.", + "type": "object", + "properties": { + "PersonaInvalid": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "path": { + "type": "string" + } + }, + "required": [ + "path", + "message" + ] + } + }, + "additionalProperties": false, + "required": [ + "PersonaInvalid" + ] + }, + { + "description": "The document's `personaId` is not this mind's instance, which is\n`instance`.", + "type": "object", + "properties": { + "PersonaForeign": { + "type": "object", + "properties": { + "instance": { + "type": "string" + } + }, + "required": [ + "instance" + ] + } + }, + "additionalProperties": false, + "required": [ + "PersonaForeign" + ] + }, + { + "description": "The put's `expected_updated_at` is not the stored document's\n`updatedAt`, which is `stored` (none when no persona is stored).", + "type": "object", + "properties": { + "PersonaStale": { + "type": "object", + "properties": { + "stored": { + "type": [ + "string", + "null" + ] + } + } + } + }, + "additionalProperties": false, + "required": [ + "PersonaStale" + ] + }, + { + "description": "The document's `provenance.authority` is not `canonical`: a projection\nor an import is not the mind's persona.", + "type": "string", + "const": "PersonaNotCanonical" + }, { "description": "A run claims work another run in force already holds: `item` is the\nclaimed document's id and `run` the id of the run that holds it.", "type": "object", @@ -1504,6 +1607,13 @@ "instance": { "$ref": "#/$defs/Slug" }, + "persona": { + "description": "The stored persona document's `updatedAt`; none until the first put.", + "type": [ + "string", + "null" + ] + }, "receipts": { "type": "integer", "format": "uint32", @@ -1582,6 +1692,61 @@ "type": "string", "maxLength": 4000 }, + "PersonaPutOutcome": { + "description": "How a put ended. A refusal is an answer, as for `admit`.", + "oneOf": [ + { + "type": "object", + "properties": { + "Committed": { + "type": "object", + "properties": { + "receipt_id": { + "type": "string" + } + }, + "required": [ + "receipt_id" + ] + } + }, + "additionalProperties": false, + "required": [ + "Committed" + ] + }, + { + "type": "object", + "properties": { + "Refused": { + "$ref": "#/$defs/MindRefusal" + } + }, + "additionalProperties": false, + "required": [ + "Refused" + ] + } + ] + }, + "PersonaStateView": { + "description": "What `PersonaGet` answers: the stored document, its `updatedAt`, and the\nreceipt of the put that wrote it.", + "type": "object", + "properties": { + "receipt_id": { + "type": "string" + }, + "updated_at": { + "type": "string" + }, + "value": true + }, + "required": [ + "value", + "updated_at", + "receipt_id" + ] + }, "PipelineAdmissionOutcome": { "description": "How admission ended. `Committed.writes` names every document the batch\nlanded, derived writes included; Cut 11 indexes from it after `admit`\nreturns, and never inside it.", "oneOf": [ From ef7c5e5f2fd819d5c8d9fc0e527687303746851d Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 06:09:42 +0200 Subject: [PATCH 03/11] Persona: the view's receipt is the newest one that wrote the document The match on type, key and bytes was three conditions for one fact; the newest receipt writing the persona identity is that fact. Tests pin the declared-name walk and the receipt of each of five consecutive puts. Co-Authored-By: Claude Opus 5.5 --- crates/huginn-mind/src/persona.rs | 37 ++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs index f77a4a0..13f4fc8 100644 --- a/crates/huginn-mind/src/persona.rs +++ b/crates/huginn-mind/src/persona.rs @@ -20,7 +20,6 @@ use serde::{Deserialize, Serialize}; use serde_json::Value; use crate::mind::Mind; -use crate::receipt::HuginnCommitReceipt; use crate::refusal::MindRefusal; use crate::store::MindStore; @@ -147,16 +146,12 @@ impl Mind { let value = decode(envelope)?; let integrity = |detail: &str| MindRefusal::Unavailable { detail: detail.into() }; let updated_at = updated_at(&value).ok_or_else(|| integrity("the stored persona has no updatedAt"))?.to_string(); + let identity = (envelope.r#type.as_str(), envelope.key.as_str()); let receipt_id = self .receipts()? .into_iter() - .find(|receipt: &HuginnCommitReceipt| { - receipt.writes.iter().any(|write| { - write.document_type == envelope.r#type - && write.document_key == envelope.key - && write.payload_msgpack == envelope.payload - }) - }) + .filter(|receipt| receipt.writes.iter().any(|write| write.identity() == identity)) + .max_by_key(|receipt| receipt.ordinal) .ok_or_else(|| integrity("the stored persona has no receipt"))? .receipt_id; Ok(Some(PersonaStateView { value, updated_at, receipt_id })) @@ -263,6 +258,32 @@ mod tests { } } + #[test] + fn declared_names_are_every_property_name_at_any_depth() { + let schema = json!({ + "properties": { "a": { "properties": { "b": {} } } }, + "allOf": [{ "properties": { "c": {} } }], + "definitions": { "d": { "properties": { "e": {} } } }, + "required": ["not-a-property"] + }); + let mut names = BTreeSet::new(); + declared_names(&schema, &mut names); + assert_eq!(names, BTreeSet::from(["a", "b", "c", "e"].map(String::from))); + } + + #[test] + fn the_view_names_the_receipt_of_the_latest_put() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let mut previous: Option = None; + for second in 0..5 { + let stamp = format!("2026-10-10T10:00:0{second}Z"); + let receipt = committed(put(&mut mind, persona(INSTANCE, &stamp), previous.as_deref())); + assert_eq!(mind.persona().unwrap().unwrap().receipt_id, receipt, "after put {second}"); + previous = Some(stamp); + } + } + #[test] fn a_persona_document_is_validated_at_the_door() { let store = MemoryStore::new(); From 8f59d4850a56b98952340ce52b527e092191ba58 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 06:35:25 +0200 Subject: [PATCH 04/11] Persona: a put may rewrite identity fields, and every change lands Pins identity-write-all-visible: publicName, publicDescription, presentation and values change through put_persona with no per-field rule and no rate limit beyond the monotone updatedAt. Co-Authored-By: Claude Opus 5.5 --- crates/huginn-mind/src/persona.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs index 13f4fc8..8e1a7a9 100644 --- a/crates/huginn-mind/src/persona.rs +++ b/crates/huginn-mind/src/persona.rs @@ -271,6 +271,28 @@ mod tests { assert_eq!(names, BTreeSet::from(["a", "b", "c", "e"].map(String::from))); } + /// `identity-write-all-visible`: a put may change any field, the identity + /// fields included, and a change the next second is no less admissible. + #[test] + fn a_put_may_rewrite_identity_fields_and_every_change_lands() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + + let mut renamed = persona(INSTANCE, T2); + renamed["publicName"] = json!("A New Name"); + renamed["publicDescription"] = json!("who she says she is"); + renamed["presentation"] = json!({ "voiceSummary": "warmer", "pronouns": "she/her" }); + renamed["values"] = json!([{ "id": "v1", "label": "candor", "priority": 0.9 }]); + committed(put(&mut mind, renamed.clone(), Some(T1))); + assert_eq!(mind.persona().unwrap().unwrap().value, renamed); + + let mut again = persona(INSTANCE, T3); + again["publicName"] = json!("Another Name"); + committed(put(&mut mind, again.clone(), Some(T2))); + assert_eq!(mind.persona().unwrap().unwrap().value, again); + } + #[test] fn the_view_names_the_receipt_of_the_latest_put() { let store = MemoryStore::new(); From ea28b8cbc0050acd0d12d4190f69d399af3efd3d Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 08:32:48 +0200 Subject: [PATCH 05/11] Decoder reports field path and error class, never a caller value; status says Unreadable The shared request decoder (envelope.rs) no longer quotes decoder text or envelope fields: a refusal names the field path and the class. MindStatus.persona is PersonaStatus {Absent, Stored, Unreadable}, so whoami answers in the persona door's own terms. Co-Authored-By: Claude Opus 5.5 --- crates/eureka-state/tests/client.rs | 2 +- crates/huginn-daemon/src/daemon.rs | 4 +- crates/huginn-mind/Cargo.toml | 1 + crates/huginn-mind/src/envelope.rs | 112 ++++++++++++++++++++++++++-- crates/huginn-mind/src/lib.rs | 2 +- crates/huginn-mind/src/persona.rs | 35 ++++++++- crates/huginn-mind/src/wire.rs | 20 ++++- 7 files changed, 158 insertions(+), 18 deletions(-) diff --git a/crates/eureka-state/tests/client.rs b/crates/eureka-state/tests/client.rs index 38550b9..e474276 100644 --- a/crates/eureka-state/tests/client.rs +++ b/crates/eureka-state/tests/client.rs @@ -218,7 +218,7 @@ fn client_persona_round_trip_against_a_live_daemon() { assert_eq!(view.value, persona(INSTANCE, T1)); assert_eq!((view.updated_at.as_str(), view.receipt_id.as_str()), (T1, receipt_id.as_str())); let HuginnMindResponse::Whoami(status) = client.call(HuginnMindRequest::Whoami).unwrap() else { panic!("a status") }; - assert_eq!(status.persona.as_deref(), Some(T1)); + assert_eq!(status.persona, huginn_mind::wire::PersonaStatus::Stored { updated_at: T1.into() }); // A stale put is an answer. assert_eq!( diff --git a/crates/huginn-daemon/src/daemon.rs b/crates/huginn-daemon/src/daemon.rs index 34a54c7..afe0185 100644 --- a/crates/huginn-daemon/src/daemon.rs +++ b/crates/huginn-daemon/src/daemon.rs @@ -590,7 +590,7 @@ pub(crate) mod tests { documents: 1, receipts: 1, index: IndexStatus::Current, - persona: None, + persona: huginn_mind::wire::PersonaStatus::Absent, } ); assert_eq!(daemon.runtime_id(), "huginn-yggdrasil"); @@ -704,7 +704,7 @@ pub(crate) mod tests { expected_updated_at: None, }; assert_eq!(daemon.handle(put, now()).answered(), HuginnMindResponse::Refused(foreign)); - assert_eq!(status(&mut daemon).persona, None); + assert_eq!(status(&mut daemon).persona, huginn_mind::wire::PersonaStatus::Absent); } /// A declared instance outside `Slug`'s grammar is refused by its own diff --git a/crates/huginn-mind/Cargo.toml b/crates/huginn-mind/Cargo.toml index bcbfde6..48e61ad 100644 --- a/crates/huginn-mind/Cargo.toml +++ b/crates/huginn-mind/Cargo.toml @@ -26,6 +26,7 @@ rmp-serde = "1" schemars = "1" serde = { version = "1", features = ["derive"] } serde_json = "1" +serde_path_to_error = "0.1" sha2 = "0.10" [dev-dependencies] diff --git a/crates/huginn-mind/src/envelope.rs b/crates/huginn-mind/src/envelope.rs index a314e37..4ac9544 100644 --- a/crates/huginn-mind/src/envelope.rs +++ b/crates/huginn-mind/src/envelope.rs @@ -70,28 +70,50 @@ pub fn decode_request(message: &CultNetMessage) -> Result<(String, HuginnMindReq )); }; if service_id != MIND_SERVICE_ID { - return Err(OperationFailure::new("wrong-service", format!("{service_id} is not {MIND_SERVICE_ID}"))); + return Err(OperationFailure::new("wrong-service", format!("the service is not {MIND_SERVICE_ID}"))); } if payload_schema != MIND_REQUEST_SCHEMA { return Err(OperationFailure::new( "wrong-payload-schema", - format!("{payload_schema} is not {MIND_REQUEST_SCHEMA}"), + format!("the payload schema is not {MIND_REQUEST_SCHEMA}"), )); } let bytes = STANDARD .decode(payload) - .map_err(|error| OperationFailure::new("payload-not-base64", error.to_string()))?; - let request: HuginnMindRequest = rmp_serde::from_slice(&bytes) - .map_err(|error| OperationFailure::new("payload-not-a-request", error.to_string()))?; + .map_err(|_| OperationFailure::new("payload-not-base64", "the payload is not standard base64"))?; + let request = read_request(&bytes)?; if operation != request.operation() { return Err(OperationFailure::new( "operation-mismatch", - format!("the envelope says {operation} and the payload is {}", request.operation()), + format!("the envelope's operation is not the payload's {}", request.operation()), )); } Ok((message_id.clone(), request)) } +/// The payload as a request, or a failure naming the field path and the class +/// of error and nothing the caller sent: a decoder's own text quotes the +/// offending value (an unknown variant, an integer), so no decoder text +/// leaves this function. +fn read_request(bytes: &[u8]) -> Result { + use rmp_serde::decode::Error as Decode; + let mut decoder = rmp_serde::Deserializer::new(bytes); + serde_path_to_error::deserialize(&mut decoder).map_err(|error| { + let class = match error.inner() { + Decode::InvalidMarkerRead(_) | Decode::InvalidDataRead(_) => "truncated", + Decode::TypeMismatch(_) => "wrong-type", + Decode::OutOfRange => "out-of-range", + Decode::LengthMismatch(_) => "wrong-length", + Decode::Uncategorized(_) | Decode::Syntax(_) => "invalid-value", + Decode::Utf8Error(_) => "invalid-text", + Decode::DepthLimitExceeded => "too-deep", + }; + let path = error.path().to_string(); + let at = if path == "." { "the payload".to_string() } else { format!("field {path}") }; + OperationFailure::new("payload-not-a-request", format!("{at}: {class}")) + }) +} + /// One answer, whose status the response derives. pub fn encode_response( message_id: &str, @@ -184,7 +206,7 @@ mod tests { documents: 0, receipts: 0, index: crate::wire::IndexStatus::Current, - persona: None, + persona: crate::wire::PersonaStatus::Absent, }), "accepted", ), @@ -210,6 +232,82 @@ mod tests { assert_eq!(decode_response(&message).unwrap(), ("m-2".into(), Err(failure))); } + fn request_message(service_id: &str, operation: &str, schema: &str, payload: String) -> CultNetMessage { + CultNetMessage::OperationRequest { + message_id: "m-9".into(), + service_id: service_id.into(), + operation: operation.into(), + payload_schema: schema.into(), + payload_encoding: "messagepack-base64".into(), + payload, + source_runtime_id: None, + target_runtime_id: None, + } + } + + /// The payload of `request` with the value at `path` replaced, encoded the + /// way a client does. + fn payload_with(request: &HuginnMindRequest, path: &[&str], bad: serde_json::Value) -> String { + let mut value = serde_json::to_value(request).unwrap(); + let mut at = &mut value; + for key in path { + at = at.get_mut(*key).unwrap_or_else(|| panic!("no {key} in the request")); + } + *at = bad; + STANDARD.encode(rmp_serde::to_vec_named(&value).unwrap()) + } + + /// A refusal of the decoder names the field and the class of error and + /// nothing the caller sent: not an unknown variant, not an integer, not + /// an envelope field, not a byte of bad base64. Over the persona wire and + /// over the pipeline's, because the decoder is one. + #[test] + fn the_decoder_never_echoes_what_the_caller_sent() { + const CANARY: &str = "CANARY-5c0de1-do-not-echo"; + const NUMBER: i64 = 90817263; + let put = HuginnMindRequest::PersonaPut { + instance: slug(INSTANCE), + provenance: provenance(Faculty::Hands), + state: serde_json::json!({}), + expected_updated_at: None, + }; + let admit = HuginnMindRequest::Admit(PipelineAdmissionBatch { + instance: slug(INSTANCE), + provenance: provenance(Faculty::Hands), + documents: vec![instance(INSTANCE)], + }); + let cases = [ + (&put, vec!["PersonaPut", "provenance", "faculty"], serde_json::json!(CANARY), "provenance.faculty"), + (&put, vec!["PersonaPut", "provenance", "agent"], serde_json::json!(NUMBER), "provenance.agent"), + (&put, vec!["PersonaPut", "expected_updated_at"], serde_json::json!(NUMBER), "expected_updated_at"), + (&put, vec!["PersonaPut", "instance"], serde_json::json!(NUMBER), "instance"), + (&admit, vec!["Admit", "provenance", "faculty"], serde_json::json!(CANARY), "provenance.faculty"), + (&admit, vec!["Admit", "instance"], serde_json::json!(NUMBER), "instance"), + ]; + for (request, path, bad, field) in cases { + let message = request_message(MIND_SERVICE_ID, request.operation(), MIND_REQUEST_SCHEMA, payload_with(request, &path, bad)); + let failure = decode_request(&message).unwrap_err(); + assert_eq!(failure.code, "payload-not-a-request"); + assert!(failure.message.contains(field), "{field} is named: {}", failure.message); + assert!(failure.message.ends_with(": invalid-value"), "the class is named: {}", failure.message); + for echoed in [CANARY.to_string(), NUMBER.to_string()] { + assert!(!failure.message.contains(&echoed), "{echoed} came back: {}", failure.message); + } + } + + let good = payload_with(&put, &["PersonaPut", "expected_updated_at"], serde_json::Value::Null); + let envelope_cases = [ + request_message(CANARY, "persona_put", MIND_REQUEST_SCHEMA, good.clone()), + request_message(MIND_SERVICE_ID, "persona_put", CANARY, good.clone()), + request_message(MIND_SERVICE_ID, CANARY, MIND_REQUEST_SCHEMA, good), + request_message(MIND_SERVICE_ID, "persona_put", MIND_REQUEST_SCHEMA, format!("{CANARY}!!")), + ]; + for message in envelope_cases { + let failure = decode_request(&message).unwrap_err(); + assert!(!failure.message.contains(CANARY), "{} came back: {}", failure.code, failure.message); + } + } + /// The round trip the client and the daemon share, and the one code that /// `serve::answer` cannot reach because it answers a foreign message with /// `Error` instead. diff --git a/crates/huginn-mind/src/lib.rs b/crates/huginn-mind/src/lib.rs index 0e9dc19..67b76d6 100644 --- a/crates/huginn-mind/src/lib.rs +++ b/crates/huginn-mind/src/lib.rs @@ -55,7 +55,7 @@ pub use refusal::MindRefusal; pub use store::{MindStore, OwnedRedbMessagePackBackingStore}; pub use wire::{ DeferredAnswer, HuginnMindRequest, HuginnMindResponse, IndexStatus, MAX_DEFERRED_BODY_BYTES, MIND_REQUEST_SCHEMA, MIND_REQUEST_SCHEMA_JSON, - MIND_RESPONSE_SCHEMA, MIND_RESPONSE_SCHEMA_JSON, MIND_SERVICE_ID, MindStatus, + MIND_RESPONSE_SCHEMA, MIND_RESPONSE_SCHEMA_JSON, MIND_SERVICE_ID, MindStatus, PersonaStatus, }; /// The leaf, whole, through the one crate that pins its rev: the daemon and diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs index 8e1a7a9..9c47518 100644 --- a/crates/huginn-mind/src/persona.rs +++ b/crates/huginn-mind/src/persona.rs @@ -243,7 +243,7 @@ mod tests { mind } - fn persona_in_status(mind: &Mind) -> Option { + fn persona_in_status(mind: &Mind) -> crate::wire::PersonaStatus { mind.status(crate::wire::IndexStatus::Current).persona } @@ -436,7 +436,7 @@ mod tests { fn a_put_is_a_compare_and_swap_on_updated_at() { let store = MemoryStore::new(); let mut mind = seeded_over(&store); - assert_eq!(persona_in_status(&mind), None); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Absent); let receipts = |mind: &Mind| mind.receipts().unwrap().len(); let base = receipts(&mind); @@ -447,7 +447,7 @@ mod tests { let view = mind.persona().unwrap().unwrap(); assert_eq!((view.updated_at.as_str(), view.receipt_id.as_str()), (T1, first.as_str())); assert_eq!(view.value, persona(INSTANCE, T1)); - assert_eq!(persona_in_status(&mind).as_deref(), Some(T1)); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); // Two puts that read the same stored document: the second loses. let second = committed(put(&mut mind, persona(INSTANCE, T2), Some(T1))); @@ -521,7 +521,7 @@ mod tests { with_one.push(entry(INSTANCE, persona(INSTANCE, T1))); let mind = Mind::open_with(planted(with_one.clone()), &yggdrasil).unwrap(); assert_eq!(mind.envelopes().len(), 3); - assert_eq!(persona_in_status(&mind).as_deref(), Some(T1)); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); // Two are no mind's. with_one.push(entry("second", persona(INSTANCE, T2))); @@ -537,6 +537,33 @@ mod tests { assert!(matches!(Mind::open_with(planted(stranger), &yggdrasil).err(), Some(MindRefusal::ForeignStore { .. }))); } + /// Status answers in the door's own terms: a stored persona the door + /// cannot read is `Unreadable`, not the `Absent` of a mind with none, while + /// `PersonaGet` answers `Unavailable` for the same bytes. + #[test] + fn status_says_unreadable_where_the_door_says_unavailable() { + let yggdrasil = slug(INSTANCE); + let cache = crate::mind::schema_cache().unwrap(); + let readable = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: persona(INSTANCE, T1) }).unwrap().0; + let no_stamp = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: json!({}) }).unwrap().0; + let mut undecodable = readable.clone(); + undecodable.payload = vec![0xc1]; + for (row, status) in [ + (readable, crate::wire::PersonaStatus::Stored { updated_at: T1.into() }), + (no_stamp, crate::wire::PersonaStatus::Unreadable), + (undecodable, crate::wire::PersonaStatus::Unreadable), + ] { + let store = MemoryStore::new(); + store.plant(epoch()); + store.plant(prepare(&instance(INSTANCE))); + store.plant(row); + let mind = Mind::open_with(store, &yggdrasil).unwrap(); + assert_eq!(persona_in_status(&mind), status); + assert_eq!(mind.persona().is_err(), status == crate::wire::PersonaStatus::Unreadable); + } + assert_eq!(persona_in_status(&seeded_over(&MemoryStore::new())), crate::wire::PersonaStatus::Absent); + } + #[test] fn the_stored_bytes_are_the_one_slot_array_the_catalogue_describes() { let store = MemoryStore::new(); diff --git a/crates/huginn-mind/src/wire.rs b/crates/huginn-mind/src/wire.rs index e68805a..00cbce0 100644 --- a/crates/huginn-mind/src/wire.rs +++ b/crates/huginn-mind/src/wire.rs @@ -192,8 +192,18 @@ pub struct MindStatus { pub documents: u32, pub receipts: u32, pub index: IndexStatus, - /// The stored persona document's `updatedAt`; none until the first put. - pub persona: Option, + /// The persona door as `PersonaGet` would find it. + pub persona: PersonaStatus, +} + +/// What the persona door holds, in the one vocabulary the door itself answers +/// in: nothing yet, a document with this `updatedAt`, or a stored document the +/// door cannot read (`PersonaGet` and every put answer `Unavailable`). +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum PersonaStatus { + Absent, + Stored { updated_at: String }, + Unreadable, } impl Mind { @@ -215,7 +225,11 @@ impl Mind { documents, receipts, index, - persona: self.stored_updated_at().ok().flatten(), + persona: match self.stored_updated_at() { + Ok(None) => PersonaStatus::Absent, + Ok(Some(updated_at)) => PersonaStatus::Stored { updated_at }, + Err(_) => PersonaStatus::Unreadable, + }, } } } From b759addf3e5287bd0de747500a75a4f28d548461 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 08:38:42 +0200 Subject: [PATCH 06/11] Regenerate the response wire schema for PersonaStatus; lock serde_path_to_error Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 12 ++++++ .../huginn.mind_response.v1.schema.json | 42 ++++++++++++++++--- 2 files changed, 48 insertions(+), 6 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index e288372..7731775 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -820,6 +820,7 @@ dependencies = [ "schemars", "serde", "serde_json", + "serde_path_to_error", "sha2", "tempfile", ] @@ -1628,6 +1629,17 @@ dependencies = [ "zmij", ] +[[package]] +name = "serde_path_to_error" +version = "0.1.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457" +dependencies = [ + "itoa", + "serde", + "serde_core", +] + [[package]] name = "sha2" version = "0.10.9" diff --git a/schemas/cultnet/huginn.mind_response.v1.schema.json b/schemas/cultnet/huginn.mind_response.v1.schema.json index 7e1eeda..e0c48b6 100644 --- a/schemas/cultnet/huginn.mind_response.v1.schema.json +++ b/schemas/cultnet/huginn.mind_response.v1.schema.json @@ -1608,11 +1608,8 @@ "$ref": "#/$defs/Slug" }, "persona": { - "description": "The stored persona document's `updatedAt`; none until the first put.", - "type": [ - "string", - "null" - ] + "description": "The persona door as `PersonaGet` would find it.", + "$ref": "#/$defs/PersonaStatus" }, "receipts": { "type": "integer", @@ -1628,7 +1625,8 @@ "schema_epoch", "documents", "receipts", - "index" + "index", + "persona" ] }, "MutationRecord": { @@ -1747,6 +1745,38 @@ "receipt_id" ] }, + "PersonaStatus": { + "description": "What the persona door holds, in the one vocabulary the door itself answers\nin: nothing yet, a document with this `updatedAt`, or a stored document the\ndoor cannot read (`PersonaGet` and every put answer `Unavailable`).", + "oneOf": [ + { + "type": "string", + "enum": [ + "Absent", + "Unreadable" + ] + }, + { + "type": "object", + "properties": { + "Stored": { + "type": "object", + "properties": { + "updated_at": { + "type": "string" + } + }, + "required": [ + "updated_at" + ] + } + }, + "additionalProperties": false, + "required": [ + "Stored" + ] + } + ] + }, "PipelineAdmissionOutcome": { "description": "How admission ended. `Committed.writes` names every document the batch\nlanded, derived writes included; Cut 11 indexes from it after `admit`\nreturns, and never inside it.", "oneOf": [ From c5af029d20a5f02bd6a43c43680eda6cfc06316a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 08:53:05 +0200 Subject: [PATCH 07/11] Tests follow PersonaStatus: the MCP whoami answers in it, a receipt-less planted row is not a door read Co-Authored-By: Claude Opus 5.5 --- crates/eureka-state/tests/mcp.rs | 4 ++-- crates/huginn-mind/src/persona.rs | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/crates/eureka-state/tests/mcp.rs b/crates/eureka-state/tests/mcp.rs index f4b96d3..ef9b54a 100644 --- a/crates/eureka-state/tests/mcp.rs +++ b/crates/eureka-state/tests/mcp.rs @@ -270,7 +270,7 @@ fn the_persona_tools_round_trip_against_a_live_daemon() { assert!(!error); assert_eq!(nothing, Value::Null); let (_, whoami) = mcp.call("whoami", json!({})); - assert_eq!(whoami["status"]["persona"], Value::Null); + assert_eq!(whoami["status"]["persona"], json!("Absent")); let (error, committed) = mcp.call("persona_put", put(persona(INSTANCE, T1), None)); assert!(!error); @@ -281,7 +281,7 @@ fn the_persona_tools_round_trip_against_a_live_daemon() { assert_eq!(view["value"], persona(INSTANCE, T1)); assert_eq!((view["updated_at"].as_str(), view["receipt_id"].as_str()), (Some(T1), Some(receipt.as_str()))); let (_, whoami) = mcp.call("whoami", json!({})); - assert_eq!(whoami["status"]["persona"], json!(T1)); + assert_eq!(whoami["status"]["persona"], json!({ "Stored": { "updated_at": T1 } })); let (error, stale) = mcp.call("persona_put", put(persona(INSTANCE, T2), None)); assert!(!error, "a stale put is an answer"); diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs index 9c47518..f9c31fe 100644 --- a/crates/huginn-mind/src/persona.rs +++ b/crates/huginn-mind/src/persona.rs @@ -559,7 +559,9 @@ mod tests { store.plant(row); let mind = Mind::open_with(store, &yggdrasil).unwrap(); assert_eq!(persona_in_status(&mind), status); - assert_eq!(mind.persona().is_err(), status == crate::wire::PersonaStatus::Unreadable); + if status == crate::wire::PersonaStatus::Unreadable { + assert!(matches!(mind.persona(), Err(MindRefusal::Unavailable { .. })), "the door answers what the status says"); + } } assert_eq!(persona_in_status(&seeded_over(&MemoryStore::new())), crate::wire::PersonaStatus::Absent); } From 6f483bbe0227389fc3107f1d9562d173214f7b4a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 10:15:44 +0200 Subject: [PATCH 08/11] Persona status goes through persona(): one decision of readability whoami's persona field derived from stored_updated_at, which ignores the writing receipt, while persona_get requires one. Status now matches on persona(), so a receiptless row is Unreadable on both. The test asserts agreement for every planted row and for a put-written row (restoring the is_err equality weakened in c5af029). Co-Authored-By: Claude Opus 5.5 --- crates/huginn-mind/src/persona.rs | 1163 +++++++++++++++-------------- crates/huginn-mind/src/wire.rs | 686 ++++++++--------- 2 files changed, 927 insertions(+), 922 deletions(-) diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs index f9c31fe..9f92455 100644 --- a/crates/huginn-mind/src/persona.rs +++ b/crates/huginn-mind/src/persona.rs @@ -1,579 +1,584 @@ -//! The persona document: one `gamecult.persona_state.v0` per mind, stored -//! opaque and replaced whole. -//! -//! The shape is the published schema's, `schemas/cultnet/`, read here with -//! `include_bytes!`; the mind holds no Rust type for it, only the value that -//! passed the schema. `put_persona` (admission.rs) owns whether a document may -//! enter; this module owns what it is checked against and how it is stored and -//! read back. Nothing here echoes a caller's value: a refusal names a schema -//! location and a keyword, never the text that failed. - -use std::collections::BTreeSet; -use std::sync::OnceLock; - -use cultcache_rs::{CultCacheEnvelope, DatabaseEntry}; -use jsonschema::paths::LocationSegment; -use jsonschema::error::ValidationErrorKind; -use jsonschema::Validator; -use schemars::JsonSchema; -use serde::{Deserialize, Serialize}; -use serde_json::Value; - -use crate::mind::Mind; -use crate::refusal::MindRefusal; -use crate::store::MindStore; - -const PERSONA_SCHEMA: &[u8] = include_bytes!("../../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); - -/// The stored envelope's payload: the document, one slot, keyed by the mind's -/// instance. The cache needs a registered entry type to hold the envelope; the -/// document inside stays a value. -#[derive(Clone, Debug, PartialEq, DatabaseEntry)] -#[cultcache(type = "gamecult.persona_state.v0", schema = "HuginnPersonaEntry")] -pub struct HuginnPersonaEntry { - #[cultcache(key = 0)] - pub value: Value, -} - -/// What `PersonaGet` answers: the stored document, its `updatedAt`, and the -/// receipt of the put that wrote it. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub struct PersonaStateView { - pub value: Value, - pub updated_at: String, - pub receipt_id: String, -} - -/// How a put ended. A refusal is an answer, as for `admit`. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum PersonaPutOutcome { - Committed { receipt_id: String }, - Refused(MindRefusal), -} - -struct Compiled { - validator: Validator, - /// Every property name the schema declares. A path segment outside this - /// set is a caller's key (`traitMap` keys are free), so it is withheld. - declared: BTreeSet, -} - -fn compiled() -> Result<&'static Compiled, MindRefusal> { - static COMPILED: OnceLock> = OnceLock::new(); - COMPILED - .get_or_init(|| { - let schema: Value = serde_json::from_slice(PERSONA_SCHEMA) - .map_err(|error| format!("the published persona schema does not parse: {error}"))?; - let validator = jsonschema::draft7::new(&schema) - .map_err(|error| format!("the published persona schema does not compile: {error}"))?; - let mut declared = BTreeSet::new(); - declared_names(&schema, &mut declared); - Ok(Compiled { validator, declared }) - }) - .as_ref() - .map_err(|detail| MindRefusal::Unavailable { detail: detail.clone() }) -} - -fn declared_names(node: &Value, names: &mut BTreeSet) { - match node { - Value::Object(map) => { - if let Some(Value::Object(properties)) = map.get("properties") { - names.extend(properties.keys().cloned()); - } - map.values().for_each(|child| declared_names(child, names)); - } - Value::Array(items) => items.iter().for_each(|child| declared_names(child, names)), - _ => {} - } -} - -/// Rule 1: the document is valid against the published schema. The first -/// failure is the refusal; it names where and which keyword, never the value. -pub(crate) fn validate_shape(state: &Value) -> Result<(), MindRefusal> { - let compiled = compiled()?; - let Err(error) = compiled.validator.validate(state) else { return Ok(()) }; - let mut path = error - .instance_path() - .segments() - .map(|segment| match segment { - LocationSegment::Index(index) => index.to_string(), - LocationSegment::Property(name) if compiled.declared.contains(name.as_ref()) => name.into_owned(), - LocationSegment::Property(_) => "*".to_string(), - }) - .collect::>(); - match error.kind() { - ValidationErrorKind::Required { property } => path.extend(property.as_str().map(str::to_string)), - ValidationErrorKind::AdditionalProperties { .. } => path.push("*".to_string()), - _ => {} - } - Err(MindRefusal::PersonaInvalid { - path: format!("/{}", path.join("/")), - message: format!("fails the published schema's {} rule", error.kind().keyword()), - }) -} - -/// A stored persona envelope's document. -pub(crate) fn decode(envelope: &CultCacheEnvelope) -> Result { - rmp_serde::from_slice::(&envelope.payload) - .map(|entry| entry.value) - .map_err(|error| MindRefusal::Unavailable { detail: format!("the stored persona does not decode: {error}") }) -} - -/// A document's `updatedAt`; the schema makes it a required string. -pub(crate) fn updated_at(value: &Value) -> Option<&str> { - value.get("updatedAt").and_then(Value::as_str) -} - -impl Mind { - /// This mind's persona envelope, if one is stored. - pub(crate) fn persona_envelope(&self) -> Option<&CultCacheEnvelope> { - self.raw_envelope(HuginnPersonaEntry::TYPE, &self.instance().0) - } - - /// The stored `updatedAt`; none when no persona is stored. - pub(crate) fn stored_updated_at(&self) -> Result, MindRefusal> { - let Some(envelope) = self.persona_envelope() else { return Ok(None) }; - let value = decode(envelope)?; - updated_at(&value) - .map(|stamp| Some(stamp.to_string())) - .ok_or_else(|| MindRefusal::Unavailable { detail: "the stored persona has no updatedAt".into() }) - } - - /// `PersonaGet`: the document, its `updatedAt` and the receipt of the put - /// that wrote exactly these bytes. - pub fn persona(&self) -> Result, MindRefusal> { - let Some(envelope) = self.persona_envelope() else { return Ok(None) }; - let value = decode(envelope)?; - let integrity = |detail: &str| MindRefusal::Unavailable { detail: detail.into() }; - let updated_at = updated_at(&value).ok_or_else(|| integrity("the stored persona has no updatedAt"))?.to_string(); - let identity = (envelope.r#type.as_str(), envelope.key.as_str()); - let receipt_id = self - .receipts()? - .into_iter() - .filter(|receipt| receipt.writes.iter().any(|write| write.identity() == identity)) - .max_by_key(|receipt| receipt.ordinal) - .ok_or_else(|| integrity("the stored persona has no receipt"))? - .receipt_id; - Ok(Some(PersonaStateView { value, updated_at, receipt_id })) - } -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::fixtures::{INSTANCE, OTHER_INSTANCE, epoch, instance, opened, prepare, provenance, seed, slug}; - use crate::receipt::Faculty; - use crate::store::test_stores::{MemoryStore, RefusingStore, SwapCommand}; - use eureka_pipeline::PipelineKind; - use serde_json::json; - - const T1: &str = "2026-10-10T10:00:00Z"; - const T2: &str = "2026-10-10T10:00:01Z"; - const T3: &str = "2026-10-10T10:00:02Z"; - const CANARY: &str = "CANARY-7f3a91-do-not-echo"; - const NOT_LATER: &str = "must be later than the stored updatedAt"; - - /// A minimal document the published schema accepts. The test that follows - /// holds it to the schema file's own required list. - fn persona(id: &str, updated_at: &str) -> Value { - let traits = json!({ - "underlyingOrganization": {}, "stableDispositions": {}, "behavioralDimensions": {}, - "presentationStrategy": {}, "voiceStyle": {}, "situationalState": {} - }); - json!({ - "schemaVersion": "gamecult.persona_state.v0", - "provenance": { - "sourceSystem": "huginn", "sourceDocumentId": id, "sourceUpdatedAt": updated_at, - "exportedAt": updated_at, "authority": "canonical" - }, - "personaId": id, - "publicName": "Test Persona", - "presentation": { "voiceSummary": "plain" }, - "activationProfile": traits, - "thoughtMemory": { "shortTerm": [], "memories": [], "incubation": [] }, - "agencyPressure": { "pressures": [] }, - "candidateActions": { "actions": [] }, - "affect": { - "needs": [], "socialBonds": [], "statusReads": [], "moodDimensions": [], - "socialBiases": [], "doctrineStances": [] - }, - "updatedAt": updated_at - }) - } - - fn schema_file() -> Value { - let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); - serde_json::from_slice(&std::fs::read(path).unwrap()).unwrap() - } - - fn put(mind: &mut Mind, state: Value, expected: Option<&str>) -> PersonaPutOutcome { - let instance = mind.instance().clone(); - mind.put_persona(&instance, state, expected.map(str::to_string), provenance(Faculty::Hands), crate::fixtures::now()) - } - - fn committed(outcome: PersonaPutOutcome) -> String { - match outcome { - PersonaPutOutcome::Committed { receipt_id } => receipt_id, - other => panic!("expected a commit, got {other:?}"), - } - } - - fn refused(outcome: PersonaPutOutcome) -> MindRefusal { - match outcome { - PersonaPutOutcome::Refused(refusal) => refusal, - other => panic!("expected a refusal, got {other:?}"), - } - } - - fn invalid(path: &str, rule: &str) -> MindRefusal { - MindRefusal::PersonaInvalid { path: path.into(), message: format!("fails the published schema's {rule} rule") } - } - - fn not_later() -> MindRefusal { - MindRefusal::PersonaInvalid { path: "/updatedAt".into(), message: NOT_LATER.into() } - } - - fn stale(stored: Option<&str>) -> MindRefusal { - MindRefusal::PersonaStale { stored: stored.map(str::to_string) } - } - - fn seeded_over(store: &MemoryStore) -> Mind { - let mut mind = opened(store.clone(), INSTANCE); - seed(&mut mind); - mind - } - - fn persona_in_status(mind: &Mind) -> crate::wire::PersonaStatus { - mind.status(crate::wire::IndexStatus::Current).persona - } - - #[test] - fn the_fixture_is_valid_against_the_published_file_and_covers_its_required_fields() { - let schema = schema_file(); - let validator = jsonschema::draft7::new(&schema).unwrap(); - let document = persona(INSTANCE, T1); - assert!(validator.is_valid(&document)); - for name in schema["required"].as_array().unwrap() { - assert!(document.get(name.as_str().unwrap()).is_some(), "the fixture lacks {name}"); - } - } - - #[test] - fn declared_names_are_every_property_name_at_any_depth() { - let schema = json!({ - "properties": { "a": { "properties": { "b": {} } } }, - "allOf": [{ "properties": { "c": {} } }], - "definitions": { "d": { "properties": { "e": {} } } }, - "required": ["not-a-property"] - }); - let mut names = BTreeSet::new(); - declared_names(&schema, &mut names); - assert_eq!(names, BTreeSet::from(["a", "b", "c", "e"].map(String::from))); - } - - /// `identity-write-all-visible`: a put may change any field, the identity - /// fields included, and a change the next second is no less admissible. - #[test] - fn a_put_may_rewrite_identity_fields_and_every_change_lands() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - committed(put(&mut mind, persona(INSTANCE, T1), None)); - - let mut renamed = persona(INSTANCE, T2); - renamed["publicName"] = json!("A New Name"); - renamed["publicDescription"] = json!("who she says she is"); - renamed["presentation"] = json!({ "voiceSummary": "warmer", "pronouns": "she/her" }); - renamed["values"] = json!([{ "id": "v1", "label": "candor", "priority": 0.9 }]); - committed(put(&mut mind, renamed.clone(), Some(T1))); - assert_eq!(mind.persona().unwrap().unwrap().value, renamed); - - let mut again = persona(INSTANCE, T3); - again["publicName"] = json!("Another Name"); - committed(put(&mut mind, again.clone(), Some(T2))); - assert_eq!(mind.persona().unwrap().unwrap().value, again); - } - - #[test] - fn the_view_names_the_receipt_of_the_latest_put() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let mut previous: Option = None; - for second in 0..5 { - let stamp = format!("2026-10-10T10:00:0{second}Z"); - let receipt = committed(put(&mut mind, persona(INSTANCE, &stamp), previous.as_deref())); - assert_eq!(mind.persona().unwrap().unwrap().receipt_id, receipt, "after put {second}"); - previous = Some(stamp); - } - } - - #[test] - fn a_persona_document_is_validated_at_the_door() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let before = store.rows(); - - for name in schema_file()["required"].as_array().unwrap() { - let name = name.as_str().unwrap(); - let mut document = persona(INSTANCE, T1); - document.as_object_mut().unwrap().remove(name); - assert_eq!(refused(put(&mut mind, document, None)), invalid(&format!("/{name}"), "required"), "{name}"); - } - - let mut extra = persona(INSTANCE, T1); - extra["notInTheSchema"] = json!(1); - assert_eq!(refused(put(&mut mind, extra, None)), invalid("/*", "additionalProperties")); - - let mut wrong_type = persona(INSTANCE, T1); - wrong_type["publicName"] = json!(5); - assert_eq!(refused(put(&mut mind, wrong_type, None)), invalid("/publicName", "type")); - - let mut bad_stamp = persona(INSTANCE, T1); - bad_stamp["updatedAt"] = json!("yesterday"); - assert_eq!(refused(put(&mut mind, bad_stamp, None)), invalid("/updatedAt", "format")); - - let mut nested = persona(INSTANCE, T1); - nested["thoughtMemory"]["memories"] = json!([7]); - assert_eq!(refused(put(&mut mind, nested, None)), invalid("/thoughtMemory/memories/0", "type")); - - let mut free_key = persona(INSTANCE, T1); - free_key["activationProfile"]["voiceStyle"]["any-key"] = json!({}); - assert_eq!( - refused(put(&mut mind, free_key, None)), - invalid("/activationProfile/voiceStyle/*/mean", "required"), - "a key the schema does not declare is withheld from the path" - ); - - assert_eq!(store.rows(), before, "no refusal wrote anything"); - assert_eq!(mind.persona().unwrap(), None); - } - - #[test] - fn a_refusal_never_echoes_what_the_caller_sent() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - committed(put(&mut mind, persona(INSTANCE, T2), None)); - - let mut free_key = persona(INSTANCE, T3); - free_key["activationProfile"]["voiceStyle"][CANARY] = json!({}); - let mut extra_key = persona(INSTANCE, T3); - extra_key[CANARY] = json!(CANARY); - let mut bad_value = persona(INSTANCE, T3); - bad_value["updatedAt"] = json!(CANARY); - let mut bad_enum = persona(INSTANCE, T3); - bad_enum["provenance"]["authority"] = json!(CANARY); - let mut foreign = persona(CANARY, T3); - foreign["publicName"] = json!(CANARY); - let mut imported = persona(INSTANCE, T3); - imported["provenance"]["authority"] = json!("import"); - imported["provenance"]["sourceSystem"] = json!(CANARY); - let mut late = persona(INSTANCE, T1); - late["publicName"] = json!(CANARY); - - let cases: Vec<(Value, Option<&str>)> = vec![ - (free_key, Some(T2)), - (extra_key, Some(T2)), - (bad_value, Some(T2)), - (bad_enum, Some(T2)), - (foreign, Some(T2)), - (imported, Some(T2)), - (late, Some(T2)), - (persona(INSTANCE, T3), Some(CANARY)), - ]; - for (document, expected) in cases { - let refusal = refused(put(&mut mind, document, expected)); - assert!(!format!("{refusal:?}").contains(CANARY), "{refusal:?}"); - assert!(!serde_json::to_string(&refusal).unwrap().contains(CANARY)); - } - } - - #[test] - fn persona_id_must_be_the_instance() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let before = store.rows(); - let refusal = refused(put(&mut mind, persona(OTHER_INSTANCE, T1), None)); - assert_eq!(refusal, MindRefusal::PersonaForeign { instance: INSTANCE.into() }); - assert_eq!(store.rows(), before); - assert_eq!(mind.persona().unwrap(), None); - } - - #[test] - fn only_a_canonical_document_is_the_minds_persona() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - for authority in ["projection", "import"] { - let mut document = persona(INSTANCE, T1); - document["provenance"]["authority"] = json!(authority); - assert_eq!(refused(put(&mut mind, document, None)), MindRefusal::PersonaNotCanonical, "{authority}"); - } - assert_eq!(mind.persona().unwrap(), None); - } - - #[test] - fn a_persona_waits_for_the_minds_identity() { - let mut mind = opened(MemoryStore::new(), INSTANCE); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), None)), MindRefusal::MissingIdentity); - assert!(mind.is_empty()); - } - - #[test] - fn a_put_must_name_this_mind_and_a_named_asker() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let before = store.rows(); - let other = slug(OTHER_INSTANCE); - let outcome = mind.put_persona(&other, persona(INSTANCE, T1), None, provenance(Faculty::Hands), crate::fixtures::now()); - assert!(matches!(refused(outcome), MindRefusal::ForeignInstance { .. })); - let mut unnamed = provenance(Faculty::Hands); - unnamed.agent = eureka_pipeline::Short(" ".into()); - let instance = mind.instance().clone(); - let outcome = mind.put_persona(&instance, persona(INSTANCE, T1), None, unnamed, crate::fixtures::now()); - assert!(matches!(refused(outcome), MindRefusal::Document(_))); - assert_eq!(store.rows(), before); - } - - #[test] - fn a_put_is_a_compare_and_swap_on_updated_at() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Absent); - let receipts = |mind: &Mind| mind.receipts().unwrap().len(); - let base = receipts(&mind); - - // A first put expects nothing; claiming a stored document is stale. - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T1))), stale(None)); - let first = committed(put(&mut mind, persona(INSTANCE, T1), None)); - assert_eq!(receipts(&mind), base + 1); - let view = mind.persona().unwrap().unwrap(); - assert_eq!((view.updated_at.as_str(), view.receipt_id.as_str()), (T1, first.as_str())); - assert_eq!(view.value, persona(INSTANCE, T1)); - assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); - - // Two puts that read the same stored document: the second loses. - let second = committed(put(&mut mind, persona(INSTANCE, T2), Some(T1))); - assert_eq!(receipts(&mind), base + 2); - let rows = store.rows(); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), Some(T1))), stale(Some(T2))); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), None)), stale(Some(T2))); - assert_eq!(store.rows(), rows, "a stale put wrote nothing"); - - // The right expectation with an updatedAt that is not later. - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T2))), not_later()); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T2))), not_later()); - // Instants compare, not spellings: the same instant at another offset is not later. - assert_eq!(refused(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:01+02:00"), Some(T2))), not_later()); - assert_eq!(store.rows(), rows); - assert_eq!(receipts(&mind), base + 2); - committed(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:02+02:00"), Some(T2))); - assert_eq!(receipts(&mind), base + 3); - - // The second put's receipt read the first document and wrote the second. - let receipt = mind.receipts().unwrap().into_iter().find(|receipt| receipt.receipt_id == second).unwrap(); - assert_eq!((receipt.strong_reads.len(), receipt.writes.len()), (1, 1)); - assert_eq!(receipt.strong_reads[0].document_key, INSTANCE); - assert_ne!(receipt.strong_reads[0].payload_msgpack, receipt.writes[0].payload_msgpack); - assert_eq!(receipt.provenance, provenance(Faculty::Hands)); - } - - #[test] - fn a_put_whose_swap_is_lost_is_stale_and_changes_nothing() { - let store = RefusingStore::new(); - let mut mind = opened(store.clone(), INSTANCE); - seed(&mut mind); - committed(put(&mut mind, persona(INSTANCE, T1), None)); - let rows = store.rows(); - store.command(SwapCommand::Lose); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T1))), stale(Some(T1))); - assert_eq!(store.rows(), rows); - } - - #[test] - fn the_persona_is_not_a_pipeline_document_and_a_batch_cannot_carry_it() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let documents = mind.status(crate::wire::IndexStatus::Current).documents; - committed(put(&mut mind, persona(INSTANCE, T1), None)); - assert_eq!(mind.status(crate::wire::IndexStatus::Current).documents, documents); - assert!(PipelineKind::ALL.iter().all(|kind| kind.type_id() != HuginnPersonaEntry::TYPE)); - let forged = mind.persona_envelope().unwrap().clone(); - let instance = mind.instance().clone(); - let outcome = mind.admit_prepared(&instance, provenance(Faculty::Hands), vec![forged], crate::fixtures::now()); - assert!(matches!(outcome, crate::admission::PipelineAdmissionOutcome::Refused(_)), "{outcome:?}"); - } - - #[test] - fn one_persona_per_mind_and_the_store_still_opens() { - let yggdrasil = slug(INSTANCE); - let cache = crate::mind::schema_cache().unwrap(); - let entry = |key: &str, value: Value| cache.prepare_entry_named(key, &HuginnPersonaEntry { value }).unwrap().0; - let planted = |rows: Vec| { - let store = MemoryStore::new(); - rows.into_iter().for_each(|row| store.plant(row)); - store - }; - let base = || vec![epoch(), prepare(&instance(INSTANCE))]; - - // A store written before this type existed opens unchanged. - assert!(Mind::open_with(planted(base()), &yggdrasil).is_ok()); - - // One persona opens and reads back. - let mut with_one = base(); - with_one.push(entry(INSTANCE, persona(INSTANCE, T1))); - let mind = Mind::open_with(planted(with_one.clone()), &yggdrasil).unwrap(); - assert_eq!(mind.envelopes().len(), 3); - assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); - - // Two are no mind's. - with_one.push(entry("second", persona(INSTANCE, T2))); - assert_eq!( - Mind::open_with(planted(with_one), &yggdrasil).err(), - Some(MindRefusal::ForeignStore { r#type: HuginnPersonaEntry::TYPE.into() }) - ); - // The opener still refuses a type that is not one of the seventeen. - let mut stranger = base(); - let mut foreign = entry(INSTANCE, persona(INSTANCE, T1)); - foreign.r#type = "gamecult.persona_state.v1".into(); - stranger.push(foreign); - assert!(matches!(Mind::open_with(planted(stranger), &yggdrasil).err(), Some(MindRefusal::ForeignStore { .. }))); - } - - /// Status answers in the door's own terms: a stored persona the door - /// cannot read is `Unreadable`, not the `Absent` of a mind with none, while - /// `PersonaGet` answers `Unavailable` for the same bytes. - #[test] - fn status_says_unreadable_where_the_door_says_unavailable() { - let yggdrasil = slug(INSTANCE); - let cache = crate::mind::schema_cache().unwrap(); - let readable = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: persona(INSTANCE, T1) }).unwrap().0; - let no_stamp = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: json!({}) }).unwrap().0; - let mut undecodable = readable.clone(); - undecodable.payload = vec![0xc1]; - for (row, status) in [ - (readable, crate::wire::PersonaStatus::Stored { updated_at: T1.into() }), - (no_stamp, crate::wire::PersonaStatus::Unreadable), - (undecodable, crate::wire::PersonaStatus::Unreadable), - ] { - let store = MemoryStore::new(); - store.plant(epoch()); - store.plant(prepare(&instance(INSTANCE))); - store.plant(row); - let mind = Mind::open_with(store, &yggdrasil).unwrap(); - assert_eq!(persona_in_status(&mind), status); - if status == crate::wire::PersonaStatus::Unreadable { - assert!(matches!(mind.persona(), Err(MindRefusal::Unavailable { .. })), "the door answers what the status says"); - } - } - assert_eq!(persona_in_status(&seeded_over(&MemoryStore::new())), crate::wire::PersonaStatus::Absent); - } - - #[test] - fn the_stored_bytes_are_the_one_slot_array_the_catalogue_describes() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - committed(put(&mut mind, persona(INSTANCE, T1), None)); - let envelope = mind.persona_envelope().unwrap(); - assert_eq!((envelope.r#type.as_str(), envelope.key.as_str()), ("gamecult.persona_state.v0", INSTANCE)); - let slots: (Value,) = rmp_serde::from_slice(&envelope.payload).unwrap(); - assert_eq!(slots.0, persona(INSTANCE, T1)); - } -} +//! The persona document: one `gamecult.persona_state.v0` per mind, stored +//! opaque and replaced whole. +//! +//! The shape is the published schema's, `schemas/cultnet/`, read here with +//! `include_bytes!`; the mind holds no Rust type for it, only the value that +//! passed the schema. `put_persona` (admission.rs) owns whether a document may +//! enter; this module owns what it is checked against and how it is stored and +//! read back. Nothing here echoes a caller's value: a refusal names a schema +//! location and a keyword, never the text that failed. + +use std::collections::BTreeSet; +use std::sync::OnceLock; + +use cultcache_rs::{CultCacheEnvelope, DatabaseEntry}; +use jsonschema::paths::LocationSegment; +use jsonschema::error::ValidationErrorKind; +use jsonschema::Validator; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use crate::mind::Mind; +use crate::refusal::MindRefusal; +use crate::store::MindStore; + +const PERSONA_SCHEMA: &[u8] = include_bytes!("../../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); + +/// The stored envelope's payload: the document, one slot, keyed by the mind's +/// instance. The cache needs a registered entry type to hold the envelope; the +/// document inside stays a value. +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache(type = "gamecult.persona_state.v0", schema = "HuginnPersonaEntry")] +pub struct HuginnPersonaEntry { + #[cultcache(key = 0)] + pub value: Value, +} + +/// What `PersonaGet` answers: the stored document, its `updatedAt`, and the +/// receipt of the put that wrote it. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub struct PersonaStateView { + pub value: Value, + pub updated_at: String, + pub receipt_id: String, +} + +/// How a put ended. A refusal is an answer, as for `admit`. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum PersonaPutOutcome { + Committed { receipt_id: String }, + Refused(MindRefusal), +} + +struct Compiled { + validator: Validator, + /// Every property name the schema declares. A path segment outside this + /// set is a caller's key (`traitMap` keys are free), so it is withheld. + declared: BTreeSet, +} + +fn compiled() -> Result<&'static Compiled, MindRefusal> { + static COMPILED: OnceLock> = OnceLock::new(); + COMPILED + .get_or_init(|| { + let schema: Value = serde_json::from_slice(PERSONA_SCHEMA) + .map_err(|error| format!("the published persona schema does not parse: {error}"))?; + let validator = jsonschema::draft7::new(&schema) + .map_err(|error| format!("the published persona schema does not compile: {error}"))?; + let mut declared = BTreeSet::new(); + declared_names(&schema, &mut declared); + Ok(Compiled { validator, declared }) + }) + .as_ref() + .map_err(|detail| MindRefusal::Unavailable { detail: detail.clone() }) +} + +fn declared_names(node: &Value, names: &mut BTreeSet) { + match node { + Value::Object(map) => { + if let Some(Value::Object(properties)) = map.get("properties") { + names.extend(properties.keys().cloned()); + } + map.values().for_each(|child| declared_names(child, names)); + } + Value::Array(items) => items.iter().for_each(|child| declared_names(child, names)), + _ => {} + } +} + +/// Rule 1: the document is valid against the published schema. The first +/// failure is the refusal; it names where and which keyword, never the value. +pub(crate) fn validate_shape(state: &Value) -> Result<(), MindRefusal> { + let compiled = compiled()?; + let Err(error) = compiled.validator.validate(state) else { return Ok(()) }; + let mut path = error + .instance_path() + .segments() + .map(|segment| match segment { + LocationSegment::Index(index) => index.to_string(), + LocationSegment::Property(name) if compiled.declared.contains(name.as_ref()) => name.into_owned(), + LocationSegment::Property(_) => "*".to_string(), + }) + .collect::>(); + match error.kind() { + ValidationErrorKind::Required { property } => path.extend(property.as_str().map(str::to_string)), + ValidationErrorKind::AdditionalProperties { .. } => path.push("*".to_string()), + _ => {} + } + Err(MindRefusal::PersonaInvalid { + path: format!("/{}", path.join("/")), + message: format!("fails the published schema's {} rule", error.kind().keyword()), + }) +} + +/// A stored persona envelope's document. +pub(crate) fn decode(envelope: &CultCacheEnvelope) -> Result { + rmp_serde::from_slice::(&envelope.payload) + .map(|entry| entry.value) + .map_err(|error| MindRefusal::Unavailable { detail: format!("the stored persona does not decode: {error}") }) +} + +/// A document's `updatedAt`; the schema makes it a required string. +pub(crate) fn updated_at(value: &Value) -> Option<&str> { + value.get("updatedAt").and_then(Value::as_str) +} + +impl Mind { + /// This mind's persona envelope, if one is stored. + pub(crate) fn persona_envelope(&self) -> Option<&CultCacheEnvelope> { + self.raw_envelope(HuginnPersonaEntry::TYPE, &self.instance().0) + } + + /// The stored `updatedAt`; none when no persona is stored. + pub(crate) fn stored_updated_at(&self) -> Result, MindRefusal> { + let Some(envelope) = self.persona_envelope() else { return Ok(None) }; + let value = decode(envelope)?; + updated_at(&value) + .map(|stamp| Some(stamp.to_string())) + .ok_or_else(|| MindRefusal::Unavailable { detail: "the stored persona has no updatedAt".into() }) + } + + /// `PersonaGet`: the document, its `updatedAt` and the receipt of the put + /// that wrote exactly these bytes. + pub fn persona(&self) -> Result, MindRefusal> { + let Some(envelope) = self.persona_envelope() else { return Ok(None) }; + let value = decode(envelope)?; + let integrity = |detail: &str| MindRefusal::Unavailable { detail: detail.into() }; + let updated_at = updated_at(&value).ok_or_else(|| integrity("the stored persona has no updatedAt"))?.to_string(); + let identity = (envelope.r#type.as_str(), envelope.key.as_str()); + let receipt_id = self + .receipts()? + .into_iter() + .filter(|receipt| receipt.writes.iter().any(|write| write.identity() == identity)) + .max_by_key(|receipt| receipt.ordinal) + .ok_or_else(|| integrity("the stored persona has no receipt"))? + .receipt_id; + Ok(Some(PersonaStateView { value, updated_at, receipt_id })) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::fixtures::{INSTANCE, OTHER_INSTANCE, epoch, instance, opened, prepare, provenance, seed, slug}; + use crate::receipt::Faculty; + use crate::store::test_stores::{MemoryStore, RefusingStore, SwapCommand}; + use eureka_pipeline::PipelineKind; + use serde_json::json; + + const T1: &str = "2026-10-10T10:00:00Z"; + const T2: &str = "2026-10-10T10:00:01Z"; + const T3: &str = "2026-10-10T10:00:02Z"; + const CANARY: &str = "CANARY-7f3a91-do-not-echo"; + const NOT_LATER: &str = "must be later than the stored updatedAt"; + + /// A minimal document the published schema accepts. The test that follows + /// holds it to the schema file's own required list. + fn persona(id: &str, updated_at: &str) -> Value { + let traits = json!({ + "underlyingOrganization": {}, "stableDispositions": {}, "behavioralDimensions": {}, + "presentationStrategy": {}, "voiceStyle": {}, "situationalState": {} + }); + json!({ + "schemaVersion": "gamecult.persona_state.v0", + "provenance": { + "sourceSystem": "huginn", "sourceDocumentId": id, "sourceUpdatedAt": updated_at, + "exportedAt": updated_at, "authority": "canonical" + }, + "personaId": id, + "publicName": "Test Persona", + "presentation": { "voiceSummary": "plain" }, + "activationProfile": traits, + "thoughtMemory": { "shortTerm": [], "memories": [], "incubation": [] }, + "agencyPressure": { "pressures": [] }, + "candidateActions": { "actions": [] }, + "affect": { + "needs": [], "socialBonds": [], "statusReads": [], "moodDimensions": [], + "socialBiases": [], "doctrineStances": [] + }, + "updatedAt": updated_at + }) + } + + fn schema_file() -> Value { + let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); + serde_json::from_slice(&std::fs::read(path).unwrap()).unwrap() + } + + fn put(mind: &mut Mind, state: Value, expected: Option<&str>) -> PersonaPutOutcome { + let instance = mind.instance().clone(); + mind.put_persona(&instance, state, expected.map(str::to_string), provenance(Faculty::Hands), crate::fixtures::now()) + } + + fn committed(outcome: PersonaPutOutcome) -> String { + match outcome { + PersonaPutOutcome::Committed { receipt_id } => receipt_id, + other => panic!("expected a commit, got {other:?}"), + } + } + + fn refused(outcome: PersonaPutOutcome) -> MindRefusal { + match outcome { + PersonaPutOutcome::Refused(refusal) => refusal, + other => panic!("expected a refusal, got {other:?}"), + } + } + + fn invalid(path: &str, rule: &str) -> MindRefusal { + MindRefusal::PersonaInvalid { path: path.into(), message: format!("fails the published schema's {rule} rule") } + } + + fn not_later() -> MindRefusal { + MindRefusal::PersonaInvalid { path: "/updatedAt".into(), message: NOT_LATER.into() } + } + + fn stale(stored: Option<&str>) -> MindRefusal { + MindRefusal::PersonaStale { stored: stored.map(str::to_string) } + } + + fn seeded_over(store: &MemoryStore) -> Mind { + let mut mind = opened(store.clone(), INSTANCE); + seed(&mut mind); + mind + } + + fn persona_in_status(mind: &Mind) -> crate::wire::PersonaStatus { + mind.status(crate::wire::IndexStatus::Current).persona + } + + #[test] + fn the_fixture_is_valid_against_the_published_file_and_covers_its_required_fields() { + let schema = schema_file(); + let validator = jsonschema::draft7::new(&schema).unwrap(); + let document = persona(INSTANCE, T1); + assert!(validator.is_valid(&document)); + for name in schema["required"].as_array().unwrap() { + assert!(document.get(name.as_str().unwrap()).is_some(), "the fixture lacks {name}"); + } + } + + #[test] + fn declared_names_are_every_property_name_at_any_depth() { + let schema = json!({ + "properties": { "a": { "properties": { "b": {} } } }, + "allOf": [{ "properties": { "c": {} } }], + "definitions": { "d": { "properties": { "e": {} } } }, + "required": ["not-a-property"] + }); + let mut names = BTreeSet::new(); + declared_names(&schema, &mut names); + assert_eq!(names, BTreeSet::from(["a", "b", "c", "e"].map(String::from))); + } + + /// `identity-write-all-visible`: a put may change any field, the identity + /// fields included, and a change the next second is no less admissible. + #[test] + fn a_put_may_rewrite_identity_fields_and_every_change_lands() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + + let mut renamed = persona(INSTANCE, T2); + renamed["publicName"] = json!("A New Name"); + renamed["publicDescription"] = json!("who she says she is"); + renamed["presentation"] = json!({ "voiceSummary": "warmer", "pronouns": "she/her" }); + renamed["values"] = json!([{ "id": "v1", "label": "candor", "priority": 0.9 }]); + committed(put(&mut mind, renamed.clone(), Some(T1))); + assert_eq!(mind.persona().unwrap().unwrap().value, renamed); + + let mut again = persona(INSTANCE, T3); + again["publicName"] = json!("Another Name"); + committed(put(&mut mind, again.clone(), Some(T2))); + assert_eq!(mind.persona().unwrap().unwrap().value, again); + } + + #[test] + fn the_view_names_the_receipt_of_the_latest_put() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let mut previous: Option = None; + for second in 0..5 { + let stamp = format!("2026-10-10T10:00:0{second}Z"); + let receipt = committed(put(&mut mind, persona(INSTANCE, &stamp), previous.as_deref())); + assert_eq!(mind.persona().unwrap().unwrap().receipt_id, receipt, "after put {second}"); + previous = Some(stamp); + } + } + + #[test] + fn a_persona_document_is_validated_at_the_door() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + + for name in schema_file()["required"].as_array().unwrap() { + let name = name.as_str().unwrap(); + let mut document = persona(INSTANCE, T1); + document.as_object_mut().unwrap().remove(name); + assert_eq!(refused(put(&mut mind, document, None)), invalid(&format!("/{name}"), "required"), "{name}"); + } + + let mut extra = persona(INSTANCE, T1); + extra["notInTheSchema"] = json!(1); + assert_eq!(refused(put(&mut mind, extra, None)), invalid("/*", "additionalProperties")); + + let mut wrong_type = persona(INSTANCE, T1); + wrong_type["publicName"] = json!(5); + assert_eq!(refused(put(&mut mind, wrong_type, None)), invalid("/publicName", "type")); + + let mut bad_stamp = persona(INSTANCE, T1); + bad_stamp["updatedAt"] = json!("yesterday"); + assert_eq!(refused(put(&mut mind, bad_stamp, None)), invalid("/updatedAt", "format")); + + let mut nested = persona(INSTANCE, T1); + nested["thoughtMemory"]["memories"] = json!([7]); + assert_eq!(refused(put(&mut mind, nested, None)), invalid("/thoughtMemory/memories/0", "type")); + + let mut free_key = persona(INSTANCE, T1); + free_key["activationProfile"]["voiceStyle"]["any-key"] = json!({}); + assert_eq!( + refused(put(&mut mind, free_key, None)), + invalid("/activationProfile/voiceStyle/*/mean", "required"), + "a key the schema does not declare is withheld from the path" + ); + + assert_eq!(store.rows(), before, "no refusal wrote anything"); + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn a_refusal_never_echoes_what_the_caller_sent() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T2), None)); + + let mut free_key = persona(INSTANCE, T3); + free_key["activationProfile"]["voiceStyle"][CANARY] = json!({}); + let mut extra_key = persona(INSTANCE, T3); + extra_key[CANARY] = json!(CANARY); + let mut bad_value = persona(INSTANCE, T3); + bad_value["updatedAt"] = json!(CANARY); + let mut bad_enum = persona(INSTANCE, T3); + bad_enum["provenance"]["authority"] = json!(CANARY); + let mut foreign = persona(CANARY, T3); + foreign["publicName"] = json!(CANARY); + let mut imported = persona(INSTANCE, T3); + imported["provenance"]["authority"] = json!("import"); + imported["provenance"]["sourceSystem"] = json!(CANARY); + let mut late = persona(INSTANCE, T1); + late["publicName"] = json!(CANARY); + + let cases: Vec<(Value, Option<&str>)> = vec![ + (free_key, Some(T2)), + (extra_key, Some(T2)), + (bad_value, Some(T2)), + (bad_enum, Some(T2)), + (foreign, Some(T2)), + (imported, Some(T2)), + (late, Some(T2)), + (persona(INSTANCE, T3), Some(CANARY)), + ]; + for (document, expected) in cases { + let refusal = refused(put(&mut mind, document, expected)); + assert!(!format!("{refusal:?}").contains(CANARY), "{refusal:?}"); + assert!(!serde_json::to_string(&refusal).unwrap().contains(CANARY)); + } + } + + #[test] + fn persona_id_must_be_the_instance() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + let refusal = refused(put(&mut mind, persona(OTHER_INSTANCE, T1), None)); + assert_eq!(refusal, MindRefusal::PersonaForeign { instance: INSTANCE.into() }); + assert_eq!(store.rows(), before); + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn only_a_canonical_document_is_the_minds_persona() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + for authority in ["projection", "import"] { + let mut document = persona(INSTANCE, T1); + document["provenance"]["authority"] = json!(authority); + assert_eq!(refused(put(&mut mind, document, None)), MindRefusal::PersonaNotCanonical, "{authority}"); + } + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn a_persona_waits_for_the_minds_identity() { + let mut mind = opened(MemoryStore::new(), INSTANCE); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), None)), MindRefusal::MissingIdentity); + assert!(mind.is_empty()); + } + + #[test] + fn a_put_must_name_this_mind_and_a_named_asker() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + let other = slug(OTHER_INSTANCE); + let outcome = mind.put_persona(&other, persona(INSTANCE, T1), None, provenance(Faculty::Hands), crate::fixtures::now()); + assert!(matches!(refused(outcome), MindRefusal::ForeignInstance { .. })); + let mut unnamed = provenance(Faculty::Hands); + unnamed.agent = eureka_pipeline::Short(" ".into()); + let instance = mind.instance().clone(); + let outcome = mind.put_persona(&instance, persona(INSTANCE, T1), None, unnamed, crate::fixtures::now()); + assert!(matches!(refused(outcome), MindRefusal::Document(_))); + assert_eq!(store.rows(), before); + } + + #[test] + fn a_put_is_a_compare_and_swap_on_updated_at() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Absent); + let receipts = |mind: &Mind| mind.receipts().unwrap().len(); + let base = receipts(&mind); + + // A first put expects nothing; claiming a stored document is stale. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T1))), stale(None)); + let first = committed(put(&mut mind, persona(INSTANCE, T1), None)); + assert_eq!(receipts(&mind), base + 1); + let view = mind.persona().unwrap().unwrap(); + assert_eq!((view.updated_at.as_str(), view.receipt_id.as_str()), (T1, first.as_str())); + assert_eq!(view.value, persona(INSTANCE, T1)); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); + + // Two puts that read the same stored document: the second loses. + let second = committed(put(&mut mind, persona(INSTANCE, T2), Some(T1))); + assert_eq!(receipts(&mind), base + 2); + let rows = store.rows(); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), Some(T1))), stale(Some(T2))); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), None)), stale(Some(T2))); + assert_eq!(store.rows(), rows, "a stale put wrote nothing"); + + // The right expectation with an updatedAt that is not later. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T2))), not_later()); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T2))), not_later()); + // Instants compare, not spellings: the same instant at another offset is not later. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:01+02:00"), Some(T2))), not_later()); + assert_eq!(store.rows(), rows); + assert_eq!(receipts(&mind), base + 2); + committed(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:02+02:00"), Some(T2))); + assert_eq!(receipts(&mind), base + 3); + + // The second put's receipt read the first document and wrote the second. + let receipt = mind.receipts().unwrap().into_iter().find(|receipt| receipt.receipt_id == second).unwrap(); + assert_eq!((receipt.strong_reads.len(), receipt.writes.len()), (1, 1)); + assert_eq!(receipt.strong_reads[0].document_key, INSTANCE); + assert_ne!(receipt.strong_reads[0].payload_msgpack, receipt.writes[0].payload_msgpack); + assert_eq!(receipt.provenance, provenance(Faculty::Hands)); + } + + #[test] + fn a_put_whose_swap_is_lost_is_stale_and_changes_nothing() { + let store = RefusingStore::new(); + let mut mind = opened(store.clone(), INSTANCE); + seed(&mut mind); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + let rows = store.rows(); + store.command(SwapCommand::Lose); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T1))), stale(Some(T1))); + assert_eq!(store.rows(), rows); + } + + #[test] + fn the_persona_is_not_a_pipeline_document_and_a_batch_cannot_carry_it() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let documents = mind.status(crate::wire::IndexStatus::Current).documents; + committed(put(&mut mind, persona(INSTANCE, T1), None)); + assert_eq!(mind.status(crate::wire::IndexStatus::Current).documents, documents); + assert!(PipelineKind::ALL.iter().all(|kind| kind.type_id() != HuginnPersonaEntry::TYPE)); + let forged = mind.persona_envelope().unwrap().clone(); + let instance = mind.instance().clone(); + let outcome = mind.admit_prepared(&instance, provenance(Faculty::Hands), vec![forged], crate::fixtures::now()); + assert!(matches!(outcome, crate::admission::PipelineAdmissionOutcome::Refused(_)), "{outcome:?}"); + } + + #[test] + fn one_persona_per_mind_and_the_store_still_opens() { + let yggdrasil = slug(INSTANCE); + let cache = crate::mind::schema_cache().unwrap(); + let entry = |key: &str, value: Value| cache.prepare_entry_named(key, &HuginnPersonaEntry { value }).unwrap().0; + let planted = |rows: Vec| { + let store = MemoryStore::new(); + rows.into_iter().for_each(|row| store.plant(row)); + store + }; + let base = || vec![epoch(), prepare(&instance(INSTANCE))]; + + // A store written before this type existed opens unchanged. + assert!(Mind::open_with(planted(base()), &yggdrasil).is_ok()); + + // One persona opens and reads back. + let mut with_one = base(); + with_one.push(entry(INSTANCE, persona(INSTANCE, T1))); + let mind = Mind::open_with(planted(with_one.clone()), &yggdrasil).unwrap(); + assert_eq!(mind.envelopes().len(), 3); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); + + // Two are no mind's. + with_one.push(entry("second", persona(INSTANCE, T2))); + assert_eq!( + Mind::open_with(planted(with_one), &yggdrasil).err(), + Some(MindRefusal::ForeignStore { r#type: HuginnPersonaEntry::TYPE.into() }) + ); + // The opener still refuses a type that is not one of the seventeen. + let mut stranger = base(); + let mut foreign = entry(INSTANCE, persona(INSTANCE, T1)); + foreign.r#type = "gamecult.persona_state.v1".into(); + stranger.push(foreign); + assert!(matches!(Mind::open_with(planted(stranger), &yggdrasil).err(), Some(MindRefusal::ForeignStore { .. }))); + } + + /// Status answers in the door's own terms: a stored persona the door + /// cannot read is `Unreadable`, not the `Absent` of a mind with none, while + /// `PersonaGet` answers `Unavailable` for the same bytes. + #[test] + fn status_says_unreadable_where_the_door_says_unavailable() { + let yggdrasil = slug(INSTANCE); + let cache = crate::mind::schema_cache().unwrap(); + let readable = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: persona(INSTANCE, T1) }).unwrap().0; + let no_stamp = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: json!({}) }).unwrap().0; + let mut undecodable = readable.clone(); + undecodable.payload = vec![0xc1]; + // Planted rows have no writing receipt: the door cannot read them, so neither may the status. + for (row, status) in [ + (readable, crate::wire::PersonaStatus::Unreadable), + (no_stamp, crate::wire::PersonaStatus::Unreadable), + (undecodable, crate::wire::PersonaStatus::Unreadable), + ] { + let store = MemoryStore::new(); + store.plant(epoch()); + store.plant(prepare(&instance(INSTANCE))); + store.plant(row); + let mind = Mind::open_with(store, &yggdrasil).unwrap(); + assert_eq!(persona_in_status(&mind), status); + assert!(matches!(mind.persona(), Err(MindRefusal::Unavailable { .. })), "the door answers what the status says"); + } + // A row a put wrote: status and door agree it is stored, with one stamp. + let store = MemoryStore::new(); + let mut written = seeded_over(&store); + committed(put(&mut written, persona(INSTANCE, T1), None)); + assert_eq!(persona_in_status(&written), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); + assert_eq!(written.persona().unwrap().unwrap().updated_at, T1); + assert_eq!(persona_in_status(&seeded_over(&MemoryStore::new())), crate::wire::PersonaStatus::Absent); + } + + #[test] + fn the_stored_bytes_are_the_one_slot_array_the_catalogue_describes() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + let envelope = mind.persona_envelope().unwrap(); + assert_eq!((envelope.r#type.as_str(), envelope.key.as_str()), ("gamecult.persona_state.v0", INSTANCE)); + let slots: (Value,) = rmp_serde::from_slice(&envelope.payload).unwrap(); + assert_eq!(slots.0, persona(INSTANCE, T1)); + } +} diff --git a/crates/huginn-mind/src/wire.rs b/crates/huginn-mind/src/wire.rs index 00cbce0..ba213b3 100644 --- a/crates/huginn-mind/src/wire.rs +++ b/crates/huginn-mind/src/wire.rs @@ -1,343 +1,343 @@ -//! The organ's request and response vocabulary: one operation per `Mind` -//! method and `whoami`. Payloads are the admission and read types unchanged. -//! The daemon carries these in CultNet's operation envelope; the client -//! constructs them. Nothing here validates a document, derives a status or -//! names a transport. - -use cultcache_rs::DatabaseEntry; -use cultnet_rs::{CultMeshCdnArtifactManifest, Selection}; -use eureka_pipeline::{PIPELINE_SCHEMA_EPOCH, PipelineKind, PipelineRef, Slug}; -use schemars::JsonSchema; -use serde::{Deserialize, Serialize}; -use serde_json::Value; - -use crate::admission::{PipelineAdmissionBatch, PipelineAdmissionOutcome}; -use crate::mind::Mind; -use crate::persona::{PersonaPutOutcome, PersonaStateView}; -use crate::query::{PipelineDocumentView, PipelineSelectionPage, SemanticQuery}; -use crate::receipt::{HuginnCommitReceipt, PipelineProvenance}; -use crate::refusal::MindRefusal; -use crate::store::MindStore; - -/// The envelope's `service_id`: one service, one mind, whichever mind the -/// process opened. -pub const MIND_SERVICE_ID: &str = "huginn.mind"; -pub const MIND_REQUEST_SCHEMA: &str = "huginn.mind_request.v1"; -pub const MIND_RESPONSE_SCHEMA: &str = "huginn.mind_response.v1"; - -/// The largest answer that is deferred rather than refused, measured on the -/// encoded payload. The daemon refuses past it and a client caps its fetch at -/// it, so both sides read one number. -pub const MAX_DEFERRED_BODY_BYTES: u64 = 64 * 1024 * 1024; - -/// The published JSON schema of each wire type, as the catalog advertises it. -/// The files are derived from the types below and pinned byte for byte by -/// `published_wire_schemas_match_derivation`, so the catalog cannot advertise -/// a shape the crate does not speak. -pub const MIND_REQUEST_SCHEMA_JSON: &str = - include_str!("../../../schemas/cultnet/huginn.mind_request.v1.schema.json"); -pub const MIND_RESPONSE_SCHEMA_JSON: &str = - include_str!("../../../schemas/cultnet/huginn.mind_response.v1.schema.json"); - -/// The request's `selection` is CultNet's, and its published schema is -/// CultLib's: a `$ref` to the `$id` it publishes, so one owner holds the -/// selection's shape and nothing here copies it. -fn selection_ref(_: &mut schemars::SchemaGenerator) -> schemars::Schema { - schemars::json_schema!({ - "$ref": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.selection.schema.json" - }) -} - -/// The deferred answer's manifest is CultMesh's own type, a positional array -/// the C# reference defines (`CultMeshCdnArtifactManifest`, schema version -/// `gamecult.mesh.cdn_artifact_manifest.v1`). CultLib publishes no JSON schema -/// for it, so the schema says what the reference says: an array of its ten -/// fields in order, and nothing here copies their meaning. -fn manifest_array(_: &mut schemars::SchemaGenerator) -> schemars::Schema { - schemars::json_schema!({ - "description": "gamecult.mesh.cdn_artifact_manifest.v1, the C# reference's CultMeshCdnArtifactManifest as its positional array: [artifactId, kind, version, contentHash, sizeBytes, mimeType, createdAtUtc, chunks[[chunkHash, offset, sizeBytes, recordKey]], tags, metadata].", - "type": "array" - }) -} - -/// Every operation a mind answers. `Admit` carries the batch whole because the -/// batch already names the instance and the asker; a second `instance` beside -/// it would be two declarations. Every read names the instance because ruling -/// 14 refuses another mind's identity whatever the transport, and a read of -/// the wrong mind is that same collision on the read side. `Whoami` names -/// none: it is how a client learns which mind it reached. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum HuginnMindRequest { - Whoami, - Admit(PipelineAdmissionBatch), - View { instance: Slug, id: PipelineRef }, - Query { - instance: Slug, - #[schemars(schema_with = "selection_ref")] - selection: Selection, - semantic: Option, - }, - /// The mind's persona document, if one is stored. - PersonaGet { instance: Slug }, - /// Replaces the mind's persona document whole. `expected_updated_at` is - /// the stored document's `updatedAt`, none for the first put. The - /// provenance is the asker's, as for `Admit`. - PersonaPut { - instance: Slug, - provenance: PipelineProvenance, - state: Value, - expected_updated_at: Option, - }, -} - -impl HuginnMindRequest { - /// The envelope's `operation`. - pub fn operation(&self) -> &'static str { - match self { - Self::Whoami => "whoami", - Self::Admit(_) => "admit", - Self::View { .. } => "view", - Self::Query { .. } => "query", - Self::PersonaGet { .. } => "persona_get", - Self::PersonaPut { .. } => "persona_put", - } - } - - /// The instance the request declares; `Whoami` declares none. - pub fn instance(&self) -> Option<&Slug> { - match self { - Self::Whoami => None, - Self::Admit(batch) => Some(&batch.instance), - Self::View { instance, .. } - | Self::Query { instance, .. } - | Self::PersonaGet { instance } - | Self::PersonaPut { instance, .. } => Some(instance), - } - } -} - -/// Every answer a mind gives. A refusal is data in the response, never a -/// transport failure: the read side carries `Refused`, the write side carries -/// the outcome's own `Refused`. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum HuginnMindResponse { - Whoami(MindStatus), - Admit(PipelineAdmissionOutcome), - View(Option>), - Query(PipelineSelectionPage), - Refused(MindRefusal), - Persona(Option), - PersonaPut(PersonaPutOutcome), - /// The answer did not fit one send and is being held for the client to - /// fetch. Nothing in a mind produces this: the daemon's serve module does, - /// in place of an answer, and the answer it stands for is the named - /// MessagePack of the `HuginnMindResponse` the mind gave. - Deferred(DeferredAnswer), -} - -/// Where the body of an answer that did not fit one send can be fetched: the -/// reference's own manifest, whose `contentHash` is the SHA-256 of the answer's -/// encoded bytes and whose chunks are asked for, one at a time, on the session -/// this arrived on. Row-level facts come from asking again with a header -/// projection; there is no summary. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub struct DeferredAnswer { - #[schemars(schema_with = "manifest_array")] - pub manifest: CultMeshCdnArtifactManifest, -} - -impl HuginnMindResponse { - /// The envelope's `status`, in the C# reference's vocabulary: `rejected` - /// exactly for a refusal, `accepted` otherwise. `Conflict` and - /// `AlreadyAdmitted` are answers about the mind, not refusals of the - /// request. A `Deferred` is nominally `accepted`; the daemon sets the - /// envelope of a deferred answer to the status of the answer it stands for. - pub fn status(&self) -> &'static str { - match self { - Self::Refused(_) - | Self::Admit(PipelineAdmissionOutcome::Refused(_)) - | Self::PersonaPut(PersonaPutOutcome::Refused(_)) => "rejected", - _ => "accepted", - } - } -} - -/// How far the semantic index has caught up with the mind. The mind decides -/// none of it: the daemon's index worker reports it, in memory, and a restart -/// recomputes it. `pending` counts documents not yet known to be in the index. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum IndexStatus { - /// The worker has not yet compared the mind with the collection. - Reconciling { pending: u32 }, - /// Every indexable document is in the collection. - Current, - /// Reconciled, and indexing what is still pending. - Behind { pending: u32 }, - /// The last attempt failed (the embedder or the vector store is - /// unreachable, or refused); it is retried with a backoff and nothing is - /// dropped. `attempts` counts consecutive failures. - Failing { pending: u32, attempts: u32, error: String }, - /// The collection belongs to another writer. The worker never recreates - /// it; it re-reads it on the same backoff. - Refused { pending: u32, attempts: u32, reason: String }, -} - -/// What a mind says about itself: the typed state a dashboard projects. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub struct MindStatus { - pub instance: Slug, - pub schema_epoch: String, - /// Pipeline documents in the image; the epoch record and the receipts are - /// not documents and are not counted here. - pub documents: u32, - pub receipts: u32, - pub index: IndexStatus, - /// The persona door as `PersonaGet` would find it. - pub persona: PersonaStatus, -} - -/// What the persona door holds, in the one vocabulary the door itself answers -/// in: nothing yet, a document with this `updatedAt`, or a stored document the -/// door cannot read (`PersonaGet` and every put answer `Unavailable`). -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum PersonaStatus { - Absent, - Stored { updated_at: String }, - Unreadable, -} - -impl Mind { - /// `whoami`, derived from the image every time it is asked, and from the - /// index status the caller holds: the mind stores neither. - pub fn status(&self, index: IndexStatus) -> MindStatus { - let mut documents = 0_u32; - let mut receipts = 0_u32; - for envelope in self.envelopes() { - if envelope.r#type == HuginnCommitReceipt::TYPE { - receipts += 1; - } else if PipelineKind::ALL.iter().any(|kind| kind.type_id() == envelope.r#type) { - documents += 1; - } - } - MindStatus { - instance: self.instance().clone(), - schema_epoch: PIPELINE_SCHEMA_EPOCH.to_string(), - documents, - receipts, - index, - persona: match self.stored_updated_at() { - Ok(None) => PersonaStatus::Absent, - Ok(Some(updated_at)) => PersonaStatus::Stored { updated_at }, - Err(_) => PersonaStatus::Unreadable, - }, - } - } -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::query::PipelinePageItems; - use crate::fixtures::{CAMPAIGN, INSTANCE, OTHER_INSTANCE, instance, provenance, r, seeded, slug}; - use crate::receipt::Faculty; - - fn requests() -> Vec { - let batch = PipelineAdmissionBatch { - instance: slug(INSTANCE), - provenance: provenance(Faculty::Hands), - documents: vec![instance(INSTANCE)], - }; - vec![ - HuginnMindRequest::Whoami, - HuginnMindRequest::Admit(batch), - HuginnMindRequest::View { instance: slug(INSTANCE), id: r(PipelineKind::Campaign, CAMPAIGN) }, - HuginnMindRequest::Query { instance: slug(OTHER_INSTANCE), selection: Selection::default(), semantic: None }, - HuginnMindRequest::PersonaGet { instance: slug(INSTANCE) }, - HuginnMindRequest::PersonaPut { - instance: slug(INSTANCE), - provenance: provenance(Faculty::Hands), - state: serde_json::json!({ "updatedAt": "2026-10-10T10:00:00Z", "n": [1, 2.5, null, "x"] }), - expected_updated_at: Some("2026-10-10T09:00:00Z".into()), - }, - ] - } - - fn responses() -> Vec { - let refusal = MindRefusal::ForeignInstance { declared: OTHER_INSTANCE.into(), mind: INSTANCE.into() }; - vec![ - HuginnMindResponse::Whoami(seeded().status(IndexStatus::Current)), - HuginnMindResponse::Admit(PipelineAdmissionOutcome::AlreadyAdmitted { receipt_id: "r1".into() }), - HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { identities: vec![] }), - HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(refusal.clone())), - HuginnMindResponse::View(None), - HuginnMindResponse::Query(PipelineSelectionPage { - matched: 0, - as_of: 1, - next: None, - items: PipelinePageItems::Headers(vec![]), - edges: None, - }), - HuginnMindResponse::Refused(refusal), - HuginnMindResponse::Persona(None), - HuginnMindResponse::Persona(Some(PersonaStateView { - value: serde_json::json!({ "personaId": INSTANCE }), - updated_at: "2026-10-10T10:00:00Z".into(), - receipt_id: "mind-commit-1".into(), - })), - HuginnMindResponse::PersonaPut(PersonaPutOutcome::Committed { receipt_id: "mind-commit-2".into() }), - HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(MindRefusal::PersonaNotCanonical)), - HuginnMindResponse::Deferred(DeferredAnswer { - manifest: cultnet_rs::pack_content("huginn.mind_response", "package", "", "", "", b"body", 4) - .unwrap() - .0, - }), - ] - } - - /// The vocabulary is the mind's methods, the declared instance is on every - /// request that names a mind, and the envelope's status is derived from - /// the response rather than chosen by whoever sends it. - #[test] - fn the_wire_vocabulary_is_the_minds_methods_and_status_is_derived_from_the_response() { - let names: Vec<&str> = requests().iter().map(|request| request.operation()).collect(); - assert_eq!(names, ["whoami", "admit", "view", "query", "persona_get", "persona_put"]); - for request in requests() { - let declared = request.instance().is_none(); - assert_eq!(declared, matches!(request, HuginnMindRequest::Whoami), "{request:?}"); - let bytes = rmp_serde::to_vec_named(&request).unwrap(); - assert_eq!(rmp_serde::from_slice::(&bytes).unwrap(), request); - } - assert_eq!( - requests()[3].instance(), - Some(&slug(OTHER_INSTANCE)), - "the request's instance is the one it declares, not the mind's" - ); - - for response in responses() { - let rejected = matches!( - response, - HuginnMindResponse::Refused(_) - | HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(_)) - | HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(_)) - ); - assert_eq!(response.status(), if rejected { "rejected" } else { "accepted" }, "{response:?}"); - let bytes = rmp_serde::to_vec_named(&response).unwrap(); - assert_eq!(rmp_serde::from_slice::(&bytes).unwrap(), response); - } - } - - /// The two files the catalog publishes are the derivation of the two - /// types, byte for byte. - #[test] - fn published_wire_schemas_match_derivation() { - let request = serde_json::to_string_pretty(&schemars::schema_for!(HuginnMindRequest)).unwrap(); - let response = serde_json::to_string_pretty(&schemars::schema_for!(HuginnMindResponse)).unwrap(); - assert_eq!(MIND_REQUEST_SCHEMA_JSON.replace("\r\n", "\n"), request); - assert_eq!(MIND_RESPONSE_SCHEMA_JSON.replace("\r\n", "\n"), response); - // The selection is CultLib's, referenced by the `$id` it publishes and - // not copied into this schema. - let selection = "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.selection.schema.json"; - assert!(request.contains(&format!("\"$ref\": \"{selection}\""))); - assert!(!request.contains("\"cursor\""), "no second copy of the selection's shape"); - } -} +//! The organ's request and response vocabulary: one operation per `Mind` +//! method and `whoami`. Payloads are the admission and read types unchanged. +//! The daemon carries these in CultNet's operation envelope; the client +//! constructs them. Nothing here validates a document, derives a status or +//! names a transport. + +use cultcache_rs::DatabaseEntry; +use cultnet_rs::{CultMeshCdnArtifactManifest, Selection}; +use eureka_pipeline::{PIPELINE_SCHEMA_EPOCH, PipelineKind, PipelineRef, Slug}; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use crate::admission::{PipelineAdmissionBatch, PipelineAdmissionOutcome}; +use crate::mind::Mind; +use crate::persona::{PersonaPutOutcome, PersonaStateView}; +use crate::query::{PipelineDocumentView, PipelineSelectionPage, SemanticQuery}; +use crate::receipt::{HuginnCommitReceipt, PipelineProvenance}; +use crate::refusal::MindRefusal; +use crate::store::MindStore; + +/// The envelope's `service_id`: one service, one mind, whichever mind the +/// process opened. +pub const MIND_SERVICE_ID: &str = "huginn.mind"; +pub const MIND_REQUEST_SCHEMA: &str = "huginn.mind_request.v1"; +pub const MIND_RESPONSE_SCHEMA: &str = "huginn.mind_response.v1"; + +/// The largest answer that is deferred rather than refused, measured on the +/// encoded payload. The daemon refuses past it and a client caps its fetch at +/// it, so both sides read one number. +pub const MAX_DEFERRED_BODY_BYTES: u64 = 64 * 1024 * 1024; + +/// The published JSON schema of each wire type, as the catalog advertises it. +/// The files are derived from the types below and pinned byte for byte by +/// `published_wire_schemas_match_derivation`, so the catalog cannot advertise +/// a shape the crate does not speak. +pub const MIND_REQUEST_SCHEMA_JSON: &str = + include_str!("../../../schemas/cultnet/huginn.mind_request.v1.schema.json"); +pub const MIND_RESPONSE_SCHEMA_JSON: &str = + include_str!("../../../schemas/cultnet/huginn.mind_response.v1.schema.json"); + +/// The request's `selection` is CultNet's, and its published schema is +/// CultLib's: a `$ref` to the `$id` it publishes, so one owner holds the +/// selection's shape and nothing here copies it. +fn selection_ref(_: &mut schemars::SchemaGenerator) -> schemars::Schema { + schemars::json_schema!({ + "$ref": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.selection.schema.json" + }) +} + +/// The deferred answer's manifest is CultMesh's own type, a positional array +/// the C# reference defines (`CultMeshCdnArtifactManifest`, schema version +/// `gamecult.mesh.cdn_artifact_manifest.v1`). CultLib publishes no JSON schema +/// for it, so the schema says what the reference says: an array of its ten +/// fields in order, and nothing here copies their meaning. +fn manifest_array(_: &mut schemars::SchemaGenerator) -> schemars::Schema { + schemars::json_schema!({ + "description": "gamecult.mesh.cdn_artifact_manifest.v1, the C# reference's CultMeshCdnArtifactManifest as its positional array: [artifactId, kind, version, contentHash, sizeBytes, mimeType, createdAtUtc, chunks[[chunkHash, offset, sizeBytes, recordKey]], tags, metadata].", + "type": "array" + }) +} + +/// Every operation a mind answers. `Admit` carries the batch whole because the +/// batch already names the instance and the asker; a second `instance` beside +/// it would be two declarations. Every read names the instance because ruling +/// 14 refuses another mind's identity whatever the transport, and a read of +/// the wrong mind is that same collision on the read side. `Whoami` names +/// none: it is how a client learns which mind it reached. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum HuginnMindRequest { + Whoami, + Admit(PipelineAdmissionBatch), + View { instance: Slug, id: PipelineRef }, + Query { + instance: Slug, + #[schemars(schema_with = "selection_ref")] + selection: Selection, + semantic: Option, + }, + /// The mind's persona document, if one is stored. + PersonaGet { instance: Slug }, + /// Replaces the mind's persona document whole. `expected_updated_at` is + /// the stored document's `updatedAt`, none for the first put. The + /// provenance is the asker's, as for `Admit`. + PersonaPut { + instance: Slug, + provenance: PipelineProvenance, + state: Value, + expected_updated_at: Option, + }, +} + +impl HuginnMindRequest { + /// The envelope's `operation`. + pub fn operation(&self) -> &'static str { + match self { + Self::Whoami => "whoami", + Self::Admit(_) => "admit", + Self::View { .. } => "view", + Self::Query { .. } => "query", + Self::PersonaGet { .. } => "persona_get", + Self::PersonaPut { .. } => "persona_put", + } + } + + /// The instance the request declares; `Whoami` declares none. + pub fn instance(&self) -> Option<&Slug> { + match self { + Self::Whoami => None, + Self::Admit(batch) => Some(&batch.instance), + Self::View { instance, .. } + | Self::Query { instance, .. } + | Self::PersonaGet { instance } + | Self::PersonaPut { instance, .. } => Some(instance), + } + } +} + +/// Every answer a mind gives. A refusal is data in the response, never a +/// transport failure: the read side carries `Refused`, the write side carries +/// the outcome's own `Refused`. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum HuginnMindResponse { + Whoami(MindStatus), + Admit(PipelineAdmissionOutcome), + View(Option>), + Query(PipelineSelectionPage), + Refused(MindRefusal), + Persona(Option), + PersonaPut(PersonaPutOutcome), + /// The answer did not fit one send and is being held for the client to + /// fetch. Nothing in a mind produces this: the daemon's serve module does, + /// in place of an answer, and the answer it stands for is the named + /// MessagePack of the `HuginnMindResponse` the mind gave. + Deferred(DeferredAnswer), +} + +/// Where the body of an answer that did not fit one send can be fetched: the +/// reference's own manifest, whose `contentHash` is the SHA-256 of the answer's +/// encoded bytes and whose chunks are asked for, one at a time, on the session +/// this arrived on. Row-level facts come from asking again with a header +/// projection; there is no summary. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub struct DeferredAnswer { + #[schemars(schema_with = "manifest_array")] + pub manifest: CultMeshCdnArtifactManifest, +} + +impl HuginnMindResponse { + /// The envelope's `status`, in the C# reference's vocabulary: `rejected` + /// exactly for a refusal, `accepted` otherwise. `Conflict` and + /// `AlreadyAdmitted` are answers about the mind, not refusals of the + /// request. A `Deferred` is nominally `accepted`; the daemon sets the + /// envelope of a deferred answer to the status of the answer it stands for. + pub fn status(&self) -> &'static str { + match self { + Self::Refused(_) + | Self::Admit(PipelineAdmissionOutcome::Refused(_)) + | Self::PersonaPut(PersonaPutOutcome::Refused(_)) => "rejected", + _ => "accepted", + } + } +} + +/// How far the semantic index has caught up with the mind. The mind decides +/// none of it: the daemon's index worker reports it, in memory, and a restart +/// recomputes it. `pending` counts documents not yet known to be in the index. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum IndexStatus { + /// The worker has not yet compared the mind with the collection. + Reconciling { pending: u32 }, + /// Every indexable document is in the collection. + Current, + /// Reconciled, and indexing what is still pending. + Behind { pending: u32 }, + /// The last attempt failed (the embedder or the vector store is + /// unreachable, or refused); it is retried with a backoff and nothing is + /// dropped. `attempts` counts consecutive failures. + Failing { pending: u32, attempts: u32, error: String }, + /// The collection belongs to another writer. The worker never recreates + /// it; it re-reads it on the same backoff. + Refused { pending: u32, attempts: u32, reason: String }, +} + +/// What a mind says about itself: the typed state a dashboard projects. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub struct MindStatus { + pub instance: Slug, + pub schema_epoch: String, + /// Pipeline documents in the image; the epoch record and the receipts are + /// not documents and are not counted here. + pub documents: u32, + pub receipts: u32, + pub index: IndexStatus, + /// The persona door as `PersonaGet` would find it. + pub persona: PersonaStatus, +} + +/// What the persona door holds, in the one vocabulary the door itself answers +/// in: nothing yet, a document with this `updatedAt`, or a stored document the +/// door cannot read (`PersonaGet` and every put answer `Unavailable`). +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum PersonaStatus { + Absent, + Stored { updated_at: String }, + Unreadable, +} + +impl Mind { + /// `whoami`, derived from the image every time it is asked, and from the + /// index status the caller holds: the mind stores neither. + pub fn status(&self, index: IndexStatus) -> MindStatus { + let mut documents = 0_u32; + let mut receipts = 0_u32; + for envelope in self.envelopes() { + if envelope.r#type == HuginnCommitReceipt::TYPE { + receipts += 1; + } else if PipelineKind::ALL.iter().any(|kind| kind.type_id() == envelope.r#type) { + documents += 1; + } + } + MindStatus { + instance: self.instance().clone(), + schema_epoch: PIPELINE_SCHEMA_EPOCH.to_string(), + documents, + receipts, + index, + persona: match self.persona() { + Ok(None) => PersonaStatus::Absent, + Ok(Some(view)) => PersonaStatus::Stored { updated_at: view.updated_at }, + Err(_) => PersonaStatus::Unreadable, + }, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::query::PipelinePageItems; + use crate::fixtures::{CAMPAIGN, INSTANCE, OTHER_INSTANCE, instance, provenance, r, seeded, slug}; + use crate::receipt::Faculty; + + fn requests() -> Vec { + let batch = PipelineAdmissionBatch { + instance: slug(INSTANCE), + provenance: provenance(Faculty::Hands), + documents: vec![instance(INSTANCE)], + }; + vec![ + HuginnMindRequest::Whoami, + HuginnMindRequest::Admit(batch), + HuginnMindRequest::View { instance: slug(INSTANCE), id: r(PipelineKind::Campaign, CAMPAIGN) }, + HuginnMindRequest::Query { instance: slug(OTHER_INSTANCE), selection: Selection::default(), semantic: None }, + HuginnMindRequest::PersonaGet { instance: slug(INSTANCE) }, + HuginnMindRequest::PersonaPut { + instance: slug(INSTANCE), + provenance: provenance(Faculty::Hands), + state: serde_json::json!({ "updatedAt": "2026-10-10T10:00:00Z", "n": [1, 2.5, null, "x"] }), + expected_updated_at: Some("2026-10-10T09:00:00Z".into()), + }, + ] + } + + fn responses() -> Vec { + let refusal = MindRefusal::ForeignInstance { declared: OTHER_INSTANCE.into(), mind: INSTANCE.into() }; + vec![ + HuginnMindResponse::Whoami(seeded().status(IndexStatus::Current)), + HuginnMindResponse::Admit(PipelineAdmissionOutcome::AlreadyAdmitted { receipt_id: "r1".into() }), + HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { identities: vec![] }), + HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(refusal.clone())), + HuginnMindResponse::View(None), + HuginnMindResponse::Query(PipelineSelectionPage { + matched: 0, + as_of: 1, + next: None, + items: PipelinePageItems::Headers(vec![]), + edges: None, + }), + HuginnMindResponse::Refused(refusal), + HuginnMindResponse::Persona(None), + HuginnMindResponse::Persona(Some(PersonaStateView { + value: serde_json::json!({ "personaId": INSTANCE }), + updated_at: "2026-10-10T10:00:00Z".into(), + receipt_id: "mind-commit-1".into(), + })), + HuginnMindResponse::PersonaPut(PersonaPutOutcome::Committed { receipt_id: "mind-commit-2".into() }), + HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(MindRefusal::PersonaNotCanonical)), + HuginnMindResponse::Deferred(DeferredAnswer { + manifest: cultnet_rs::pack_content("huginn.mind_response", "package", "", "", "", b"body", 4) + .unwrap() + .0, + }), + ] + } + + /// The vocabulary is the mind's methods, the declared instance is on every + /// request that names a mind, and the envelope's status is derived from + /// the response rather than chosen by whoever sends it. + #[test] + fn the_wire_vocabulary_is_the_minds_methods_and_status_is_derived_from_the_response() { + let names: Vec<&str> = requests().iter().map(|request| request.operation()).collect(); + assert_eq!(names, ["whoami", "admit", "view", "query", "persona_get", "persona_put"]); + for request in requests() { + let declared = request.instance().is_none(); + assert_eq!(declared, matches!(request, HuginnMindRequest::Whoami), "{request:?}"); + let bytes = rmp_serde::to_vec_named(&request).unwrap(); + assert_eq!(rmp_serde::from_slice::(&bytes).unwrap(), request); + } + assert_eq!( + requests()[3].instance(), + Some(&slug(OTHER_INSTANCE)), + "the request's instance is the one it declares, not the mind's" + ); + + for response in responses() { + let rejected = matches!( + response, + HuginnMindResponse::Refused(_) + | HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(_)) + | HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(_)) + ); + assert_eq!(response.status(), if rejected { "rejected" } else { "accepted" }, "{response:?}"); + let bytes = rmp_serde::to_vec_named(&response).unwrap(); + assert_eq!(rmp_serde::from_slice::(&bytes).unwrap(), response); + } + } + + /// The two files the catalog publishes are the derivation of the two + /// types, byte for byte. + #[test] + fn published_wire_schemas_match_derivation() { + let request = serde_json::to_string_pretty(&schemars::schema_for!(HuginnMindRequest)).unwrap(); + let response = serde_json::to_string_pretty(&schemars::schema_for!(HuginnMindResponse)).unwrap(); + assert_eq!(MIND_REQUEST_SCHEMA_JSON.replace("\r\n", "\n"), request); + assert_eq!(MIND_RESPONSE_SCHEMA_JSON.replace("\r\n", "\n"), response); + // The selection is CultLib's, referenced by the `$id` it publishes and + // not copied into this schema. + let selection = "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.selection.schema.json"; + assert!(request.contains(&format!("\"$ref\": \"{selection}\""))); + assert!(!request.contains("\"cursor\""), "no second copy of the selection's shape"); + } +} From 27e8d5875757d095d7234aa81e5cabc5020bbdbe Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 10:15:44 +0200 Subject: [PATCH 09/11] huginn CLI whoami prints the persona door state One bounded line: absent, stored updatedAt=, or unreadable; no value of the document. Test over canned Whoami answers. Co-Authored-By: Claude Opus 5.5 --- crates/eureka-state/src/bin/huginn/main.rs | 1 + crates/eureka-state/src/bin/huginn/render.rs | 12 +- crates/eureka-state/tests/cli.rs | 2079 +++++++++--------- 3 files changed, 1059 insertions(+), 1033 deletions(-) diff --git a/crates/eureka-state/src/bin/huginn/main.rs b/crates/eureka-state/src/bin/huginn/main.rs index f2bb165..f3f8f0e 100644 --- a/crates/eureka-state/src/bin/huginn/main.rs +++ b/crates/eureka-state/src/bin/huginn/main.rs @@ -195,6 +195,7 @@ fn whoami(settings: &Settings) -> Result { render::index_state(&status.index), status.schema_epoch )); + say(format_args!("persona {}", render::persona_state(&status.persona))); Ok(0) } Ok(other) => { diff --git a/crates/eureka-state/src/bin/huginn/render.rs b/crates/eureka-state/src/bin/huginn/render.rs index 83b37b0..dfef1ec 100644 --- a/crates/eureka-state/src/bin/huginn/render.rs +++ b/crates/eureka-state/src/bin/huginn/render.rs @@ -2,7 +2,7 @@ use std::fmt::Write; -use huginn_mind::{IndexStatus, PipelineDocumentSummary, PipelineDocumentView, PipelineStatus, PipelineStatusSummary}; +use huginn_mind::{IndexStatus, PersonaStatus, PipelineDocumentSummary, PipelineDocumentView, PipelineStatus, PipelineStatusSummary}; use serde::Serialize; use serde_json::Value; @@ -19,6 +19,16 @@ pub fn name_of(value: &T) -> String { } } +/// The persona door's state as one line: no value of the document, only the +/// vocabulary the door answers in. +pub fn persona_state(persona: &PersonaStatus) -> String { + match persona { + PersonaStatus::Absent => "absent".into(), + PersonaStatus::Stored { updated_at } => format!("stored updatedAt={updated_at}"), + PersonaStatus::Unreadable => "unreadable".into(), + } +} + /// An index status as one token and its numbers: `Behind pending=3`. pub fn index_state(index: &IndexStatus) -> String { let mut text = name_of(index); diff --git a/crates/eureka-state/tests/cli.rs b/crates/eureka-state/tests/cli.rs index 898bee0..24385dc 100644 --- a/crates/eureka-state/tests/cli.rs +++ b/crates/eureka-state/tests/cli.rs @@ -1,1032 +1,1047 @@ -//! The `huginn` binary as an agent drives it: a real process, its stdout, its -//! stderr and its exit code, against a real daemon in-process or a scripted -//! server where the daemon cannot be made to misbehave. - -use std::io::Write; -use std::net::{SocketAddr, UdpSocket}; -use std::path::Path; -use std::process::{Command, Stdio}; -use std::sync::{Arc, Mutex}; - -use cultnet_rs::Selection; -use huginn_mind::envelope::{OperationFailure, decode_request, encode_failure, encode_response}; -use huginn_mind::eureka_pipeline::{ - CodeLocation, CommitRange, CutVerification, Date, Evidence, EvidenceKind, MutationRecord, OrgRepo, PipelineCutReport, - PipelineCutSpec, PipelineDocument, PipelineKind, PipelineRef, PipelineRuling, Promise, ReportCommit, RulingAuthority, Short, - StructuralDelta, pipeline_key, -}; -use huginn_mind::{ - AdmissionFacts, HuginnMindRequest, HuginnMindResponse, IndexStatus, MindRefusal, MindStatus, PersonaStatus, PipelineAdmissionOutcome, PipelineDocumentView, - PipelinePageItems, PipelineProvenance, PipelineSelectionPage, PipelineStatus, -}; -use serde_json::{Value, json}; -use tempfile::TempDir; - -mod common; -use common::*; - -struct Run { - code: i32, - out: String, - err: String, -} - -fn run(env: &[(&str, &str)], args: &[&str], stdin: Option<&str>) -> Run { - let mut command = Command::new(env!("CARGO_BIN_EXE_huginn")); - command - .env_remove("EUREKA_INSTANCE") - .env_remove("HUGINN_ENDPOINT") - .envs(env.iter().copied()) - .args(args) - .stdin(if stdin.is_some() { Stdio::piped() } else { Stdio::null() }) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()); - let mut child = command.spawn().expect("the binary starts"); - if let Some(text) = stdin { - child.stdin.take().unwrap().write_all(text.as_bytes()).unwrap(); - } - let output = child.wait_with_output().unwrap(); - Run { - code: output.status.code().expect("exited, not killed"), - out: String::from_utf8(output.stdout).unwrap(), - err: String::from_utf8(output.stderr).unwrap(), - } -} - -/// Configured for the test instance against a daemon at `addr`. -fn at(addr: SocketAddr, args: &[&str], stdin: Option<&str>) -> Run { - run(&[("EUREKA_INSTANCE", INSTANCE), ("HUGINN_ENDPOINT", &format!("rudp://{addr}"))], args, stdin) -} - -/// A loopback UDP port nothing listens on. -fn closed_port() -> SocketAddr { - UdpSocket::bind("127.0.0.1:0").unwrap().local_addr().unwrap() -} - -fn write(dir: &TempDir, name: &str, value: &Value) -> String { - let path = dir.path().join(name); - std::fs::write(&path, value.to_string()).unwrap(); - path.to_str().unwrap().to_string() -} - -fn campaign_json() -> Value { - serde_json::to_value(campaign()).unwrap() -} - -fn live() -> Server { - let (root, daemon) = mind(vec![vec![stewardship()]]); - serve(root, daemon) -} - -fn admit_args(file: &str) -> Vec<&str> { - vec!["admit", "--faculty", "Hands", "--agent", "claude", "--session", "session-7", file] -} - -fn delta() -> StructuralDelta { - StructuralDelta { - lines_added: 0, - lines_removed: 0, - dependencies_added: vec![], - dependencies_removed: vec![], - formats_added: vec![], - formats_removed: vec![], - targets_added: vec![], - targets_removed: vec![], - } -} - -fn spec(cut: &str) -> Value { - serde_json::to_value(PipelineDocument::CutSpec(PipelineCutSpec { - campaign: slug(CAMPAIGN), - cut: cut.into(), - revision: 1, - title: "A cut".into(), - repo: OrgRepo(REPO.into()), - branch: "codex/eureka-pipeline-state".into(), - base: sha(), - depends_on: vec![], - first: vec![], - deletes: vec![], - keeps_moves: vec![], - adds: vec![], - file_changes: vec![], - reads: vec![], - authority_map: None, - verification: CutVerification { builds: vec![], tests: vec![], negative: vec![], operator: vec![] }, - estimate: delta(), - rulings: vec![], - questions: vec![], - })) - .unwrap() -} - -fn report(cut: &str) -> Value { - serde_json::to_value(PipelineDocument::CutReport(PipelineCutReport { - campaign: slug(CAMPAIGN), - cut_spec: Short(format!("{CAMPAIGN}:cut_spec:cut-{cut}.r1")), - attempt: 1, - repo: OrgRepo(REPO.into()), - branch: "codex/eureka-pipeline-state".into(), - commits: vec![ReportCommit { sha: sha(), subject: "Land the cut".into(), builds: true }], - range: CommitRange { base: sha(), head: sha() }, - verification: vec![Evidence { kind: EvidenceKind::Test, locator: "cargo test".into(), result: "ok".into() }], - mutations: vec![MutationRecord { - label: "M1".into(), - rule: "the rule".into(), - location: CodeLocation { path: Short("crates/x.rs".into()), line: 1, end_line: None, symbol: None }, - before: "before".into(), - after: "after".into(), - commit: sha(), - failed_as_expected: true, - }], - deviations: vec![], - forks: vec![], - structural_delta: delta(), - landed_names: vec![], - undone: vec![], - promises: vec![Promise { label: "P1".into(), text: "One derived key per document.".into() }], - })) - .unwrap() -} - -fn ruling(quote: Option<&str>) -> PipelineDocument { - PipelineDocument::Ruling(PipelineRuling { - campaign: slug(CAMPAIGN), - label: "R1".into(), - title: "An instance owns its mind".into(), - answers: None, - choice: None, - ruling: "An instance owns its mind.".into(), - operator_quote: quote.map(Into::into), - ruled_on: Date("2026-10-10".into()), - precedents: vec![], - authority: RulingAuthority::Standing, - }) -} - -fn empty_page() -> PipelineSelectionPage { - PipelineSelectionPage { matched: 0, as_of: 1, next: None, items: PipelinePageItems::Headers(vec![]), edges: None } -} - -fn answer(operation: &str, response: &HuginnMindResponse) -> cultnet_rs::CultNetMessage { - encode_response("eureka-state-call", operation, response, "scripted").unwrap() -} - -/// A scripted server that records every request it is sent and answers a -/// query with an empty page. -fn recording() -> (Server, Arc>>) { - let seen = Arc::new(Mutex::new(Vec::new())); - let sink = Arc::clone(&seen); - let server = scripted(move |message| { - let (_, request) = decode_request(message).expect("a mind request"); - sink.lock().unwrap().push(request); - answer("query", &HuginnMindResponse::Query(empty_page())) - }); - (server, seen) -} - -/// The selection a command sent, and its semantic part. -fn sent(args: &[&str]) -> (Selection, Option<(String, u32)>) { - let (server, seen) = recording(); - let ran = at(server.addr, args, None); - assert_eq!(ran.code, 0, "{args:?}: {}", ran.err); - assert!(ran.out.contains("matched 0 as_of 1 next -"), "{}", ran.out); - let seen = seen.lock().unwrap(); - let [HuginnMindRequest::Query { instance, selection, semantic }] = &seen[..] else { - panic!("one query expected: {seen:?}"); - }; - assert_eq!(instance.0, INSTANCE); - (selection.clone(), semantic.as_ref().map(|asked| (asked.text.0.clone(), asked.top_k))) -} - -/// The page's literal as the selection it spells, with the CLI's default page. -fn page_literal(literal: Value) -> Selection { - let mut selection: Selection = serde_json::from_value(literal).unwrap(); - selection.limit = Some(50); - selection -} - -fn counting(replies: HuginnMindResponse, operation: &'static str) -> (Server, Arc>) { - let count = Arc::new(Mutex::new(0)); - let counter = Arc::clone(&count); - let server = scripted(move |_| { - *counter.lock().unwrap() += 1; - answer(operation, &replies) - }); - (server, count) -} - -#[test] -fn without_configuration_whoami_reports_it_and_every_other_command_refuses() { - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "campaign.json", &json!([campaign_json()])); - - let whoami = run(&[], &["whoami"], None); - assert_eq!(whoami.code, 2); - assert!(whoami.out.contains("instance unset\nendpoint unset\nclient "), "{}", whoami.out); - assert!(whoami.out.contains("reachable no"), "{}", whoami.out); - assert!(whoami.err.starts_with("Misconfigured: EUREKA_INSTANCE is not set"), "{}", whoami.err); - - for args in [ - vec!["view", "eureka-state:campaign:self"], - vec!["query", "{}"], - vec!["rulings", "eureka-state"], - admit_args(&file), - ] { - let ran = run(&[], &args, None); - assert_eq!(ran.code, 2, "{args:?}"); - assert!(ran.err.starts_with("Misconfigured:"), "{args:?}: {}", ran.err); - assert_eq!(ran.out, "", "{args:?}"); - } -} - -#[test] -fn a_bad_environment_is_misconfigured_with_its_own_reason() { - let cases: [(&[(&str, &str)], &str); 4] = [ - (&[("HUGINN_ENDPOINT", "rudp://127.0.0.1:1")], "EUREKA_INSTANCE is not set"), - (&[("EUREKA_INSTANCE", "Not A Slug"), ("HUGINN_ENDPOINT", "rudp://127.0.0.1:1")], "EUREKA_INSTANCE is not a valid"), - (&[("EUREKA_INSTANCE", "eureka")], "HUGINN_ENDPOINT is not set"), - (&[("EUREKA_INSTANCE", "eureka"), ("HUGINN_ENDPOINT", "127.0.0.1:1")], "HUGINN_ENDPOINT is not rudp://"), - ]; - for (env, expected) in cases { - let ran = run(env, &["whoami"], None); - assert_eq!(ran.code, 2, "{expected}"); - assert!(ran.err.starts_with("Misconfigured: "), "{}", ran.err); - assert!(ran.err.contains(expected), "{expected}: {}", ran.err); - } - let named = run(&[("EUREKA_INSTANCE", "eureka"), ("HUGINN_ENDPOINT", "rudp://not-an-address")], &["whoami"], None); - assert_eq!(named.code, 2); - assert!(named.out.contains("endpoint rudp://not-an-address"), "{}", named.out); - assert!(named.out.contains("instance eureka"), "{}", named.out); -} - -#[test] -fn whoami_reads_the_live_mind() { - let server = live(); - let ran = at(server.addr, &["whoami"], None); - assert_eq!(ran.code, 0, "{}", ran.err); - let lines: Vec<&str> = ran.out.lines().collect(); - assert_eq!(lines[0], format!("instance {INSTANCE}")); - assert_eq!(lines[1], format!("endpoint rudp://{}", server.addr)); - assert_eq!(lines[2], format!("client {}", option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown"))); - assert_eq!(lines[3], "reachable yes"); - assert_eq!(lines[4], "documents 2 receipts 2 index Current epoch epiphany.pipeline.epoch.v2"); - assert_eq!(lines.len(), 5); - assert_eq!(ran.err, ""); -} - -#[test] -fn an_index_that_is_behind_shows_its_count() { - let status = MindStatus { - instance: slug(INSTANCE), - schema_epoch: "epoch".into(), - documents: 7, - receipts: 9, - index: IndexStatus::Behind { pending: 3 }, - persona: PersonaStatus::Absent, - }; - let (server, _) = counting(HuginnMindResponse::Whoami(status), "whoami"); - let ran = at(server.addr, &["whoami"], None); - assert_eq!(ran.code, 0); - assert!(ran.out.contains("documents 7 receipts 9 index Behind pending=3 epoch epoch"), "{}", ran.out); -} - -#[test] -fn admit_round_trips_and_is_idempotent() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "campaign.json", &json!([campaign_json()])); - - let first = at(server.addr, &admit_args(&file), None); - assert_eq!(first.code, 0, "{}", first.err); - let lines: Vec<&str> = first.out.lines().collect(); - assert!(lines[0].starts_with("Committed mind-commit-"), "{}", first.out); - assert!(lines[0].contains(" at "), "{}", first.out); - assert_eq!(lines[1], format!("wrote {CAMPAIGN}:campaign:self")); - assert_eq!(lines[2], "read back 1 equal"); - assert_eq!(lines.len(), 3, "{}", first.out); - - let again = at(server.addr, &admit_args(&file), None); - assert_eq!(again.code, 0, "{}", again.err); - let lines: Vec<&str> = again.out.lines().collect(); - assert!(lines[0].starts_with("AlreadyAdmitted mind-commit-"), "{}", again.out); - assert_eq!(lines[1], "read back 1 equal"); - - let id = format!("{CAMPAIGN}:campaign:self"); - let viewed = at(server.addr, &["view", &id], None); - assert_eq!(viewed.code, 0, "{}", viewed.err); - let lines: Vec<&str> = viewed.out.lines().collect(); - assert_eq!(lines[0], format!("{id} InForce")); - assert!(lines[1].starts_with("admitted "), "{}", viewed.out); - assert!(lines[1].contains(" ordinal 3 Hands/claude session session-7 tool huginn receipt mind-commit-"), "{}", lines[1]); - let shown: Value = serde_json::from_str(&lines[2..].join("\n")).unwrap(); - assert_eq!(shown, campaign_json()); - - let raw = at(server.addr, &["view", &id, "--raw"], None); - assert_eq!(raw.code, 0); - assert_eq!(serde_json::from_str::(&raw.out).unwrap(), campaign_json()); - assert!(raw.out.starts_with('{'), "{}", raw.out); - - let fed_back = at(server.addr, &admit_args("-"), Some(&raw.out)); - assert_eq!(fed_back.code, 0, "{}", fed_back.err); - assert!(fed_back.out.starts_with("AlreadyAdmitted "), "{}", fed_back.out); - - let status = at(server.addr, &["whoami"], None); - assert!(status.out.contains("documents 3 receipts 3"), "{}", status.out); -} - -#[test] -fn unknown_keys_are_refused_by_path_and_never_by_value() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let mut nested = campaign_json(); - nested["value"]["target_doc"]["pathh"] = json!("CANARY-NESTED"); - let mut top = campaign_json(); - top["surplus"] = json!("CANARY-TOP"); - let file = write(&dir, "bad.json", &json!([nested, top])); - - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 2); - assert_eq!(ran.out, ""); - assert!(ran.err.starts_with("InvalidInput: "), "{}", ran.err); - assert!(ran.err.contains("documents[0].value.target_doc.pathh"), "{}", ran.err); - assert!(ran.err.contains("documents[1].surplus"), "{}", ran.err); - assert!(!ran.err.contains("CANARY"), "{}", ran.err); - - let status = at(server.addr, &["whoami"], None); - assert!(status.out.contains("receipts 2 "), "nothing was sent: {}", status.out); - - let selection = at(server.addr, &["query", r#"{"limt": 5}"#], None); - assert_eq!(selection.code, 2); - assert!(selection.err.contains("selection.limt"), "{}", selection.err); -} - -#[test] -fn an_explicitly_empty_unknown_key_is_not_a_loss() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let mut doc = campaign_json(); - doc["value"]["ghost"] = Value::Null; - doc["value"]["ghosts"] = json!([]); - doc["value"]["ghost_map"] = json!({}); - doc["value"]["ghost_text"] = json!(""); - let file = write(&dir, "ghosts.json", &json!([doc])); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 0, "{}", ran.err); - assert!(ran.out.contains("read back 1 equal"), "{}", ran.out); -} - -#[test] -fn a_falsy_unknown_value_is_still_a_loss() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let mut doc = campaign_json(); - doc["value"]["zero"] = json!(0); - doc["value"]["no"] = json!(false); - let file = write(&dir, "falsy.json", &json!([doc])); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 2); - assert!(ran.err.contains("documents[0].value.zero") && ran.err.contains("documents[0].value.no"), "{}", ran.err); -} - -#[test] -fn a_document_that_does_not_decode_is_invalid_input() { - let dir = tempfile::tempdir().unwrap(); - let cases = [ - (json!([{ "kind": "nonsense", "value": {} }]), "documents does not decode"), - (json!("text"), "JSON array"), - (json!([[]]), "documents[0] must be a JSON object"), - (json!([]), "1 to 64"), - (json!((0..65).map(|_| campaign_json()).collect::>()), "1 to 64"), - ]; - for (n, (value, expected)) in cases.into_iter().enumerate() { - let file = write(&dir, &format!("case{n}.json"), &value); - let ran = at(closed_port(), &admit_args(&file), None); - assert_eq!(ran.code, 2, "{expected}: {}", ran.err); - assert!(ran.err.starts_with("InvalidInput: "), "{}", ran.err); - assert!(ran.err.contains(expected), "{expected}: {}", ran.err); - } - let broken = at(closed_port(), &admit_args("-"), Some("{ not json")); - assert_eq!(broken.code, 2); - assert!(broken.err.contains("not JSON"), "{}", broken.err); - let missing = at(closed_port(), &admit_args("/no/such/file.json"), None); - assert_eq!(missing.code, 2); - assert!(missing.err.contains("cannot read /no/such/file.json"), "{}", missing.err); -} - -#[test] -fn a_document_that_does_not_decode_never_echoes_its_values() { - let dir = tempfile::tempdir().unwrap(); - let mut string_for_number = report("canary"); - string_for_number["value"]["attempt"] = json!("CANARY-NUMBER"); - let mut long_string_for_list = campaign_json(); - long_string_for_list["value"]["repos"] = json!(format!("CANARY-LIST{}", "x".repeat(60_000))); - let unknown_kind = json!({ "kind": "CANARY-KIND", "value": {} }); - let mut unknown_variant = serde_json::to_value(ruling(None)).unwrap(); - unknown_variant["value"]["authority"] = json!("CANARY-VARIANT"); - for (n, document) in [string_for_number, long_string_for_list, unknown_kind, unknown_variant].into_iter().enumerate() { - let file = write(&dir, &format!("canary{n}.json"), &json!([document])); - let ran = at(closed_port(), &admit_args(&file), None); - assert_eq!(ran.code, 2, "case {n}: {}", ran.err); - assert!(ran.err.starts_with("InvalidInput: documents does not decode: "), "case {n}: {}", ran.err); - assert!(ran.err.contains(" at line 1 column "), "case {n}: {}", ran.err); - assert!(!ran.err.contains("CANARY") && !ran.out.contains("CANARY"), "case {n}: {}", ran.err); - assert!(ran.err.len() < 300, "stderr is bounded whatever the input: {} bytes", ran.err.len()); - } - let ran = at(closed_port(), &["query", r#"{"limit": "CANARY-LIMIT"}"#], None); - assert_eq!(ran.code, 2); - assert!(ran.err.starts_with("InvalidInput: selection does not decode: "), "{}", ran.err); - assert!(!ran.err.contains("CANARY") && ran.err.len() < 300, "{}", ran.err); - let ran = at(closed_port(), &admit_args("-"), Some(r#"[{"kind": "campaign", "value": CANARY-SYNTAX}]"#)); - assert_eq!(ran.code, 2); - assert!(ran.err.starts_with("InvalidInput: not JSON: syntax at line 1 column "), "{}", ran.err); - assert!(!ran.err.contains("CANARY"), "{}", ran.err); -} - -#[test] -fn a_refused_read_back_is_the_minds_no_with_the_receipt_printed() { - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "ruling.json", &json!([ruling(None)])); - let server = scripted(|message| { - let (_, request) = decode_request(message).expect("a mind request"); - match request { - HuginnMindRequest::Admit(_) => answer( - "admit", - &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { - receipt_id: "mind-commit-x".into(), - committed_at: "2026-10-10T00:00:00Z".into(), - writes: vec![], - }), - ), - _ => answer("query", &HuginnMindResponse::Refused(MindRefusal::MissingIdentity)), - } - }); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 1, "{}", ran.err); - assert!(ran.out.starts_with("Committed mind-commit-x at "), "{}", ran.out); - assert!(ran.out.contains("Refused MissingIdentity"), "{}", ran.out); - assert_eq!(ran.err, ""); -} - -fn view_of(document: &PipelineDocument) -> PipelineDocumentView { - PipelineDocumentView { - id: PipelineRef { kind: document.kind(), id: Short(pipeline_key(document).unwrap()) }, - document: document.clone(), - admission: AdmissionFacts { - receipt_id: "mind-commit-x".into(), - admitted_at: "2026-10-10T00:00:00Z".into(), - provenance: PipelineProvenance { - faculty: huginn_mind::Faculty::Hands, - agent: Short("a".into()), - session: Short("s".into()), - tool: Short("huginn".into()), - }, - ordinal: 1, - }, - status: PipelineStatus::InForce, - } -} - -/// Admits `Committed` and answers the keys query with `stored`. -fn committing(stored: Vec) -> Server { - scripted(move |message| { - let (_, request) = decode_request(message).expect("a mind request"); - match request { - HuginnMindRequest::Admit(_) => answer( - "admit", - &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { - receipt_id: "mind-commit-x".into(), - committed_at: "2026-10-10T00:00:00Z".into(), - writes: vec![], - }), - ), - HuginnMindRequest::Query { selection, .. } => { - assert_eq!(selection.projection, "document"); - assert_eq!(selection.limit, Some(u32::try_from(selection.keys.as_ref().unwrap().len()).unwrap())); - let page = PipelineSelectionPage { - matched: u32::try_from(stored.len()).unwrap(), - as_of: 2, - next: None, - items: PipelinePageItems::Documents(stored.clone()), - edges: None, - }; - answer("query", &HuginnMindResponse::Query(page)) - } - other => panic!("unexpected {other:?}"), - } - }) -} - -#[test] -fn a_field_the_mind_dropped_is_reported_with_the_receipt_printed() { - let dir = tempfile::tempdir().unwrap(); - let sent = ruling(Some("CANARY-QUOTE")); - let file = write(&dir, "ruling.json", &json!([sent])); - let key = pipeline_key(&sent).unwrap(); - - let server = committing(vec![view_of(&ruling(None))]); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 5); - assert!(ran.out.starts_with("Committed mind-commit-x at 2026-10-10T00:00:00Z"), "{}", ran.out); - assert!(!ran.out.contains("read back"), "{}", ran.out); - assert!(ran.err.starts_with(&format!("ReadBackDiffers: {key}: value.operator_quote;")), "{}", ran.err); - assert!(ran.err.contains("supersede"), "{}", ran.err); - - let missing = committing(vec![]); - let ran = at(missing.addr, &admit_args(&file), None); - assert_eq!(ran.code, 5); - assert!(ran.err.contains(&format!("{key}: missing from the read-back")), "{}", ran.err); - - let equal = committing(vec![view_of(&sent)]); - let ran = at(equal.addr, &admit_args(&file), None); - assert_eq!(ran.code, 0, "{}", ran.err); - assert!(ran.out.ends_with("read back 1 equal\n"), "{}", ran.out); -} - -#[test] -fn a_difference_deep_in_a_list_names_its_path() { - let dir = tempfile::tempdir().unwrap(); - let mut sent = serde_json::from_value::(spec("A")).unwrap(); - let rulings = |document: &mut PipelineDocument, ids: &[&str]| { - if let PipelineDocument::CutSpec(value) = document { - value.rulings = ids.iter().map(|id| Short(format!("{CAMPAIGN}:ruling:{id}"))).collect(); - } - }; - rulings(&mut sent, &["R1"]); - let file = write(&dir, "spec.json", &json!([sent])); - - let mut stored = sent.clone(); - rulings(&mut stored, &["R2"]); - if let PipelineDocument::CutSpec(value) = &mut stored { - value.title = "Another".into(); - } - let server = committing(vec![view_of(&stored)]); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 5); - assert!(ran.err.contains("value.rulings[0], value.title;"), "{}", ran.err); - - let mut longer = sent.clone(); - rulings(&mut longer, &["R1", "R2"]); - let server = committing(vec![view_of(&longer)]); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 5); - assert!(ran.err.contains("value.rulings;"), "{}", ran.err); - assert!(!ran.err.contains("rulings["), "{}", ran.err); -} - -#[test] -fn a_full_batch_passes_the_door() { - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "full.json", &json!((0..64).map(|_| campaign_json()).collect::>())); - let ran = at(closed_port(), &admit_args(&file), None); - assert_eq!(ran.code, 3, "64 documents are a batch; the daemon is what is down: {}", ran.err); -} - -#[test] -fn exit_codes_follow_the_answer() { - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "campaign.json", &json!([campaign_json()])); - - // Nothing listening: Unavailable, naming the endpoint, whoami included. - let port = closed_port(); - let down = at(port, &["view", "eureka-state:campaign:self"], None); - assert_eq!(down.code, 3); - assert!(down.err.starts_with("Unavailable: "), "{}", down.err); - assert!(down.err.contains(&format!("rudp://{port}")), "{}", down.err); - let whoami = at(port, &["whoami"], None); - assert_eq!(whoami.code, 3); - assert!(whoami.out.contains("reachable no"), "{}", whoami.out); - - // The daemon rejecting the envelope. - let rejecting = scripted(|_| { - encode_failure( - "eureka-state-call", - "view", - &OperationFailure { code: "wrong-service".into(), message: "not huginn.mind".into() }, - "scripted", - ) - }); - let rejected = at(rejecting.addr, &["view", "eureka-state:campaign:self"], None); - assert_eq!(rejected.code, 4); - assert!(rejected.err.starts_with("Rejected: "), "{}", rejected.err); - assert!(rejected.err.contains("wrong-service"), "{}", rejected.err); - - // An answer of another operation's shape. - let status = MindStatus { - instance: slug(INSTANCE), - schema_epoch: "e".into(), - documents: 0, - receipts: 0, - index: IndexStatus::Current, - persona: PersonaStatus::Absent, - }; - let (odd, _) = counting(HuginnMindResponse::Whoami(status), "view"); - let internal = at(odd.addr, &["view", "eureka-state:campaign:self"], None); - assert_eq!(internal.code, 4); - assert!(internal.err.starts_with("Internal: "), "{}", internal.err); - - // A batch no single send carries, refused before sending. - let mut huge = campaign_json(); - huge["value"]["working_branch"] = json!("b".repeat(90_000)); - let big = write(&dir, "huge.json", &json!([huge])); - let too_large = at(closed_port(), &admit_args(&big), None); - assert_eq!(too_large.code, 2); - assert!(too_large.err.starts_with("TooLarge: "), "{}", too_large.err); - assert!(too_large.err.contains(&eureka_state::MAX_REQUEST_BYTES.to_string()), "{}", too_large.err); - - // The mind saying no: a refusal is an answer on stdout. - let live = live(); - let refused = at(live.addr, &["admit", "--faculty", "Hands", "--agent", "a", "--session", "", &file], None); - assert_eq!(refused.code, 1); - assert!(refused.out.starts_with("Refused "), "{}", refused.out); - assert!(refused.out.contains("provenance.session"), "{}", refused.out); - assert_eq!(refused.err, ""); - - // Absent: the mind answered null. - let absent = at(live.addr, &["view", "eureka-state:cut_spec:cut-99.r1"], None); - assert_eq!(absent.code, 1); - assert_eq!(absent.out, "absent eureka-state:cut_spec:cut-99.r1\n"); - - // Another instance's mind: refused on the read side too. - let foreign = run( - &[("EUREKA_INSTANCE", "thought-cage"), ("HUGINN_ENDPOINT", &format!("rudp://{}", live.addr))], - &["query", "{}"], - None, - ); - assert_eq!(foreign.code, 1); - assert!(foreign.out.starts_with("Refused "), "{}", foreign.out); -} - -#[test] -fn a_call_that_is_wrong_exits_two_without_sending() { - let (server, count) = counting(HuginnMindResponse::View(None), "view"); - for args in [ - vec!["view", "eureka-state:nonsense:x"], - vec!["view", "no-kind-segment"], - vec!["history", "eureka-state:nonsense:x"], - vec!["query", "{ not json"], - vec!["query", "[]"], - vec!["admit", "--faculty", "Nope", "--agent", "a", "--session", "s", "x.json"], - vec!["schema", "no-such-kind"], - vec!["bogus"], - vec!["view"], - vec![], - ] { - let ran = at(server.addr, &args, None); - assert_eq!(ran.code, 2, "{args:?}"); - assert!(ran.err.starts_with("InvalidInput: "), "{args:?}: {}", ran.err); - assert_eq!(ran.out, "", "{args:?}"); - } - assert_eq!(*count.lock().unwrap(), 0); -} - -#[test] -fn the_recipes_send_exactly_the_pages_selections() { - let schema = |kind: &str| format!("epiphany.pipeline.{kind}.v2"); - let root = |values: &[&str]| json!({ "index": "root", "op": "any_of", "values": values }); - let in_force = json!({ "index": "in_force", "op": "any_of", "values": ["true"] }); - let c = "eureka-substrate"; - - let cases = [ - (vec!["campaigns"], json!({ "schemas": [schema("campaign")] })), - ( - vec!["target", c], - json!({ "schemas": [schema("target")], "fields": [root(&[c]), in_force], "projection": "document" }), - ), - ( - vec!["rulings", c, "eureka-body"], - json!({ "schemas": [schema("ruling")], "fields": [root(&[c, "eureka-body"]), in_force] }), - ), - ( - vec!["open", c], - json!({ "schemas": [schema("question"), schema("follow_up")], "fields": [root(&[c]), in_force] }), - ), - ( - vec!["findings", c], - json!({ - "schemas": [schema("finding")], - "fields": [root(&[c]), in_force, { "index": "faculty", "op": "any_of", "values": ["Soul"] }], - }), - ), - ( - vec!["findings", c, "--blocking"], - json!({ - "schemas": [schema("finding")], - "fields": [ - root(&[c]), - in_force, - { "index": "faculty", "op": "any_of", "values": ["Soul"] }, - { "index": "severity", "op": "any_of", "values": ["Blocker", "High"] }, - ], - }), - ), - ( - vec!["unreported", c], - json!({ - "schemas": [schema("cut_spec")], - "fields": [root(&[c]), in_force], - "cited": { "role": "cut_spec", "exists": false }, - }), - ), - ( - vec!["blocked", "eureka-substrate:cut_spec:cut-x.r1"], - json!({ - "schemas": [schema("question")], - "fields": [in_force], - "cites": { - "target": { "schemaId": schema("cut_spec"), "recordKey": "eureka-substrate:cut_spec:cut-x.r1" }, - "role": "raised_in", - }, - }), - ), - ( - vec!["unjudged", c], - json!({ - "schemas": [schema("cut_report")], - "fields": [root(&[c])], - "cited": { "role": "cut_report", "exists": false }, - }), - ), - ( - vec!["history", "eureka-substrate:ruling:R1"], - json!({ - "schemas": [schema("resolution")], - "cites": { "target": { "schemaId": schema("ruling"), "recordKey": "eureka-substrate:ruling:R1" }, "role": "subject" }, - "descending": true, - }), - ), - ( - vec!["cut", c, "huginn-cli"], - json!({ - "schemas": [schema("cut_spec"), schema("cut_report"), schema("verdict"), schema("finding"), schema("resolution")], - "fields": [root(&[c]), { "index": "cut", "op": "any_of", "values": ["huginn-cli"] }], - }), - ), - ( - vec!["ledger", c], - json!({ "schemas": [schema("cut_spec"), schema("cut_report")], "fields": [root(&[c])], "projection": "document" }), - ), - ( - vec!["precedent", c, "the question in plain words"], - json!({ "schemas": [schema("ruling"), schema("resolution"), schema("finding")], "fields": [root(&[c])] }), - ), - ( - vec!["gaps"], - json!({ "schemas": [schema("follow_up")], "fields": [root(&["eureka-substrate"]), in_force] }), - ), - ]; - for (args, literal) in cases { - let (selection, semantic) = sent(&args); - assert_eq!(selection, page_literal(literal), "{args:?}"); - let expected = (args[0] == "precedent").then(|| ("the question in plain words".to_string(), 10)); - assert_eq!(semantic, expected, "{args:?}"); - } -} - -#[test] -fn paging_and_query_flags_shape_the_selection() { - let (selection, semantic) = sent(&["gaps", "--cursor", "abc", "--documents"]); - assert_eq!(selection.cursor.as_deref(), Some("abc")); - assert_eq!(selection.projection, "document"); - assert_eq!(selection.limit, Some(50)); - assert_eq!(semantic, None); - - let (selection, _) = sent(&["gaps"]); - assert_eq!(selection.cursor, None); - assert_eq!(selection.projection, "header"); - - let (selection, semantic) = sent(&["query", "{}", "--near", "drift", "--top-k", "7"]); - assert_eq!(selection, page_literal(json!({}))); - assert_eq!(semantic, Some(("drift".to_string(), 7))); - let (_, semantic) = sent(&["query", "{}", "--near", "drift"]); - assert_eq!(semantic, Some(("drift".to_string(), 10))); - - let (selection, _) = sent(&["query", r#"{"limit": 5, "descending": true}"#]); - assert_eq!(selection.limit, Some(5)); - assert!(selection.descending); - let (selection, _) = sent(&["query", r#"{"projection": "header"}"#, "--documents"]); - assert_eq!(selection.projection, "document"); - - let ran = at(closed_port(), &["query", "{}", "--top-k", "3"], None); - assert_eq!(ran.code, 2, "--top-k needs --near"); - - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "selection.json", &json!({ "schemas": ["epiphany.pipeline.campaign.v2"] })); - let (selection, _) = sent(&["query", &format!("@{file}")]); - assert_eq!(selection.schemas, Some(vec!["epiphany.pipeline.campaign.v2".to_string()])); - let (server, seen) = recording(); - let ran = at(server.addr, &["query", "-"], Some(r#"{"keys": ["a:campaign:self"]}"#)); - assert_eq!(ran.code, 0, "{}", ran.err); - let seen = seen.lock().unwrap(); - let [HuginnMindRequest::Query { selection, .. }] = &seen[..] else { panic!("{seen:?}") }; - assert_eq!(selection.keys, Some(vec!["a:campaign:self".to_string()])); -} - -#[test] -fn recipes_list_what_the_mind_holds() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let campaign = write(&dir, "campaign.json", &json!([campaign_json()])); - let ran = at(server.addr, &admit_args(&campaign), None); - assert_eq!(ran.code, 0, "{}", ran.err); - let specs = write(&dir, "specs.json", &json!([spec("A"), spec("B")])); - let ran = at(server.addr, &admit_args(&specs), None); - assert_eq!(ran.code, 0, "{}", ran.err); - - let unreported = at(server.addr, &["unreported", CAMPAIGN], None); - assert_eq!(unreported.code, 0, "{}", unreported.err); - let mut lines: Vec<&str> = unreported.out.lines().collect(); - assert_eq!(lines.pop().unwrap().split(' ').take(2).collect::>(), ["matched", "2"]); - assert_eq!(lines.len(), 2); - - let reports = write(&dir, "report.json", &json!([report("B")])); - let ran = at(server.addr, &admit_args(&reports), None); - assert_eq!(ran.code, 0, "{}", ran.err); - - let unreported = at(server.addr, &["unreported", CAMPAIGN], None); - let lines: Vec<&str> = unreported.out.lines().collect(); - assert_eq!(lines.len(), 2, "{}", unreported.out); - let tokens: Vec<&str> = lines[0].split(' ').collect(); - let id = format!("{CAMPAIGN}:cut_spec:cut-A.r1"); - assert_eq!(tokens[..5], [id.as_str(), "InForce", "Hands", "A", "cut"]); - for fact in ["cut=A", "repo=GameCult/Epiphany", "revision=1", "base=5f98228d", "branch=codex/eureka-pipeline-state"] { - assert!(tokens.contains(&fact), "{fact}: {}", lines[0]); - } - assert!(lines[1].starts_with("matched 1 as_of "), "{}", lines[1]); - assert!(lines[1].ends_with(" next -"), "{}", lines[1]); - assert!(!unreported.out.contains("cut-B.r1"), "{}", unreported.out); - - let unjudged = at(server.addr, &["unjudged", CAMPAIGN], None); - assert!(unjudged.out.contains(&format!("{CAMPAIGN}:cut_report:cut-B.h1")), "{}", unjudged.out); - assert!(unjudged.out.contains("matched 1 "), "{}", unjudged.out); - - let campaigns = at(server.addr, &["campaigns"], None); - assert!(campaigns.out.starts_with(&format!("{CAMPAIGN}:campaign:self InForce Hands Eureka pipeline state repos={REPO}\n")), "{}", campaigns.out); - - let whole = at(server.addr, &["ledger", CAMPAIGN], None); - assert_eq!(whole.code, 0, "{}", whole.err); - assert_eq!(whole.out.matches("admitted ").count(), 3, "{}", whole.out); - assert!(!whole.out.starts_with('\n'), "{}", whole.out); - assert_eq!(whole.out.matches("\n\n").count(), 2, "documents are separated by one blank line: {}", whole.out); - - let documents = at(server.addr, &["campaigns", "--documents"], None); - assert!(documents.out.contains("\nadmitted "), "{}", documents.out); - assert!(documents.out.contains("\"kind\": \"campaign\""), "{}", documents.out); -} - -#[test] -fn a_long_header_is_cut() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let mut doc = campaign_json(); - doc["value"]["title"] = json!("t".repeat(200)); - doc["value"]["working_branch"] = json!("b"); - let file = write(&dir, "long.json", &json!([doc])); - assert_eq!(at(server.addr, &admit_args(&file), None).code, 0); - let ran = at(server.addr, &["campaigns"], None); - let header = ran.out.lines().next().unwrap(); - assert_eq!(header.chars().count(), 240); -} - -#[test] -fn a_resolved_document_shows_its_closing_record() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let question = json!({ - "kind": "question", - "value": { - "campaign": CAMPAIGN, - "label": "Q1", - "title": "Who owns the state?", - "question": "Who owns the state?", - "options": [{ "label": "A", "text": "an instance" }, { "label": "B", "text": "a repo" }], - "recommended": "A", - "depends": [], - "raised_in": null, - "asked_on": "2026-10-10", - }, - }); - let setup = write(&dir, "setup.json", &json!([campaign_json(), question])); - let ran = at(server.addr, &admit_args(&setup), None); - assert_eq!(ran.code, 0, "{}{}", ran.out, ran.err); - let resolution = json!({ - "kind": "resolution", - "value": { - "subject": { "kind": "Question", "id": format!("{CAMPAIGN}:question:Q1") }, - "sequence": 1, - "outcome": { "Withdrawn": { "reason": "moot" } }, - "rationale": "Resolved.", - "resolved_on": "2026-10-10", - }, - }); - let closing = write(&dir, "closing.json", &json!([resolution])); - let ran = at(server.addr, &admit_args(&closing), None); - assert_eq!(ran.code, 0, "{}{}", ran.out, ran.err); - - let id = format!("{CAMPAIGN}:question:Q1"); - let closer = format!("{CAMPAIGN}:resolution:question.Q1.n1"); - let viewed = at(server.addr, &["view", &id], None); - assert_eq!(viewed.out.lines().next().unwrap(), format!("{id} Resolved Withdrawn by {closer}")); - - let history = at(server.addr, &["history", &id], None); - assert_eq!(history.code, 0, "{}", history.err); - assert!(history.out.starts_with(&format!("{closer} InForce Hands ")), "{}", history.out); - assert!(history.out.contains("sequence=1"), "{}", history.out); - - let open = at(server.addr, &["open", CAMPAIGN], None); - assert!(open.out.contains("matched 0 "), "a resolved question is not open: {}", open.out); - - let header = at(server.addr, &["query", r#"{"schemas": ["epiphany.pipeline.question.v2"]}"#], None); - assert!(header.out.starts_with(&format!("{id} Resolved:Withdrawn Hands Who owns the state? ")), "{}", header.out); - assert!(header.out.contains("options=A,B") && header.out.contains("recommended=A"), "{}", header.out); -} - -#[test] -fn schema_prints_the_published_files() { - let manifest = Path::new(env!("CARGO_MANIFEST_DIR")); - for kind in ["cut_spec", "campaign", "hand_off", "run"] { - let ran = run(&[], &["schema", kind], None); - assert_eq!(ran.code, 0); - let published = std::fs::read_to_string(manifest.join(format!("../../schemas/cultnet/epiphany.pipeline.{kind}.v2.schema.json"))).unwrap(); - assert_eq!(ran.out, published, "{kind}"); - } - let selection = run(&[], &["schema", "selection"], None); - assert_eq!(selection.out, std::fs::read_to_string(manifest.join("schemas/cultnet.selection.schema.json")).unwrap()); - let names = run(&[], &["schema"], None); - assert_eq!(names.code, 0); - let names: Vec<&str> = names.out.lines().collect(); - assert_eq!(names.len(), 15, "{names:?}"); - assert_eq!(names[0], "campaign"); - assert_eq!(names[14], "selection"); - for kind in PipelineKind::ALL { - assert!(names.contains(&kind.name()), "{}", kind.name()); - } - let unknown = run(&[], &["schema", "no-such-kind"], None); - assert_eq!(unknown.code, 2); - assert!(unknown.err.starts_with("InvalidInput: "), "{}", unknown.err); -} - -#[test] -fn help_is_the_schema_surface() { - let rulings = run(&[], &["rulings", "--help"], None); - assert_eq!(rulings.code, 0); - let (_, printed) = rulings.out.split_once("selection:\n").expect("the selection is in the help"); - let selection: Value = serde_json::from_str(printed.trim()).unwrap(); - assert_eq!( - selection, - json!({ - "schemas": ["epiphany.pipeline.ruling.v2"], - "fields": [ - { "index": "root", "op": "any_of", "values": [""] }, - { "index": "in_force", "op": "any_of", "values": ["true"] }, - ], - }) - ); - let history = run(&[], &["history", "--help"], None); - assert!(history.out.contains("epiphany.pipeline..v2"), "{}", history.out); - let findings = run(&[], &["findings", "--help"], None); - assert!(findings.out.contains("\"severity\"") && findings.out.contains("Blocker"), "{}", findings.out); - let precedent = run(&[], &["precedent", "--help"], None); - assert!(precedent.out.contains("\"top_k\": 10"), "{}", precedent.out); - let admit = run(&[], &["admit", "--help"], None); - let admit_text = admit.out.split_whitespace().collect::>().join(" "); - assert!(admit_text.contains("{\"kind\": , \"value\": {...}}"), "{admit_text}"); - assert!(admit_text.contains("exit 5"), "{admit_text}"); - - let version = run(&[], &["--version"], None); - assert_eq!(version.code, 0); - let sha = option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown"); - assert_eq!(version.out, format!("huginn {} ({sha})\n", env!("CARGO_PKG_VERSION"))); -} - -#[test] -fn every_recipe_has_help() { - for recipe in [ - "campaigns", "target", "rulings", "open", "findings", "unreported", "blocked", "unjudged", "history", "cut", "ledger", - "precedent", "gaps", - ] { - let ran = run(&[], &[recipe, "--help"], None); - assert_eq!(ran.code, 0, "{recipe}"); - assert!(ran.out.contains("epiphany.pipeline."), "{recipe}: {}", ran.out); - assert!(ran.out.contains("--cursor"), "{recipe}: {}", ran.out); - } -} - -#[test] -fn a_conflicting_batch_is_the_minds_no() { - let conflict = scripted(|message| { - let (_, request) = decode_request(message).expect("a mind request"); - assert!(matches!(request, HuginnMindRequest::Admit(_))); - answer( - "admit", - &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { - identities: vec![PipelineRef { kind: PipelineKind::Campaign, id: Short(format!("{CAMPAIGN}:campaign:self")) }], - }), - ) - }); - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "campaign.json", &json!([campaign_json()])); - let ran = at(conflict.addr, &admit_args(&file), None); - assert_eq!(ran.code, 1); - assert_eq!(ran.out, format!("Conflict\nconflicts {CAMPAIGN}:campaign:self\n")); -} +//! The `huginn` binary as an agent drives it: a real process, its stdout, its +//! stderr and its exit code, against a real daemon in-process or a scripted +//! server where the daemon cannot be made to misbehave. + +use std::io::Write; +use std::net::{SocketAddr, UdpSocket}; +use std::path::Path; +use std::process::{Command, Stdio}; +use std::sync::{Arc, Mutex}; + +use cultnet_rs::Selection; +use huginn_mind::envelope::{OperationFailure, decode_request, encode_failure, encode_response}; +use huginn_mind::eureka_pipeline::{ + CodeLocation, CommitRange, CutVerification, Date, Evidence, EvidenceKind, MutationRecord, OrgRepo, PipelineCutReport, + PipelineCutSpec, PipelineDocument, PipelineKind, PipelineRef, PipelineRuling, Promise, ReportCommit, RulingAuthority, Short, + StructuralDelta, pipeline_key, +}; +use huginn_mind::{ + AdmissionFacts, HuginnMindRequest, HuginnMindResponse, IndexStatus, MindRefusal, MindStatus, PersonaStatus, PipelineAdmissionOutcome, PipelineDocumentView, + PipelinePageItems, PipelineProvenance, PipelineSelectionPage, PipelineStatus, +}; +use serde_json::{Value, json}; +use tempfile::TempDir; + +mod common; +use common::*; + +struct Run { + code: i32, + out: String, + err: String, +} + +fn run(env: &[(&str, &str)], args: &[&str], stdin: Option<&str>) -> Run { + let mut command = Command::new(env!("CARGO_BIN_EXE_huginn")); + command + .env_remove("EUREKA_INSTANCE") + .env_remove("HUGINN_ENDPOINT") + .envs(env.iter().copied()) + .args(args) + .stdin(if stdin.is_some() { Stdio::piped() } else { Stdio::null() }) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + let mut child = command.spawn().expect("the binary starts"); + if let Some(text) = stdin { + child.stdin.take().unwrap().write_all(text.as_bytes()).unwrap(); + } + let output = child.wait_with_output().unwrap(); + Run { + code: output.status.code().expect("exited, not killed"), + out: String::from_utf8(output.stdout).unwrap(), + err: String::from_utf8(output.stderr).unwrap(), + } +} + +/// Configured for the test instance against a daemon at `addr`. +fn at(addr: SocketAddr, args: &[&str], stdin: Option<&str>) -> Run { + run(&[("EUREKA_INSTANCE", INSTANCE), ("HUGINN_ENDPOINT", &format!("rudp://{addr}"))], args, stdin) +} + +/// A loopback UDP port nothing listens on. +fn closed_port() -> SocketAddr { + UdpSocket::bind("127.0.0.1:0").unwrap().local_addr().unwrap() +} + +fn write(dir: &TempDir, name: &str, value: &Value) -> String { + let path = dir.path().join(name); + std::fs::write(&path, value.to_string()).unwrap(); + path.to_str().unwrap().to_string() +} + +fn campaign_json() -> Value { + serde_json::to_value(campaign()).unwrap() +} + +fn live() -> Server { + let (root, daemon) = mind(vec![vec![stewardship()]]); + serve(root, daemon) +} + +fn admit_args(file: &str) -> Vec<&str> { + vec!["admit", "--faculty", "Hands", "--agent", "claude", "--session", "session-7", file] +} + +fn delta() -> StructuralDelta { + StructuralDelta { + lines_added: 0, + lines_removed: 0, + dependencies_added: vec![], + dependencies_removed: vec![], + formats_added: vec![], + formats_removed: vec![], + targets_added: vec![], + targets_removed: vec![], + } +} + +fn spec(cut: &str) -> Value { + serde_json::to_value(PipelineDocument::CutSpec(PipelineCutSpec { + campaign: slug(CAMPAIGN), + cut: cut.into(), + revision: 1, + title: "A cut".into(), + repo: OrgRepo(REPO.into()), + branch: "codex/eureka-pipeline-state".into(), + base: sha(), + depends_on: vec![], + first: vec![], + deletes: vec![], + keeps_moves: vec![], + adds: vec![], + file_changes: vec![], + reads: vec![], + authority_map: None, + verification: CutVerification { builds: vec![], tests: vec![], negative: vec![], operator: vec![] }, + estimate: delta(), + rulings: vec![], + questions: vec![], + })) + .unwrap() +} + +fn report(cut: &str) -> Value { + serde_json::to_value(PipelineDocument::CutReport(PipelineCutReport { + campaign: slug(CAMPAIGN), + cut_spec: Short(format!("{CAMPAIGN}:cut_spec:cut-{cut}.r1")), + attempt: 1, + repo: OrgRepo(REPO.into()), + branch: "codex/eureka-pipeline-state".into(), + commits: vec![ReportCommit { sha: sha(), subject: "Land the cut".into(), builds: true }], + range: CommitRange { base: sha(), head: sha() }, + verification: vec![Evidence { kind: EvidenceKind::Test, locator: "cargo test".into(), result: "ok".into() }], + mutations: vec![MutationRecord { + label: "M1".into(), + rule: "the rule".into(), + location: CodeLocation { path: Short("crates/x.rs".into()), line: 1, end_line: None, symbol: None }, + before: "before".into(), + after: "after".into(), + commit: sha(), + failed_as_expected: true, + }], + deviations: vec![], + forks: vec![], + structural_delta: delta(), + landed_names: vec![], + undone: vec![], + promises: vec![Promise { label: "P1".into(), text: "One derived key per document.".into() }], + })) + .unwrap() +} + +fn ruling(quote: Option<&str>) -> PipelineDocument { + PipelineDocument::Ruling(PipelineRuling { + campaign: slug(CAMPAIGN), + label: "R1".into(), + title: "An instance owns its mind".into(), + answers: None, + choice: None, + ruling: "An instance owns its mind.".into(), + operator_quote: quote.map(Into::into), + ruled_on: Date("2026-10-10".into()), + precedents: vec![], + authority: RulingAuthority::Standing, + }) +} + +fn empty_page() -> PipelineSelectionPage { + PipelineSelectionPage { matched: 0, as_of: 1, next: None, items: PipelinePageItems::Headers(vec![]), edges: None } +} + +fn answer(operation: &str, response: &HuginnMindResponse) -> cultnet_rs::CultNetMessage { + encode_response("eureka-state-call", operation, response, "scripted").unwrap() +} + +/// A scripted server that records every request it is sent and answers a +/// query with an empty page. +fn recording() -> (Server, Arc>>) { + let seen = Arc::new(Mutex::new(Vec::new())); + let sink = Arc::clone(&seen); + let server = scripted(move |message| { + let (_, request) = decode_request(message).expect("a mind request"); + sink.lock().unwrap().push(request); + answer("query", &HuginnMindResponse::Query(empty_page())) + }); + (server, seen) +} + +/// The selection a command sent, and its semantic part. +fn sent(args: &[&str]) -> (Selection, Option<(String, u32)>) { + let (server, seen) = recording(); + let ran = at(server.addr, args, None); + assert_eq!(ran.code, 0, "{args:?}: {}", ran.err); + assert!(ran.out.contains("matched 0 as_of 1 next -"), "{}", ran.out); + let seen = seen.lock().unwrap(); + let [HuginnMindRequest::Query { instance, selection, semantic }] = &seen[..] else { + panic!("one query expected: {seen:?}"); + }; + assert_eq!(instance.0, INSTANCE); + (selection.clone(), semantic.as_ref().map(|asked| (asked.text.0.clone(), asked.top_k))) +} + +/// The page's literal as the selection it spells, with the CLI's default page. +fn page_literal(literal: Value) -> Selection { + let mut selection: Selection = serde_json::from_value(literal).unwrap(); + selection.limit = Some(50); + selection +} + +fn counting(replies: HuginnMindResponse, operation: &'static str) -> (Server, Arc>) { + let count = Arc::new(Mutex::new(0)); + let counter = Arc::clone(&count); + let server = scripted(move |_| { + *counter.lock().unwrap() += 1; + answer(operation, &replies) + }); + (server, count) +} + +#[test] +fn without_configuration_whoami_reports_it_and_every_other_command_refuses() { + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "campaign.json", &json!([campaign_json()])); + + let whoami = run(&[], &["whoami"], None); + assert_eq!(whoami.code, 2); + assert!(whoami.out.contains("instance unset\nendpoint unset\nclient "), "{}", whoami.out); + assert!(whoami.out.contains("reachable no"), "{}", whoami.out); + assert!(whoami.err.starts_with("Misconfigured: EUREKA_INSTANCE is not set"), "{}", whoami.err); + + for args in [ + vec!["view", "eureka-state:campaign:self"], + vec!["query", "{}"], + vec!["rulings", "eureka-state"], + admit_args(&file), + ] { + let ran = run(&[], &args, None); + assert_eq!(ran.code, 2, "{args:?}"); + assert!(ran.err.starts_with("Misconfigured:"), "{args:?}: {}", ran.err); + assert_eq!(ran.out, "", "{args:?}"); + } +} + +#[test] +fn a_bad_environment_is_misconfigured_with_its_own_reason() { + let cases: [(&[(&str, &str)], &str); 4] = [ + (&[("HUGINN_ENDPOINT", "rudp://127.0.0.1:1")], "EUREKA_INSTANCE is not set"), + (&[("EUREKA_INSTANCE", "Not A Slug"), ("HUGINN_ENDPOINT", "rudp://127.0.0.1:1")], "EUREKA_INSTANCE is not a valid"), + (&[("EUREKA_INSTANCE", "eureka")], "HUGINN_ENDPOINT is not set"), + (&[("EUREKA_INSTANCE", "eureka"), ("HUGINN_ENDPOINT", "127.0.0.1:1")], "HUGINN_ENDPOINT is not rudp://"), + ]; + for (env, expected) in cases { + let ran = run(env, &["whoami"], None); + assert_eq!(ran.code, 2, "{expected}"); + assert!(ran.err.starts_with("Misconfigured: "), "{}", ran.err); + assert!(ran.err.contains(expected), "{expected}: {}", ran.err); + } + let named = run(&[("EUREKA_INSTANCE", "eureka"), ("HUGINN_ENDPOINT", "rudp://not-an-address")], &["whoami"], None); + assert_eq!(named.code, 2); + assert!(named.out.contains("endpoint rudp://not-an-address"), "{}", named.out); + assert!(named.out.contains("instance eureka"), "{}", named.out); +} + +#[test] +fn whoami_reads_the_live_mind() { + let server = live(); + let ran = at(server.addr, &["whoami"], None); + assert_eq!(ran.code, 0, "{}", ran.err); + let lines: Vec<&str> = ran.out.lines().collect(); + assert_eq!(lines[0], format!("instance {INSTANCE}")); + assert_eq!(lines[1], format!("endpoint rudp://{}", server.addr)); + assert_eq!(lines[2], format!("client {}", option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown"))); + assert_eq!(lines[3], "reachable yes"); + assert_eq!(lines[4], "documents 2 receipts 2 index Current epoch epiphany.pipeline.epoch.v2"); + assert_eq!(lines[5], "persona absent"); + assert_eq!(lines.len(), 6); + assert_eq!(ran.err, ""); +} + +#[test] +fn an_index_that_is_behind_shows_its_count() { + let status = MindStatus { + instance: slug(INSTANCE), + schema_epoch: "epoch".into(), + documents: 7, + receipts: 9, + index: IndexStatus::Behind { pending: 3 }, + persona: PersonaStatus::Absent, + }; + let (server, _) = counting(HuginnMindResponse::Whoami(status), "whoami"); + let ran = at(server.addr, &["whoami"], None); + assert_eq!(ran.code, 0); + assert!(ran.out.contains("documents 7 receipts 9 index Behind pending=3 epoch epoch"), "{}", ran.out); +} + +#[test] +fn whoami_shows_the_persona_door_state_and_nothing_of_the_document() { + for (persona, line) in [ + (PersonaStatus::Stored { updated_at: "2026-10-10T10:00:00Z".into() }, "persona stored updatedAt=2026-10-10T10:00:00Z"), + (PersonaStatus::Unreadable, "persona unreadable"), + ] { + let status = MindStatus { instance: slug(INSTANCE), schema_epoch: "e".into(), documents: 1, receipts: 1, index: IndexStatus::Current, persona }; + let (server, _) = counting(HuginnMindResponse::Whoami(status), "whoami"); + let ran = at(server.addr, &["whoami"], None); + assert_eq!(ran.code, 0); + assert_eq!(ran.out.lines().last(), Some(line), "{}", ran.out); + } +} + +#[test] +fn admit_round_trips_and_is_idempotent() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "campaign.json", &json!([campaign_json()])); + + let first = at(server.addr, &admit_args(&file), None); + assert_eq!(first.code, 0, "{}", first.err); + let lines: Vec<&str> = first.out.lines().collect(); + assert!(lines[0].starts_with("Committed mind-commit-"), "{}", first.out); + assert!(lines[0].contains(" at "), "{}", first.out); + assert_eq!(lines[1], format!("wrote {CAMPAIGN}:campaign:self")); + assert_eq!(lines[2], "read back 1 equal"); + assert_eq!(lines.len(), 3, "{}", first.out); + + let again = at(server.addr, &admit_args(&file), None); + assert_eq!(again.code, 0, "{}", again.err); + let lines: Vec<&str> = again.out.lines().collect(); + assert!(lines[0].starts_with("AlreadyAdmitted mind-commit-"), "{}", again.out); + assert_eq!(lines[1], "read back 1 equal"); + + let id = format!("{CAMPAIGN}:campaign:self"); + let viewed = at(server.addr, &["view", &id], None); + assert_eq!(viewed.code, 0, "{}", viewed.err); + let lines: Vec<&str> = viewed.out.lines().collect(); + assert_eq!(lines[0], format!("{id} InForce")); + assert!(lines[1].starts_with("admitted "), "{}", viewed.out); + assert!(lines[1].contains(" ordinal 3 Hands/claude session session-7 tool huginn receipt mind-commit-"), "{}", lines[1]); + let shown: Value = serde_json::from_str(&lines[2..].join("\n")).unwrap(); + assert_eq!(shown, campaign_json()); + + let raw = at(server.addr, &["view", &id, "--raw"], None); + assert_eq!(raw.code, 0); + assert_eq!(serde_json::from_str::(&raw.out).unwrap(), campaign_json()); + assert!(raw.out.starts_with('{'), "{}", raw.out); + + let fed_back = at(server.addr, &admit_args("-"), Some(&raw.out)); + assert_eq!(fed_back.code, 0, "{}", fed_back.err); + assert!(fed_back.out.starts_with("AlreadyAdmitted "), "{}", fed_back.out); + + let status = at(server.addr, &["whoami"], None); + assert!(status.out.contains("documents 3 receipts 3"), "{}", status.out); +} + +#[test] +fn unknown_keys_are_refused_by_path_and_never_by_value() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let mut nested = campaign_json(); + nested["value"]["target_doc"]["pathh"] = json!("CANARY-NESTED"); + let mut top = campaign_json(); + top["surplus"] = json!("CANARY-TOP"); + let file = write(&dir, "bad.json", &json!([nested, top])); + + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 2); + assert_eq!(ran.out, ""); + assert!(ran.err.starts_with("InvalidInput: "), "{}", ran.err); + assert!(ran.err.contains("documents[0].value.target_doc.pathh"), "{}", ran.err); + assert!(ran.err.contains("documents[1].surplus"), "{}", ran.err); + assert!(!ran.err.contains("CANARY"), "{}", ran.err); + + let status = at(server.addr, &["whoami"], None); + assert!(status.out.contains("receipts 2 "), "nothing was sent: {}", status.out); + + let selection = at(server.addr, &["query", r#"{"limt": 5}"#], None); + assert_eq!(selection.code, 2); + assert!(selection.err.contains("selection.limt"), "{}", selection.err); +} + +#[test] +fn an_explicitly_empty_unknown_key_is_not_a_loss() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let mut doc = campaign_json(); + doc["value"]["ghost"] = Value::Null; + doc["value"]["ghosts"] = json!([]); + doc["value"]["ghost_map"] = json!({}); + doc["value"]["ghost_text"] = json!(""); + let file = write(&dir, "ghosts.json", &json!([doc])); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 0, "{}", ran.err); + assert!(ran.out.contains("read back 1 equal"), "{}", ran.out); +} + +#[test] +fn a_falsy_unknown_value_is_still_a_loss() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let mut doc = campaign_json(); + doc["value"]["zero"] = json!(0); + doc["value"]["no"] = json!(false); + let file = write(&dir, "falsy.json", &json!([doc])); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 2); + assert!(ran.err.contains("documents[0].value.zero") && ran.err.contains("documents[0].value.no"), "{}", ran.err); +} + +#[test] +fn a_document_that_does_not_decode_is_invalid_input() { + let dir = tempfile::tempdir().unwrap(); + let cases = [ + (json!([{ "kind": "nonsense", "value": {} }]), "documents does not decode"), + (json!("text"), "JSON array"), + (json!([[]]), "documents[0] must be a JSON object"), + (json!([]), "1 to 64"), + (json!((0..65).map(|_| campaign_json()).collect::>()), "1 to 64"), + ]; + for (n, (value, expected)) in cases.into_iter().enumerate() { + let file = write(&dir, &format!("case{n}.json"), &value); + let ran = at(closed_port(), &admit_args(&file), None); + assert_eq!(ran.code, 2, "{expected}: {}", ran.err); + assert!(ran.err.starts_with("InvalidInput: "), "{}", ran.err); + assert!(ran.err.contains(expected), "{expected}: {}", ran.err); + } + let broken = at(closed_port(), &admit_args("-"), Some("{ not json")); + assert_eq!(broken.code, 2); + assert!(broken.err.contains("not JSON"), "{}", broken.err); + let missing = at(closed_port(), &admit_args("/no/such/file.json"), None); + assert_eq!(missing.code, 2); + assert!(missing.err.contains("cannot read /no/such/file.json"), "{}", missing.err); +} + +#[test] +fn a_document_that_does_not_decode_never_echoes_its_values() { + let dir = tempfile::tempdir().unwrap(); + let mut string_for_number = report("canary"); + string_for_number["value"]["attempt"] = json!("CANARY-NUMBER"); + let mut long_string_for_list = campaign_json(); + long_string_for_list["value"]["repos"] = json!(format!("CANARY-LIST{}", "x".repeat(60_000))); + let unknown_kind = json!({ "kind": "CANARY-KIND", "value": {} }); + let mut unknown_variant = serde_json::to_value(ruling(None)).unwrap(); + unknown_variant["value"]["authority"] = json!("CANARY-VARIANT"); + for (n, document) in [string_for_number, long_string_for_list, unknown_kind, unknown_variant].into_iter().enumerate() { + let file = write(&dir, &format!("canary{n}.json"), &json!([document])); + let ran = at(closed_port(), &admit_args(&file), None); + assert_eq!(ran.code, 2, "case {n}: {}", ran.err); + assert!(ran.err.starts_with("InvalidInput: documents does not decode: "), "case {n}: {}", ran.err); + assert!(ran.err.contains(" at line 1 column "), "case {n}: {}", ran.err); + assert!(!ran.err.contains("CANARY") && !ran.out.contains("CANARY"), "case {n}: {}", ran.err); + assert!(ran.err.len() < 300, "stderr is bounded whatever the input: {} bytes", ran.err.len()); + } + let ran = at(closed_port(), &["query", r#"{"limit": "CANARY-LIMIT"}"#], None); + assert_eq!(ran.code, 2); + assert!(ran.err.starts_with("InvalidInput: selection does not decode: "), "{}", ran.err); + assert!(!ran.err.contains("CANARY") && ran.err.len() < 300, "{}", ran.err); + let ran = at(closed_port(), &admit_args("-"), Some(r#"[{"kind": "campaign", "value": CANARY-SYNTAX}]"#)); + assert_eq!(ran.code, 2); + assert!(ran.err.starts_with("InvalidInput: not JSON: syntax at line 1 column "), "{}", ran.err); + assert!(!ran.err.contains("CANARY"), "{}", ran.err); +} + +#[test] +fn a_refused_read_back_is_the_minds_no_with_the_receipt_printed() { + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "ruling.json", &json!([ruling(None)])); + let server = scripted(|message| { + let (_, request) = decode_request(message).expect("a mind request"); + match request { + HuginnMindRequest::Admit(_) => answer( + "admit", + &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { + receipt_id: "mind-commit-x".into(), + committed_at: "2026-10-10T00:00:00Z".into(), + writes: vec![], + }), + ), + _ => answer("query", &HuginnMindResponse::Refused(MindRefusal::MissingIdentity)), + } + }); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 1, "{}", ran.err); + assert!(ran.out.starts_with("Committed mind-commit-x at "), "{}", ran.out); + assert!(ran.out.contains("Refused MissingIdentity"), "{}", ran.out); + assert_eq!(ran.err, ""); +} + +fn view_of(document: &PipelineDocument) -> PipelineDocumentView { + PipelineDocumentView { + id: PipelineRef { kind: document.kind(), id: Short(pipeline_key(document).unwrap()) }, + document: document.clone(), + admission: AdmissionFacts { + receipt_id: "mind-commit-x".into(), + admitted_at: "2026-10-10T00:00:00Z".into(), + provenance: PipelineProvenance { + faculty: huginn_mind::Faculty::Hands, + agent: Short("a".into()), + session: Short("s".into()), + tool: Short("huginn".into()), + }, + ordinal: 1, + }, + status: PipelineStatus::InForce, + } +} + +/// Admits `Committed` and answers the keys query with `stored`. +fn committing(stored: Vec) -> Server { + scripted(move |message| { + let (_, request) = decode_request(message).expect("a mind request"); + match request { + HuginnMindRequest::Admit(_) => answer( + "admit", + &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { + receipt_id: "mind-commit-x".into(), + committed_at: "2026-10-10T00:00:00Z".into(), + writes: vec![], + }), + ), + HuginnMindRequest::Query { selection, .. } => { + assert_eq!(selection.projection, "document"); + assert_eq!(selection.limit, Some(u32::try_from(selection.keys.as_ref().unwrap().len()).unwrap())); + let page = PipelineSelectionPage { + matched: u32::try_from(stored.len()).unwrap(), + as_of: 2, + next: None, + items: PipelinePageItems::Documents(stored.clone()), + edges: None, + }; + answer("query", &HuginnMindResponse::Query(page)) + } + other => panic!("unexpected {other:?}"), + } + }) +} + +#[test] +fn a_field_the_mind_dropped_is_reported_with_the_receipt_printed() { + let dir = tempfile::tempdir().unwrap(); + let sent = ruling(Some("CANARY-QUOTE")); + let file = write(&dir, "ruling.json", &json!([sent])); + let key = pipeline_key(&sent).unwrap(); + + let server = committing(vec![view_of(&ruling(None))]); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 5); + assert!(ran.out.starts_with("Committed mind-commit-x at 2026-10-10T00:00:00Z"), "{}", ran.out); + assert!(!ran.out.contains("read back"), "{}", ran.out); + assert!(ran.err.starts_with(&format!("ReadBackDiffers: {key}: value.operator_quote;")), "{}", ran.err); + assert!(ran.err.contains("supersede"), "{}", ran.err); + + let missing = committing(vec![]); + let ran = at(missing.addr, &admit_args(&file), None); + assert_eq!(ran.code, 5); + assert!(ran.err.contains(&format!("{key}: missing from the read-back")), "{}", ran.err); + + let equal = committing(vec![view_of(&sent)]); + let ran = at(equal.addr, &admit_args(&file), None); + assert_eq!(ran.code, 0, "{}", ran.err); + assert!(ran.out.ends_with("read back 1 equal\n"), "{}", ran.out); +} + +#[test] +fn a_difference_deep_in_a_list_names_its_path() { + let dir = tempfile::tempdir().unwrap(); + let mut sent = serde_json::from_value::(spec("A")).unwrap(); + let rulings = |document: &mut PipelineDocument, ids: &[&str]| { + if let PipelineDocument::CutSpec(value) = document { + value.rulings = ids.iter().map(|id| Short(format!("{CAMPAIGN}:ruling:{id}"))).collect(); + } + }; + rulings(&mut sent, &["R1"]); + let file = write(&dir, "spec.json", &json!([sent])); + + let mut stored = sent.clone(); + rulings(&mut stored, &["R2"]); + if let PipelineDocument::CutSpec(value) = &mut stored { + value.title = "Another".into(); + } + let server = committing(vec![view_of(&stored)]); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 5); + assert!(ran.err.contains("value.rulings[0], value.title;"), "{}", ran.err); + + let mut longer = sent.clone(); + rulings(&mut longer, &["R1", "R2"]); + let server = committing(vec![view_of(&longer)]); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 5); + assert!(ran.err.contains("value.rulings;"), "{}", ran.err); + assert!(!ran.err.contains("rulings["), "{}", ran.err); +} + +#[test] +fn a_full_batch_passes_the_door() { + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "full.json", &json!((0..64).map(|_| campaign_json()).collect::>())); + let ran = at(closed_port(), &admit_args(&file), None); + assert_eq!(ran.code, 3, "64 documents are a batch; the daemon is what is down: {}", ran.err); +} + +#[test] +fn exit_codes_follow_the_answer() { + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "campaign.json", &json!([campaign_json()])); + + // Nothing listening: Unavailable, naming the endpoint, whoami included. + let port = closed_port(); + let down = at(port, &["view", "eureka-state:campaign:self"], None); + assert_eq!(down.code, 3); + assert!(down.err.starts_with("Unavailable: "), "{}", down.err); + assert!(down.err.contains(&format!("rudp://{port}")), "{}", down.err); + let whoami = at(port, &["whoami"], None); + assert_eq!(whoami.code, 3); + assert!(whoami.out.contains("reachable no"), "{}", whoami.out); + + // The daemon rejecting the envelope. + let rejecting = scripted(|_| { + encode_failure( + "eureka-state-call", + "view", + &OperationFailure { code: "wrong-service".into(), message: "not huginn.mind".into() }, + "scripted", + ) + }); + let rejected = at(rejecting.addr, &["view", "eureka-state:campaign:self"], None); + assert_eq!(rejected.code, 4); + assert!(rejected.err.starts_with("Rejected: "), "{}", rejected.err); + assert!(rejected.err.contains("wrong-service"), "{}", rejected.err); + + // An answer of another operation's shape. + let status = MindStatus { + instance: slug(INSTANCE), + schema_epoch: "e".into(), + documents: 0, + receipts: 0, + index: IndexStatus::Current, + persona: PersonaStatus::Absent, + }; + let (odd, _) = counting(HuginnMindResponse::Whoami(status), "view"); + let internal = at(odd.addr, &["view", "eureka-state:campaign:self"], None); + assert_eq!(internal.code, 4); + assert!(internal.err.starts_with("Internal: "), "{}", internal.err); + + // A batch no single send carries, refused before sending. + let mut huge = campaign_json(); + huge["value"]["working_branch"] = json!("b".repeat(90_000)); + let big = write(&dir, "huge.json", &json!([huge])); + let too_large = at(closed_port(), &admit_args(&big), None); + assert_eq!(too_large.code, 2); + assert!(too_large.err.starts_with("TooLarge: "), "{}", too_large.err); + assert!(too_large.err.contains(&eureka_state::MAX_REQUEST_BYTES.to_string()), "{}", too_large.err); + + // The mind saying no: a refusal is an answer on stdout. + let live = live(); + let refused = at(live.addr, &["admit", "--faculty", "Hands", "--agent", "a", "--session", "", &file], None); + assert_eq!(refused.code, 1); + assert!(refused.out.starts_with("Refused "), "{}", refused.out); + assert!(refused.out.contains("provenance.session"), "{}", refused.out); + assert_eq!(refused.err, ""); + + // Absent: the mind answered null. + let absent = at(live.addr, &["view", "eureka-state:cut_spec:cut-99.r1"], None); + assert_eq!(absent.code, 1); + assert_eq!(absent.out, "absent eureka-state:cut_spec:cut-99.r1\n"); + + // Another instance's mind: refused on the read side too. + let foreign = run( + &[("EUREKA_INSTANCE", "thought-cage"), ("HUGINN_ENDPOINT", &format!("rudp://{}", live.addr))], + &["query", "{}"], + None, + ); + assert_eq!(foreign.code, 1); + assert!(foreign.out.starts_with("Refused "), "{}", foreign.out); +} + +#[test] +fn a_call_that_is_wrong_exits_two_without_sending() { + let (server, count) = counting(HuginnMindResponse::View(None), "view"); + for args in [ + vec!["view", "eureka-state:nonsense:x"], + vec!["view", "no-kind-segment"], + vec!["history", "eureka-state:nonsense:x"], + vec!["query", "{ not json"], + vec!["query", "[]"], + vec!["admit", "--faculty", "Nope", "--agent", "a", "--session", "s", "x.json"], + vec!["schema", "no-such-kind"], + vec!["bogus"], + vec!["view"], + vec![], + ] { + let ran = at(server.addr, &args, None); + assert_eq!(ran.code, 2, "{args:?}"); + assert!(ran.err.starts_with("InvalidInput: "), "{args:?}: {}", ran.err); + assert_eq!(ran.out, "", "{args:?}"); + } + assert_eq!(*count.lock().unwrap(), 0); +} + +#[test] +fn the_recipes_send_exactly_the_pages_selections() { + let schema = |kind: &str| format!("epiphany.pipeline.{kind}.v2"); + let root = |values: &[&str]| json!({ "index": "root", "op": "any_of", "values": values }); + let in_force = json!({ "index": "in_force", "op": "any_of", "values": ["true"] }); + let c = "eureka-substrate"; + + let cases = [ + (vec!["campaigns"], json!({ "schemas": [schema("campaign")] })), + ( + vec!["target", c], + json!({ "schemas": [schema("target")], "fields": [root(&[c]), in_force], "projection": "document" }), + ), + ( + vec!["rulings", c, "eureka-body"], + json!({ "schemas": [schema("ruling")], "fields": [root(&[c, "eureka-body"]), in_force] }), + ), + ( + vec!["open", c], + json!({ "schemas": [schema("question"), schema("follow_up")], "fields": [root(&[c]), in_force] }), + ), + ( + vec!["findings", c], + json!({ + "schemas": [schema("finding")], + "fields": [root(&[c]), in_force, { "index": "faculty", "op": "any_of", "values": ["Soul"] }], + }), + ), + ( + vec!["findings", c, "--blocking"], + json!({ + "schemas": [schema("finding")], + "fields": [ + root(&[c]), + in_force, + { "index": "faculty", "op": "any_of", "values": ["Soul"] }, + { "index": "severity", "op": "any_of", "values": ["Blocker", "High"] }, + ], + }), + ), + ( + vec!["unreported", c], + json!({ + "schemas": [schema("cut_spec")], + "fields": [root(&[c]), in_force], + "cited": { "role": "cut_spec", "exists": false }, + }), + ), + ( + vec!["blocked", "eureka-substrate:cut_spec:cut-x.r1"], + json!({ + "schemas": [schema("question")], + "fields": [in_force], + "cites": { + "target": { "schemaId": schema("cut_spec"), "recordKey": "eureka-substrate:cut_spec:cut-x.r1" }, + "role": "raised_in", + }, + }), + ), + ( + vec!["unjudged", c], + json!({ + "schemas": [schema("cut_report")], + "fields": [root(&[c])], + "cited": { "role": "cut_report", "exists": false }, + }), + ), + ( + vec!["history", "eureka-substrate:ruling:R1"], + json!({ + "schemas": [schema("resolution")], + "cites": { "target": { "schemaId": schema("ruling"), "recordKey": "eureka-substrate:ruling:R1" }, "role": "subject" }, + "descending": true, + }), + ), + ( + vec!["cut", c, "huginn-cli"], + json!({ + "schemas": [schema("cut_spec"), schema("cut_report"), schema("verdict"), schema("finding"), schema("resolution")], + "fields": [root(&[c]), { "index": "cut", "op": "any_of", "values": ["huginn-cli"] }], + }), + ), + ( + vec!["ledger", c], + json!({ "schemas": [schema("cut_spec"), schema("cut_report")], "fields": [root(&[c])], "projection": "document" }), + ), + ( + vec!["precedent", c, "the question in plain words"], + json!({ "schemas": [schema("ruling"), schema("resolution"), schema("finding")], "fields": [root(&[c])] }), + ), + ( + vec!["gaps"], + json!({ "schemas": [schema("follow_up")], "fields": [root(&["eureka-substrate"]), in_force] }), + ), + ]; + for (args, literal) in cases { + let (selection, semantic) = sent(&args); + assert_eq!(selection, page_literal(literal), "{args:?}"); + let expected = (args[0] == "precedent").then(|| ("the question in plain words".to_string(), 10)); + assert_eq!(semantic, expected, "{args:?}"); + } +} + +#[test] +fn paging_and_query_flags_shape_the_selection() { + let (selection, semantic) = sent(&["gaps", "--cursor", "abc", "--documents"]); + assert_eq!(selection.cursor.as_deref(), Some("abc")); + assert_eq!(selection.projection, "document"); + assert_eq!(selection.limit, Some(50)); + assert_eq!(semantic, None); + + let (selection, _) = sent(&["gaps"]); + assert_eq!(selection.cursor, None); + assert_eq!(selection.projection, "header"); + + let (selection, semantic) = sent(&["query", "{}", "--near", "drift", "--top-k", "7"]); + assert_eq!(selection, page_literal(json!({}))); + assert_eq!(semantic, Some(("drift".to_string(), 7))); + let (_, semantic) = sent(&["query", "{}", "--near", "drift"]); + assert_eq!(semantic, Some(("drift".to_string(), 10))); + + let (selection, _) = sent(&["query", r#"{"limit": 5, "descending": true}"#]); + assert_eq!(selection.limit, Some(5)); + assert!(selection.descending); + let (selection, _) = sent(&["query", r#"{"projection": "header"}"#, "--documents"]); + assert_eq!(selection.projection, "document"); + + let ran = at(closed_port(), &["query", "{}", "--top-k", "3"], None); + assert_eq!(ran.code, 2, "--top-k needs --near"); + + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "selection.json", &json!({ "schemas": ["epiphany.pipeline.campaign.v2"] })); + let (selection, _) = sent(&["query", &format!("@{file}")]); + assert_eq!(selection.schemas, Some(vec!["epiphany.pipeline.campaign.v2".to_string()])); + let (server, seen) = recording(); + let ran = at(server.addr, &["query", "-"], Some(r#"{"keys": ["a:campaign:self"]}"#)); + assert_eq!(ran.code, 0, "{}", ran.err); + let seen = seen.lock().unwrap(); + let [HuginnMindRequest::Query { selection, .. }] = &seen[..] else { panic!("{seen:?}") }; + assert_eq!(selection.keys, Some(vec!["a:campaign:self".to_string()])); +} + +#[test] +fn recipes_list_what_the_mind_holds() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let campaign = write(&dir, "campaign.json", &json!([campaign_json()])); + let ran = at(server.addr, &admit_args(&campaign), None); + assert_eq!(ran.code, 0, "{}", ran.err); + let specs = write(&dir, "specs.json", &json!([spec("A"), spec("B")])); + let ran = at(server.addr, &admit_args(&specs), None); + assert_eq!(ran.code, 0, "{}", ran.err); + + let unreported = at(server.addr, &["unreported", CAMPAIGN], None); + assert_eq!(unreported.code, 0, "{}", unreported.err); + let mut lines: Vec<&str> = unreported.out.lines().collect(); + assert_eq!(lines.pop().unwrap().split(' ').take(2).collect::>(), ["matched", "2"]); + assert_eq!(lines.len(), 2); + + let reports = write(&dir, "report.json", &json!([report("B")])); + let ran = at(server.addr, &admit_args(&reports), None); + assert_eq!(ran.code, 0, "{}", ran.err); + + let unreported = at(server.addr, &["unreported", CAMPAIGN], None); + let lines: Vec<&str> = unreported.out.lines().collect(); + assert_eq!(lines.len(), 2, "{}", unreported.out); + let tokens: Vec<&str> = lines[0].split(' ').collect(); + let id = format!("{CAMPAIGN}:cut_spec:cut-A.r1"); + assert_eq!(tokens[..5], [id.as_str(), "InForce", "Hands", "A", "cut"]); + for fact in ["cut=A", "repo=GameCult/Epiphany", "revision=1", "base=5f98228d", "branch=codex/eureka-pipeline-state"] { + assert!(tokens.contains(&fact), "{fact}: {}", lines[0]); + } + assert!(lines[1].starts_with("matched 1 as_of "), "{}", lines[1]); + assert!(lines[1].ends_with(" next -"), "{}", lines[1]); + assert!(!unreported.out.contains("cut-B.r1"), "{}", unreported.out); + + let unjudged = at(server.addr, &["unjudged", CAMPAIGN], None); + assert!(unjudged.out.contains(&format!("{CAMPAIGN}:cut_report:cut-B.h1")), "{}", unjudged.out); + assert!(unjudged.out.contains("matched 1 "), "{}", unjudged.out); + + let campaigns = at(server.addr, &["campaigns"], None); + assert!(campaigns.out.starts_with(&format!("{CAMPAIGN}:campaign:self InForce Hands Eureka pipeline state repos={REPO}\n")), "{}", campaigns.out); + + let whole = at(server.addr, &["ledger", CAMPAIGN], None); + assert_eq!(whole.code, 0, "{}", whole.err); + assert_eq!(whole.out.matches("admitted ").count(), 3, "{}", whole.out); + assert!(!whole.out.starts_with('\n'), "{}", whole.out); + assert_eq!(whole.out.matches("\n\n").count(), 2, "documents are separated by one blank line: {}", whole.out); + + let documents = at(server.addr, &["campaigns", "--documents"], None); + assert!(documents.out.contains("\nadmitted "), "{}", documents.out); + assert!(documents.out.contains("\"kind\": \"campaign\""), "{}", documents.out); +} + +#[test] +fn a_long_header_is_cut() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let mut doc = campaign_json(); + doc["value"]["title"] = json!("t".repeat(200)); + doc["value"]["working_branch"] = json!("b"); + let file = write(&dir, "long.json", &json!([doc])); + assert_eq!(at(server.addr, &admit_args(&file), None).code, 0); + let ran = at(server.addr, &["campaigns"], None); + let header = ran.out.lines().next().unwrap(); + assert_eq!(header.chars().count(), 240); +} + +#[test] +fn a_resolved_document_shows_its_closing_record() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let question = json!({ + "kind": "question", + "value": { + "campaign": CAMPAIGN, + "label": "Q1", + "title": "Who owns the state?", + "question": "Who owns the state?", + "options": [{ "label": "A", "text": "an instance" }, { "label": "B", "text": "a repo" }], + "recommended": "A", + "depends": [], + "raised_in": null, + "asked_on": "2026-10-10", + }, + }); + let setup = write(&dir, "setup.json", &json!([campaign_json(), question])); + let ran = at(server.addr, &admit_args(&setup), None); + assert_eq!(ran.code, 0, "{}{}", ran.out, ran.err); + let resolution = json!({ + "kind": "resolution", + "value": { + "subject": { "kind": "Question", "id": format!("{CAMPAIGN}:question:Q1") }, + "sequence": 1, + "outcome": { "Withdrawn": { "reason": "moot" } }, + "rationale": "Resolved.", + "resolved_on": "2026-10-10", + }, + }); + let closing = write(&dir, "closing.json", &json!([resolution])); + let ran = at(server.addr, &admit_args(&closing), None); + assert_eq!(ran.code, 0, "{}{}", ran.out, ran.err); + + let id = format!("{CAMPAIGN}:question:Q1"); + let closer = format!("{CAMPAIGN}:resolution:question.Q1.n1"); + let viewed = at(server.addr, &["view", &id], None); + assert_eq!(viewed.out.lines().next().unwrap(), format!("{id} Resolved Withdrawn by {closer}")); + + let history = at(server.addr, &["history", &id], None); + assert_eq!(history.code, 0, "{}", history.err); + assert!(history.out.starts_with(&format!("{closer} InForce Hands ")), "{}", history.out); + assert!(history.out.contains("sequence=1"), "{}", history.out); + + let open = at(server.addr, &["open", CAMPAIGN], None); + assert!(open.out.contains("matched 0 "), "a resolved question is not open: {}", open.out); + + let header = at(server.addr, &["query", r#"{"schemas": ["epiphany.pipeline.question.v2"]}"#], None); + assert!(header.out.starts_with(&format!("{id} Resolved:Withdrawn Hands Who owns the state? ")), "{}", header.out); + assert!(header.out.contains("options=A,B") && header.out.contains("recommended=A"), "{}", header.out); +} + +#[test] +fn schema_prints_the_published_files() { + let manifest = Path::new(env!("CARGO_MANIFEST_DIR")); + for kind in ["cut_spec", "campaign", "hand_off", "run"] { + let ran = run(&[], &["schema", kind], None); + assert_eq!(ran.code, 0); + let published = std::fs::read_to_string(manifest.join(format!("../../schemas/cultnet/epiphany.pipeline.{kind}.v2.schema.json"))).unwrap(); + assert_eq!(ran.out, published, "{kind}"); + } + let selection = run(&[], &["schema", "selection"], None); + assert_eq!(selection.out, std::fs::read_to_string(manifest.join("schemas/cultnet.selection.schema.json")).unwrap()); + let names = run(&[], &["schema"], None); + assert_eq!(names.code, 0); + let names: Vec<&str> = names.out.lines().collect(); + assert_eq!(names.len(), 15, "{names:?}"); + assert_eq!(names[0], "campaign"); + assert_eq!(names[14], "selection"); + for kind in PipelineKind::ALL { + assert!(names.contains(&kind.name()), "{}", kind.name()); + } + let unknown = run(&[], &["schema", "no-such-kind"], None); + assert_eq!(unknown.code, 2); + assert!(unknown.err.starts_with("InvalidInput: "), "{}", unknown.err); +} + +#[test] +fn help_is_the_schema_surface() { + let rulings = run(&[], &["rulings", "--help"], None); + assert_eq!(rulings.code, 0); + let (_, printed) = rulings.out.split_once("selection:\n").expect("the selection is in the help"); + let selection: Value = serde_json::from_str(printed.trim()).unwrap(); + assert_eq!( + selection, + json!({ + "schemas": ["epiphany.pipeline.ruling.v2"], + "fields": [ + { "index": "root", "op": "any_of", "values": [""] }, + { "index": "in_force", "op": "any_of", "values": ["true"] }, + ], + }) + ); + let history = run(&[], &["history", "--help"], None); + assert!(history.out.contains("epiphany.pipeline..v2"), "{}", history.out); + let findings = run(&[], &["findings", "--help"], None); + assert!(findings.out.contains("\"severity\"") && findings.out.contains("Blocker"), "{}", findings.out); + let precedent = run(&[], &["precedent", "--help"], None); + assert!(precedent.out.contains("\"top_k\": 10"), "{}", precedent.out); + let admit = run(&[], &["admit", "--help"], None); + let admit_text = admit.out.split_whitespace().collect::>().join(" "); + assert!(admit_text.contains("{\"kind\": , \"value\": {...}}"), "{admit_text}"); + assert!(admit_text.contains("exit 5"), "{admit_text}"); + + let version = run(&[], &["--version"], None); + assert_eq!(version.code, 0); + let sha = option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown"); + assert_eq!(version.out, format!("huginn {} ({sha})\n", env!("CARGO_PKG_VERSION"))); +} + +#[test] +fn every_recipe_has_help() { + for recipe in [ + "campaigns", "target", "rulings", "open", "findings", "unreported", "blocked", "unjudged", "history", "cut", "ledger", + "precedent", "gaps", + ] { + let ran = run(&[], &[recipe, "--help"], None); + assert_eq!(ran.code, 0, "{recipe}"); + assert!(ran.out.contains("epiphany.pipeline."), "{recipe}: {}", ran.out); + assert!(ran.out.contains("--cursor"), "{recipe}: {}", ran.out); + } +} + +#[test] +fn a_conflicting_batch_is_the_minds_no() { + let conflict = scripted(|message| { + let (_, request) = decode_request(message).expect("a mind request"); + assert!(matches!(request, HuginnMindRequest::Admit(_))); + answer( + "admit", + &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { + identities: vec![PipelineRef { kind: PipelineKind::Campaign, id: Short(format!("{CAMPAIGN}:campaign:self")) }], + }), + ) + }); + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "campaign.json", &json!([campaign_json()])); + let ran = at(conflict.addr, &admit_args(&file), None); + assert_eq!(ran.code, 1); + assert_eq!(ran.out, format!("Conflict\nconflicts {CAMPAIGN}:campaign:self\n")); +} From 6df2a684ef7a0818970aeffb75b9d1f689dcfff7 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 10:20:39 +0200 Subject: [PATCH 10/11] one_persona_per_mind test: a planted row is unreadable on status and door alike Co-Authored-By: Claude Opus 5.5 --- crates/huginn-mind/src/persona.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs index 9f92455..2742120 100644 --- a/crates/huginn-mind/src/persona.rs +++ b/crates/huginn-mind/src/persona.rs @@ -516,12 +516,13 @@ mod tests { // A store written before this type existed opens unchanged. assert!(Mind::open_with(planted(base()), &yggdrasil).is_ok()); - // One persona opens and reads back. + // One persona opens; a planted row has no writing receipt, so the door and the status both call it unreadable. let mut with_one = base(); with_one.push(entry(INSTANCE, persona(INSTANCE, T1))); let mind = Mind::open_with(planted(with_one.clone()), &yggdrasil).unwrap(); assert_eq!(mind.envelopes().len(), 3); - assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Unreadable); + assert!(mind.persona().is_err()); // Two are no mind's. with_one.push(entry("second", persona(INSTANCE, T2))); From 126a914abb9b23d647d89884d10e53f365615517 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 10:58:14 +0200 Subject: [PATCH 11/11] Restore LF line endings in the files my last three commits rewrote as CRLF The repo stores LF; a scripted edit on Windows wrote CRLF. No content change: git diff -w d5fddc3 shows only the three commits' real edits. Co-Authored-By: Claude Opus 5.5 --- crates/eureka-state/Cargo.toml | 100 +- crates/eureka-state/src/bin/huginn/main.rs | 798 ++++---- crates/eureka-state/tests/cli.rs | 2094 ++++++++++---------- crates/huginn-mind/src/persona.rs | 1170 +++++------ crates/huginn-mind/src/wire.rs | 686 +++---- 5 files changed, 2424 insertions(+), 2424 deletions(-) diff --git a/crates/eureka-state/Cargo.toml b/crates/eureka-state/Cargo.toml index 74f1143..986bbf4 100644 --- a/crates/eureka-state/Cargo.toml +++ b/crates/eureka-state/Cargo.toml @@ -1,50 +1,50 @@ -[package] -name = "eureka-state" -version = "0.1.0" -edition.workspace = true -license.workspace = true -publish.workspace = true - -# The client core (`lib.rs`): one call over CultNet to a Huginn daemon. It owns -# the transport and nothing of the mind. The operation envelope, the wire -# vocabulary and the deferred-body bound are `huginn-mind`'s, so the client and -# the daemon cannot spell them differently; the content fetch and its -# verification are `cultnet-rs`'s. -# -# The crate is the client core (`lib.rs`) and its consumers: the `huginn` CLI -# (`src/bin/huginn/`), the shell door every agent uses, and until -# delete-eureka-state-mcp the MCP server (`main.rs`, the `eureka-state` binary). -# Both hold no state. -# `cli` (default) is the `huginn` binary's argument parser; a library consumer -# takes `default-features = false` and compiles none of it. -[features] -default = ["cli"] -cli = ["dep:clap"] - -[[bin]] -name = "huginn" -path = "src/bin/huginn/main.rs" -required-features = ["cli"] - -[[test]] -name = "cli" -required-features = ["cli"] - -[dependencies] -anyhow = "1" -clap = { version = "4", features = ["derive"], optional = true } -cultnet-rs.workspace = true -huginn-mind = { path = "../huginn-mind" } -rmcp = { version = "2.2.0", default-features = false, features = ["server", "macros", "transport-io"] } -rmp-serde = "1" -schemars = "1" -serde = { version = "1", features = ["derive"] } -serde_json = "1" -tokio = { version = "1", features = ["rt", "macros", "io-std"] } - -# Tests run a real daemon in-process against a temporary mind, and the real -# binary against it. -[dev-dependencies] -chrono = "0.4.44" -huginn-daemon = { path = "../huginn-daemon" } -tempfile = "3" +[package] +name = "eureka-state" +version = "0.1.0" +edition.workspace = true +license.workspace = true +publish.workspace = true + +# The client core (`lib.rs`): one call over CultNet to a Huginn daemon. It owns +# the transport and nothing of the mind. The operation envelope, the wire +# vocabulary and the deferred-body bound are `huginn-mind`'s, so the client and +# the daemon cannot spell them differently; the content fetch and its +# verification are `cultnet-rs`'s. +# +# The crate is the client core (`lib.rs`) and its consumers: the `huginn` CLI +# (`src/bin/huginn/`), the shell door every agent uses, and until +# delete-eureka-state-mcp the MCP server (`main.rs`, the `eureka-state` binary). +# Both hold no state. +# `cli` (default) is the `huginn` binary's argument parser; a library consumer +# takes `default-features = false` and compiles none of it. +[features] +default = ["cli"] +cli = ["dep:clap"] + +[[bin]] +name = "huginn" +path = "src/bin/huginn/main.rs" +required-features = ["cli"] + +[[test]] +name = "cli" +required-features = ["cli"] + +[dependencies] +anyhow = "1" +clap = { version = "4", features = ["derive"], optional = true } +cultnet-rs.workspace = true +huginn-mind = { path = "../huginn-mind" } +rmcp = { version = "2.2.0", default-features = false, features = ["server", "macros", "transport-io"] } +rmp-serde = "1" +schemars = "1" +serde = { version = "1", features = ["derive"] } +serde_json = "1" +tokio = { version = "1", features = ["rt", "macros", "io-std"] } + +# Tests run a real daemon in-process against a temporary mind, and the real +# binary against it. +[dev-dependencies] +chrono = "0.4.44" +huginn-daemon = { path = "../huginn-daemon" } +tempfile = "3" diff --git a/crates/eureka-state/src/bin/huginn/main.rs b/crates/eureka-state/src/bin/huginn/main.rs index f3f8f0e..b1d7f7a 100644 --- a/crates/eureka-state/src/bin/huginn/main.rs +++ b/crates/eureka-state/src/bin/huginn/main.rs @@ -1,399 +1,399 @@ -//! `huginn`: the agents' door to Huginn's mind, as shell commands. -//! -//! A caller of `HuginnClient` and nothing else. It owns argument parsing, the -//! strict decode of agent-written JSON into the leaf's types (`door`), the -//! recipe selections (`recipes`), the text rendering (`render`), the exit code -//! and the read-back after an admission. It owns no state, writes no file and -//! reads no configuration but two environment variables: `EUREKA_INSTANCE` -//! names the mind and `HUGINN_ENDPOINT` (`rudp://host:port`) the daemon that -//! holds it. Each call is a new process; there is no retry inside it, the -//! caller's rule retries `Unavailable` once. -//! -//! Answers go to stdout and the exit code says what the answer was: 0 answered, -//! 1 the mind said no (a refusal, a conflict, an absent document). Troubles go -//! to stderr as `: `: 2 the call is wrong, 3 Unavailable, 4 no -//! answer and a retry cannot help, 5 the read-back after a committed admission -//! differs from what was sent. - -mod config; -mod door; -mod recipes; -mod render; -mod schema; -mod trouble; - -use std::io::Write; -use std::process::ExitCode; -use std::sync::OnceLock; - -use clap::{CommandFactory, FromArgMatches, Parser, Subcommand}; -use cultnet_rs::{PROJECTION_DOCUMENT, Selection}; -use huginn_mind::eureka_pipeline::{Line, PipelineDocument, PipelineRef, Short, Slug, pipeline_key}; -use huginn_mind::{ - BATCH_MAX, Faculty, HuginnMindRequest, HuginnMindResponse, MindRefusal, PipelineAdmissionBatch, PipelineAdmissionOutcome, - PipelinePageItems, PipelineProvenance, PipelineSelectionPage, SemanticQuery, -}; -use serde_json::Value; - -use config::{Settings, TOOL}; -use recipes::Recipe; -use trouble::Trouble; - -/// The page size when a selection names none. -const DEFAULT_LIMIT: u32 = 50; -/// The neighbours `--near` asks for when `--top-k` is not given. -const DEFAULT_TOP_K: u32 = 10; - -const ADMIT_HELP: &str = "\ -The file is a JSON array of 1 to 64 documents, each {\"kind\": , \"value\": {...}}, or - for stdin; one document object alone is a batch of one. \ -`huginn schema` lists the kinds and `huginn schema ` prints a value's JSON Schema. \ -Every key the schema does not know is refused (exit 2) with its path; nothing is sent. \ -After Committed or AlreadyAdmitted the batch is read back and compared with what was sent: `read back equal`, or exit 5 with the ids and field paths that differ."; - -#[derive(Parser, Debug)] -#[command(name = "huginn", about = "Huginn's mind: whoami, view, query, recipes, admit, schema", arg_required_else_help = true)] -struct Cli { - #[command(subcommand)] - command: Command, -} - -#[derive(Subcommand, Debug)] -enum Command { - /// Who this process acts for and whether the daemon answers. - Whoami, - /// Read one document by id, with its admission facts and status. - View { - /// The document's id: ::. - id: String, - /// Print only the {kind, value} JSON, which `admit` accepts back. - #[arg(long)] - raw: bool, - }, - /// Query the mind with a CultNet selection. - Query { - /// The selection JSON, @, or - for stdin. - selection: String, - /// Rank by nearness to this text instead of ordering by key. - #[arg(long)] - near: Option, - /// How many neighbours (default 10). - #[arg(long, requires = "near")] - top_k: Option, - /// Print each item as `view` does. - #[arg(long)] - documents: bool, - }, - #[command(flatten)] - Recipe(Recipe), - /// Admit a batch of documents, whole or not at all, and read it back. - #[command(after_help = ADMIT_HELP)] - Admit { - #[arg(long, value_parser = faculty)] - faculty: Faculty, - /// The admitting agent's name. - #[arg(long)] - agent: String, - /// The admitting session. - #[arg(long)] - session: String, - /// The documents file, or - for stdin. - file: String, - }, - /// The JSON Schema of a document kind or of a selection; no name lists them. - Schema { name: Option }, -} - -fn faculty(text: &str) -> Result { - serde_json::from_value(Value::String(text.to_string())).map_err(|error| error.to_string()) -} - -/// The version, then the sha the binary was built from. -fn version() -> &'static str { - static VERSION: OnceLock = OnceLock::new(); - VERSION.get_or_init(|| format!("{} ({})", env!("CARGO_PKG_VERSION"), build_sha())) -} - -fn build_sha() -> &'static str { - option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown") -} - -/// The command line, or the exit code of having answered it (help, version) or -/// refused it (usage, as `InvalidInput`). -fn parse() -> Result { - let mut command = Cli::command().version(version()); - for (name, text) in recipes::help() { - command = command.mut_subcommand(name, |recipe| recipe.after_help(text)); - } - match command.try_get_matches() { - Ok(matches) => Cli::from_arg_matches(&matches).map_err(|error| usage(&error)), - Err(error) => Err(usage(&error)), - } -} - -fn usage(error: &clap::Error) -> u8 { - if error.use_stderr() { - let text = error.to_string(); - eprintln!("InvalidInput: {}", text.trim_start_matches("error: ").trim_end()); - 2 - } else { - let _ = error.print(); - 0 - } -} - -fn main() -> ExitCode { - let cli = match parse() { - Ok(cli) => cli, - Err(code) => return ExitCode::from(code), - }; - match run(&Settings::from_env(), cli.command) { - Ok(code) => ExitCode::from(code), - Err(trouble) => { - eprintln!("{trouble}"); - ExitCode::from(trouble.exit()) - } - } -} - -fn say(text: impl std::fmt::Display) { - let _ = writeln!(std::io::stdout(), "{text}"); -} - -fn run(settings: &Settings, command: Command) -> Result { - match command { - Command::Whoami => whoami(settings), - Command::View { id, raw } => view(settings, &id, raw), - Command::Query { selection, near, top_k, documents } => { - let selection = door::selection(&door::argument(&selection)?)?; - let semantic = near.map(|text| SemanticQuery { text: Line(text), top_k: top_k.unwrap_or(DEFAULT_TOP_K) }); - query(settings, selection, semantic, None, documents) - } - Command::Recipe(recipe) => { - let ask = recipe.ask()?; - query(settings, door::selection_value(&ask.selection)?, ask.semantic, ask.page.cursor, ask.page.documents) - } - Command::Admit { faculty, agent, session, file } => admit(settings, faculty, agent, session, &file), - Command::Schema { name } => { - let text = schema::text(name.as_deref())?; - let _ = write!(std::io::stdout(), "{text}"); - Ok(0) - } - } -} - -fn whoami(settings: &Settings) -> Result { - say(format_args!("instance {}", settings.instance.as_deref().unwrap_or("unset"))); - say(format_args!("endpoint {}", settings.endpoint.as_deref().unwrap_or("unset"))); - say(format_args!("client {}", build_sha())); - match settings.ask(|_| HuginnMindRequest::Whoami) { - Ok(HuginnMindResponse::Whoami(status)) => { - say("reachable yes"); - say(format_args!( - "documents {} receipts {} index {} epoch {}", - status.documents, - status.receipts, - render::index_state(&status.index), - status.schema_epoch - )); - say(format_args!("persona {}", render::persona_state(&status.persona))); - Ok(0) - } - Ok(other) => { - say("reachable no"); - Err(unexpected(&other)) - } - Err(trouble) => { - say("reachable no"); - Err(trouble) - } - } -} - -fn view(settings: &Settings, id: &str, raw: bool) -> Result { - let reference = PipelineRef { kind: door::kind_of(id)?, id: Short(id.to_string()) }; - match settings.ask(|instance| HuginnMindRequest::View { instance: instance.clone(), id: reference })? { - HuginnMindResponse::View(Some(found)) => { - say(render::view(&found, raw)); - Ok(0) - } - HuginnMindResponse::View(None) => { - say(format_args!("absent {id}")); - Ok(1) - } - HuginnMindResponse::Refused(refusal) => Ok(refused(&refusal)), - other => Err(unexpected(&other)), - } -} - -fn query( - settings: &Settings, - mut selection: Selection, - semantic: Option, - cursor: Option, - documents: bool, -) -> Result { - if documents { - selection.projection = PROJECTION_DOCUMENT.to_string(); - } - if cursor.is_some() { - selection.cursor = cursor; - } - selection.limit.get_or_insert(DEFAULT_LIMIT); - match settings.ask(|instance| HuginnMindRequest::Query { instance: instance.clone(), selection, semantic })? { - HuginnMindResponse::Query(page) => { - show(&page); - Ok(0) - } - HuginnMindResponse::Refused(refusal) => Ok(refused(&refusal)), - other => Err(unexpected(&other)), - } -} - -fn show(page: &PipelineSelectionPage) { - match &page.items { - PipelinePageItems::Headers(headers) => { - for header in headers { - say(render::header(header)); - } - } - PipelinePageItems::Documents(views) => { - for (index, found) in views.iter().enumerate() { - if index > 0 { - say(""); - } - say(render::view(found, false)); - } - } - } - say(format_args!("matched {} as_of {} next {}", page.matched, page.as_of, page.next.as_deref().unwrap_or("-"))); -} - -fn admit(settings: &Settings, faculty: Faculty, agent: String, session: String, file: &str) -> Result { - let documents = door::documents(&door::file_or_stdin(file)?)?; - if documents.is_empty() || documents.len() > BATCH_MAX { - return Err(Trouble::invalid(format!("a batch is 1 to {BATCH_MAX} documents, this one has {}", documents.len()))); - } - let sent = documents.clone(); - let provenance = PipelineProvenance { faculty, agent: Short(agent), session: Short(session), tool: Short(TOOL.to_string()) }; - let request = |instance: &Slug| { - HuginnMindRequest::Admit(PipelineAdmissionBatch { instance: instance.clone(), provenance, documents }) - }; - match settings.ask(request)? { - HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { receipt_id, committed_at, writes }) => { - say(format_args!("Committed {receipt_id} at {committed_at}")); - for write in &writes { - say(format_args!("wrote {}", write.id.0)); - } - read_back(settings, &sent) - } - HuginnMindResponse::Admit(PipelineAdmissionOutcome::AlreadyAdmitted { receipt_id }) => { - say(format_args!("AlreadyAdmitted {receipt_id}")); - read_back(settings, &sent) - } - HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(refusal)) | HuginnMindResponse::Refused(refusal) => { - Ok(refused(&refusal)) - } - HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { identities }) => { - say("Conflict"); - for identity in &identities { - say(format_args!("conflicts {}", identity.id.0)); - } - Ok(1) - } - other => Err(unexpected(&other)), - } -} - -/// The end-to-end check that the mind kept what was sent: one `keys` query, -/// each stored document compared with the one sent. A difference is exit 5, -/// not silence, whatever dropped it (an older leaf, a serde default, skew). -fn read_back(settings: &Settings, sent: &[PipelineDocument]) -> Result { - let keys = sent - .iter() - .map(|document| pipeline_key(document).map_err(|refusal| Trouble::Internal(format!("a committed document has no key: {refusal:?}")))) - .collect::, _>>()?; - let selection = Selection { - keys: Some(keys.clone()), - projection: PROJECTION_DOCUMENT.to_string(), - limit: Some(u32::try_from(keys.len()).unwrap_or(u32::MAX)), - ..Selection::default() - }; - let page = match settings.ask(|instance| HuginnMindRequest::Query { instance: instance.clone(), selection, semantic: None })? { - HuginnMindResponse::Query(page) => page, - HuginnMindResponse::Refused(refusal) => return Ok(refused(&refusal)), - other => return Err(unexpected(&other)), - }; - let PipelinePageItems::Documents(stored) = page.items else { - return Err(Trouble::Internal("the read-back answered headers, not documents".to_string())); - }; - let mut differing = Vec::new(); - for (key, document) in keys.iter().zip(sent) { - let held = stored.iter().find(|found| &found.id.id.0 == key); - match held { - None => differing.push(format!("{key}: missing from the read-back")), - Some(found) if found.document == *document => {} - Some(found) => { - let (mut paths, sent_value, held_value) = (Vec::new(), to_value(document), to_value(&found.document)); - differences(&sent_value, &held_value, "", &mut paths); - let shown = if paths.is_empty() { "the document".to_string() } else { paths.join(", ") }; - differing.push(format!("{key}: {shown}")); - } - } - } - if differing.is_empty() { - say(format_args!("read back {} equal", sent.len())); - Ok(0) - } else { - Err(Trouble::ReadBackDiffers(format!( - "{}; the batch is committed, so supersede the documents that differ", - differing.join("; ") - ))) - } -} - -fn to_value(document: &PipelineDocument) -> Value { - serde_json::to_value(document).unwrap_or(Value::Null) -} - -/// The field paths at which two documents differ, including a field only one -/// of them carries. -fn differences(sent: &Value, held: &Value, path: &str, out: &mut Vec) { - match (sent, held) { - (Value::Object(sent), Value::Object(held)) => { - for key in sent.keys().chain(held.keys().filter(|key| !sent.contains_key(*key))) { - let here = if path.is_empty() { key.clone() } else { format!("{path}.{key}") }; - match (sent.get(key), held.get(key)) { - (Some(sent), Some(held)) => differences(sent, held, &here, out), - _ => out.push(here), - } - } - } - (Value::Array(sent), Value::Array(held)) if sent.len() == held.len() => { - for (index, (sent, held)) in sent.iter().zip(held).enumerate() { - differences(sent, held, &format!("{path}[{index}]"), out); - } - } - _ if sent == held => {} - _ => out.push(path.to_string()), - } -} - -/// A refusal is the mind's answer: stdout, exit 1. -fn refused(refusal: &MindRefusal) -> u8 { - say(format_args!("Refused {refusal:?}")); - 1 -} - -fn unexpected(answer: &HuginnMindResponse) -> Trouble { - let name = match answer { - HuginnMindResponse::Whoami(_) => "whoami", - HuginnMindResponse::Admit(_) => "admit", - HuginnMindResponse::View(_) => "view", - HuginnMindResponse::Query(_) => "query", - HuginnMindResponse::Persona(_) => "a persona", - HuginnMindResponse::PersonaPut(_) => "a persona put", - HuginnMindResponse::Refused(_) => "a refusal", - HuginnMindResponse::Deferred(_) => "a deferral", - }; - Trouble::Internal(format!("the daemon answered with {name}, which this call did not ask for")) -} +//! `huginn`: the agents' door to Huginn's mind, as shell commands. +//! +//! A caller of `HuginnClient` and nothing else. It owns argument parsing, the +//! strict decode of agent-written JSON into the leaf's types (`door`), the +//! recipe selections (`recipes`), the text rendering (`render`), the exit code +//! and the read-back after an admission. It owns no state, writes no file and +//! reads no configuration but two environment variables: `EUREKA_INSTANCE` +//! names the mind and `HUGINN_ENDPOINT` (`rudp://host:port`) the daemon that +//! holds it. Each call is a new process; there is no retry inside it, the +//! caller's rule retries `Unavailable` once. +//! +//! Answers go to stdout and the exit code says what the answer was: 0 answered, +//! 1 the mind said no (a refusal, a conflict, an absent document). Troubles go +//! to stderr as `: `: 2 the call is wrong, 3 Unavailable, 4 no +//! answer and a retry cannot help, 5 the read-back after a committed admission +//! differs from what was sent. + +mod config; +mod door; +mod recipes; +mod render; +mod schema; +mod trouble; + +use std::io::Write; +use std::process::ExitCode; +use std::sync::OnceLock; + +use clap::{CommandFactory, FromArgMatches, Parser, Subcommand}; +use cultnet_rs::{PROJECTION_DOCUMENT, Selection}; +use huginn_mind::eureka_pipeline::{Line, PipelineDocument, PipelineRef, Short, Slug, pipeline_key}; +use huginn_mind::{ + BATCH_MAX, Faculty, HuginnMindRequest, HuginnMindResponse, MindRefusal, PipelineAdmissionBatch, PipelineAdmissionOutcome, + PipelinePageItems, PipelineProvenance, PipelineSelectionPage, SemanticQuery, +}; +use serde_json::Value; + +use config::{Settings, TOOL}; +use recipes::Recipe; +use trouble::Trouble; + +/// The page size when a selection names none. +const DEFAULT_LIMIT: u32 = 50; +/// The neighbours `--near` asks for when `--top-k` is not given. +const DEFAULT_TOP_K: u32 = 10; + +const ADMIT_HELP: &str = "\ +The file is a JSON array of 1 to 64 documents, each {\"kind\": , \"value\": {...}}, or - for stdin; one document object alone is a batch of one. \ +`huginn schema` lists the kinds and `huginn schema ` prints a value's JSON Schema. \ +Every key the schema does not know is refused (exit 2) with its path; nothing is sent. \ +After Committed or AlreadyAdmitted the batch is read back and compared with what was sent: `read back equal`, or exit 5 with the ids and field paths that differ."; + +#[derive(Parser, Debug)] +#[command(name = "huginn", about = "Huginn's mind: whoami, view, query, recipes, admit, schema", arg_required_else_help = true)] +struct Cli { + #[command(subcommand)] + command: Command, +} + +#[derive(Subcommand, Debug)] +enum Command { + /// Who this process acts for and whether the daemon answers. + Whoami, + /// Read one document by id, with its admission facts and status. + View { + /// The document's id: ::. + id: String, + /// Print only the {kind, value} JSON, which `admit` accepts back. + #[arg(long)] + raw: bool, + }, + /// Query the mind with a CultNet selection. + Query { + /// The selection JSON, @, or - for stdin. + selection: String, + /// Rank by nearness to this text instead of ordering by key. + #[arg(long)] + near: Option, + /// How many neighbours (default 10). + #[arg(long, requires = "near")] + top_k: Option, + /// Print each item as `view` does. + #[arg(long)] + documents: bool, + }, + #[command(flatten)] + Recipe(Recipe), + /// Admit a batch of documents, whole or not at all, and read it back. + #[command(after_help = ADMIT_HELP)] + Admit { + #[arg(long, value_parser = faculty)] + faculty: Faculty, + /// The admitting agent's name. + #[arg(long)] + agent: String, + /// The admitting session. + #[arg(long)] + session: String, + /// The documents file, or - for stdin. + file: String, + }, + /// The JSON Schema of a document kind or of a selection; no name lists them. + Schema { name: Option }, +} + +fn faculty(text: &str) -> Result { + serde_json::from_value(Value::String(text.to_string())).map_err(|error| error.to_string()) +} + +/// The version, then the sha the binary was built from. +fn version() -> &'static str { + static VERSION: OnceLock = OnceLock::new(); + VERSION.get_or_init(|| format!("{} ({})", env!("CARGO_PKG_VERSION"), build_sha())) +} + +fn build_sha() -> &'static str { + option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown") +} + +/// The command line, or the exit code of having answered it (help, version) or +/// refused it (usage, as `InvalidInput`). +fn parse() -> Result { + let mut command = Cli::command().version(version()); + for (name, text) in recipes::help() { + command = command.mut_subcommand(name, |recipe| recipe.after_help(text)); + } + match command.try_get_matches() { + Ok(matches) => Cli::from_arg_matches(&matches).map_err(|error| usage(&error)), + Err(error) => Err(usage(&error)), + } +} + +fn usage(error: &clap::Error) -> u8 { + if error.use_stderr() { + let text = error.to_string(); + eprintln!("InvalidInput: {}", text.trim_start_matches("error: ").trim_end()); + 2 + } else { + let _ = error.print(); + 0 + } +} + +fn main() -> ExitCode { + let cli = match parse() { + Ok(cli) => cli, + Err(code) => return ExitCode::from(code), + }; + match run(&Settings::from_env(), cli.command) { + Ok(code) => ExitCode::from(code), + Err(trouble) => { + eprintln!("{trouble}"); + ExitCode::from(trouble.exit()) + } + } +} + +fn say(text: impl std::fmt::Display) { + let _ = writeln!(std::io::stdout(), "{text}"); +} + +fn run(settings: &Settings, command: Command) -> Result { + match command { + Command::Whoami => whoami(settings), + Command::View { id, raw } => view(settings, &id, raw), + Command::Query { selection, near, top_k, documents } => { + let selection = door::selection(&door::argument(&selection)?)?; + let semantic = near.map(|text| SemanticQuery { text: Line(text), top_k: top_k.unwrap_or(DEFAULT_TOP_K) }); + query(settings, selection, semantic, None, documents) + } + Command::Recipe(recipe) => { + let ask = recipe.ask()?; + query(settings, door::selection_value(&ask.selection)?, ask.semantic, ask.page.cursor, ask.page.documents) + } + Command::Admit { faculty, agent, session, file } => admit(settings, faculty, agent, session, &file), + Command::Schema { name } => { + let text = schema::text(name.as_deref())?; + let _ = write!(std::io::stdout(), "{text}"); + Ok(0) + } + } +} + +fn whoami(settings: &Settings) -> Result { + say(format_args!("instance {}", settings.instance.as_deref().unwrap_or("unset"))); + say(format_args!("endpoint {}", settings.endpoint.as_deref().unwrap_or("unset"))); + say(format_args!("client {}", build_sha())); + match settings.ask(|_| HuginnMindRequest::Whoami) { + Ok(HuginnMindResponse::Whoami(status)) => { + say("reachable yes"); + say(format_args!( + "documents {} receipts {} index {} epoch {}", + status.documents, + status.receipts, + render::index_state(&status.index), + status.schema_epoch + )); + say(format_args!("persona {}", render::persona_state(&status.persona))); + Ok(0) + } + Ok(other) => { + say("reachable no"); + Err(unexpected(&other)) + } + Err(trouble) => { + say("reachable no"); + Err(trouble) + } + } +} + +fn view(settings: &Settings, id: &str, raw: bool) -> Result { + let reference = PipelineRef { kind: door::kind_of(id)?, id: Short(id.to_string()) }; + match settings.ask(|instance| HuginnMindRequest::View { instance: instance.clone(), id: reference })? { + HuginnMindResponse::View(Some(found)) => { + say(render::view(&found, raw)); + Ok(0) + } + HuginnMindResponse::View(None) => { + say(format_args!("absent {id}")); + Ok(1) + } + HuginnMindResponse::Refused(refusal) => Ok(refused(&refusal)), + other => Err(unexpected(&other)), + } +} + +fn query( + settings: &Settings, + mut selection: Selection, + semantic: Option, + cursor: Option, + documents: bool, +) -> Result { + if documents { + selection.projection = PROJECTION_DOCUMENT.to_string(); + } + if cursor.is_some() { + selection.cursor = cursor; + } + selection.limit.get_or_insert(DEFAULT_LIMIT); + match settings.ask(|instance| HuginnMindRequest::Query { instance: instance.clone(), selection, semantic })? { + HuginnMindResponse::Query(page) => { + show(&page); + Ok(0) + } + HuginnMindResponse::Refused(refusal) => Ok(refused(&refusal)), + other => Err(unexpected(&other)), + } +} + +fn show(page: &PipelineSelectionPage) { + match &page.items { + PipelinePageItems::Headers(headers) => { + for header in headers { + say(render::header(header)); + } + } + PipelinePageItems::Documents(views) => { + for (index, found) in views.iter().enumerate() { + if index > 0 { + say(""); + } + say(render::view(found, false)); + } + } + } + say(format_args!("matched {} as_of {} next {}", page.matched, page.as_of, page.next.as_deref().unwrap_or("-"))); +} + +fn admit(settings: &Settings, faculty: Faculty, agent: String, session: String, file: &str) -> Result { + let documents = door::documents(&door::file_or_stdin(file)?)?; + if documents.is_empty() || documents.len() > BATCH_MAX { + return Err(Trouble::invalid(format!("a batch is 1 to {BATCH_MAX} documents, this one has {}", documents.len()))); + } + let sent = documents.clone(); + let provenance = PipelineProvenance { faculty, agent: Short(agent), session: Short(session), tool: Short(TOOL.to_string()) }; + let request = |instance: &Slug| { + HuginnMindRequest::Admit(PipelineAdmissionBatch { instance: instance.clone(), provenance, documents }) + }; + match settings.ask(request)? { + HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { receipt_id, committed_at, writes }) => { + say(format_args!("Committed {receipt_id} at {committed_at}")); + for write in &writes { + say(format_args!("wrote {}", write.id.0)); + } + read_back(settings, &sent) + } + HuginnMindResponse::Admit(PipelineAdmissionOutcome::AlreadyAdmitted { receipt_id }) => { + say(format_args!("AlreadyAdmitted {receipt_id}")); + read_back(settings, &sent) + } + HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(refusal)) | HuginnMindResponse::Refused(refusal) => { + Ok(refused(&refusal)) + } + HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { identities }) => { + say("Conflict"); + for identity in &identities { + say(format_args!("conflicts {}", identity.id.0)); + } + Ok(1) + } + other => Err(unexpected(&other)), + } +} + +/// The end-to-end check that the mind kept what was sent: one `keys` query, +/// each stored document compared with the one sent. A difference is exit 5, +/// not silence, whatever dropped it (an older leaf, a serde default, skew). +fn read_back(settings: &Settings, sent: &[PipelineDocument]) -> Result { + let keys = sent + .iter() + .map(|document| pipeline_key(document).map_err(|refusal| Trouble::Internal(format!("a committed document has no key: {refusal:?}")))) + .collect::, _>>()?; + let selection = Selection { + keys: Some(keys.clone()), + projection: PROJECTION_DOCUMENT.to_string(), + limit: Some(u32::try_from(keys.len()).unwrap_or(u32::MAX)), + ..Selection::default() + }; + let page = match settings.ask(|instance| HuginnMindRequest::Query { instance: instance.clone(), selection, semantic: None })? { + HuginnMindResponse::Query(page) => page, + HuginnMindResponse::Refused(refusal) => return Ok(refused(&refusal)), + other => return Err(unexpected(&other)), + }; + let PipelinePageItems::Documents(stored) = page.items else { + return Err(Trouble::Internal("the read-back answered headers, not documents".to_string())); + }; + let mut differing = Vec::new(); + for (key, document) in keys.iter().zip(sent) { + let held = stored.iter().find(|found| &found.id.id.0 == key); + match held { + None => differing.push(format!("{key}: missing from the read-back")), + Some(found) if found.document == *document => {} + Some(found) => { + let (mut paths, sent_value, held_value) = (Vec::new(), to_value(document), to_value(&found.document)); + differences(&sent_value, &held_value, "", &mut paths); + let shown = if paths.is_empty() { "the document".to_string() } else { paths.join(", ") }; + differing.push(format!("{key}: {shown}")); + } + } + } + if differing.is_empty() { + say(format_args!("read back {} equal", sent.len())); + Ok(0) + } else { + Err(Trouble::ReadBackDiffers(format!( + "{}; the batch is committed, so supersede the documents that differ", + differing.join("; ") + ))) + } +} + +fn to_value(document: &PipelineDocument) -> Value { + serde_json::to_value(document).unwrap_or(Value::Null) +} + +/// The field paths at which two documents differ, including a field only one +/// of them carries. +fn differences(sent: &Value, held: &Value, path: &str, out: &mut Vec) { + match (sent, held) { + (Value::Object(sent), Value::Object(held)) => { + for key in sent.keys().chain(held.keys().filter(|key| !sent.contains_key(*key))) { + let here = if path.is_empty() { key.clone() } else { format!("{path}.{key}") }; + match (sent.get(key), held.get(key)) { + (Some(sent), Some(held)) => differences(sent, held, &here, out), + _ => out.push(here), + } + } + } + (Value::Array(sent), Value::Array(held)) if sent.len() == held.len() => { + for (index, (sent, held)) in sent.iter().zip(held).enumerate() { + differences(sent, held, &format!("{path}[{index}]"), out); + } + } + _ if sent == held => {} + _ => out.push(path.to_string()), + } +} + +/// A refusal is the mind's answer: stdout, exit 1. +fn refused(refusal: &MindRefusal) -> u8 { + say(format_args!("Refused {refusal:?}")); + 1 +} + +fn unexpected(answer: &HuginnMindResponse) -> Trouble { + let name = match answer { + HuginnMindResponse::Whoami(_) => "whoami", + HuginnMindResponse::Admit(_) => "admit", + HuginnMindResponse::View(_) => "view", + HuginnMindResponse::Query(_) => "query", + HuginnMindResponse::Persona(_) => "a persona", + HuginnMindResponse::PersonaPut(_) => "a persona put", + HuginnMindResponse::Refused(_) => "a refusal", + HuginnMindResponse::Deferred(_) => "a deferral", + }; + Trouble::Internal(format!("the daemon answered with {name}, which this call did not ask for")) +} diff --git a/crates/eureka-state/tests/cli.rs b/crates/eureka-state/tests/cli.rs index 24385dc..6dc606e 100644 --- a/crates/eureka-state/tests/cli.rs +++ b/crates/eureka-state/tests/cli.rs @@ -1,1047 +1,1047 @@ -//! The `huginn` binary as an agent drives it: a real process, its stdout, its -//! stderr and its exit code, against a real daemon in-process or a scripted -//! server where the daemon cannot be made to misbehave. - -use std::io::Write; -use std::net::{SocketAddr, UdpSocket}; -use std::path::Path; -use std::process::{Command, Stdio}; -use std::sync::{Arc, Mutex}; - -use cultnet_rs::Selection; -use huginn_mind::envelope::{OperationFailure, decode_request, encode_failure, encode_response}; -use huginn_mind::eureka_pipeline::{ - CodeLocation, CommitRange, CutVerification, Date, Evidence, EvidenceKind, MutationRecord, OrgRepo, PipelineCutReport, - PipelineCutSpec, PipelineDocument, PipelineKind, PipelineRef, PipelineRuling, Promise, ReportCommit, RulingAuthority, Short, - StructuralDelta, pipeline_key, -}; -use huginn_mind::{ - AdmissionFacts, HuginnMindRequest, HuginnMindResponse, IndexStatus, MindRefusal, MindStatus, PersonaStatus, PipelineAdmissionOutcome, PipelineDocumentView, - PipelinePageItems, PipelineProvenance, PipelineSelectionPage, PipelineStatus, -}; -use serde_json::{Value, json}; -use tempfile::TempDir; - -mod common; -use common::*; - -struct Run { - code: i32, - out: String, - err: String, -} - -fn run(env: &[(&str, &str)], args: &[&str], stdin: Option<&str>) -> Run { - let mut command = Command::new(env!("CARGO_BIN_EXE_huginn")); - command - .env_remove("EUREKA_INSTANCE") - .env_remove("HUGINN_ENDPOINT") - .envs(env.iter().copied()) - .args(args) - .stdin(if stdin.is_some() { Stdio::piped() } else { Stdio::null() }) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()); - let mut child = command.spawn().expect("the binary starts"); - if let Some(text) = stdin { - child.stdin.take().unwrap().write_all(text.as_bytes()).unwrap(); - } - let output = child.wait_with_output().unwrap(); - Run { - code: output.status.code().expect("exited, not killed"), - out: String::from_utf8(output.stdout).unwrap(), - err: String::from_utf8(output.stderr).unwrap(), - } -} - -/// Configured for the test instance against a daemon at `addr`. -fn at(addr: SocketAddr, args: &[&str], stdin: Option<&str>) -> Run { - run(&[("EUREKA_INSTANCE", INSTANCE), ("HUGINN_ENDPOINT", &format!("rudp://{addr}"))], args, stdin) -} - -/// A loopback UDP port nothing listens on. -fn closed_port() -> SocketAddr { - UdpSocket::bind("127.0.0.1:0").unwrap().local_addr().unwrap() -} - -fn write(dir: &TempDir, name: &str, value: &Value) -> String { - let path = dir.path().join(name); - std::fs::write(&path, value.to_string()).unwrap(); - path.to_str().unwrap().to_string() -} - -fn campaign_json() -> Value { - serde_json::to_value(campaign()).unwrap() -} - -fn live() -> Server { - let (root, daemon) = mind(vec![vec![stewardship()]]); - serve(root, daemon) -} - -fn admit_args(file: &str) -> Vec<&str> { - vec!["admit", "--faculty", "Hands", "--agent", "claude", "--session", "session-7", file] -} - -fn delta() -> StructuralDelta { - StructuralDelta { - lines_added: 0, - lines_removed: 0, - dependencies_added: vec![], - dependencies_removed: vec![], - formats_added: vec![], - formats_removed: vec![], - targets_added: vec![], - targets_removed: vec![], - } -} - -fn spec(cut: &str) -> Value { - serde_json::to_value(PipelineDocument::CutSpec(PipelineCutSpec { - campaign: slug(CAMPAIGN), - cut: cut.into(), - revision: 1, - title: "A cut".into(), - repo: OrgRepo(REPO.into()), - branch: "codex/eureka-pipeline-state".into(), - base: sha(), - depends_on: vec![], - first: vec![], - deletes: vec![], - keeps_moves: vec![], - adds: vec![], - file_changes: vec![], - reads: vec![], - authority_map: None, - verification: CutVerification { builds: vec![], tests: vec![], negative: vec![], operator: vec![] }, - estimate: delta(), - rulings: vec![], - questions: vec![], - })) - .unwrap() -} - -fn report(cut: &str) -> Value { - serde_json::to_value(PipelineDocument::CutReport(PipelineCutReport { - campaign: slug(CAMPAIGN), - cut_spec: Short(format!("{CAMPAIGN}:cut_spec:cut-{cut}.r1")), - attempt: 1, - repo: OrgRepo(REPO.into()), - branch: "codex/eureka-pipeline-state".into(), - commits: vec![ReportCommit { sha: sha(), subject: "Land the cut".into(), builds: true }], - range: CommitRange { base: sha(), head: sha() }, - verification: vec![Evidence { kind: EvidenceKind::Test, locator: "cargo test".into(), result: "ok".into() }], - mutations: vec![MutationRecord { - label: "M1".into(), - rule: "the rule".into(), - location: CodeLocation { path: Short("crates/x.rs".into()), line: 1, end_line: None, symbol: None }, - before: "before".into(), - after: "after".into(), - commit: sha(), - failed_as_expected: true, - }], - deviations: vec![], - forks: vec![], - structural_delta: delta(), - landed_names: vec![], - undone: vec![], - promises: vec![Promise { label: "P1".into(), text: "One derived key per document.".into() }], - })) - .unwrap() -} - -fn ruling(quote: Option<&str>) -> PipelineDocument { - PipelineDocument::Ruling(PipelineRuling { - campaign: slug(CAMPAIGN), - label: "R1".into(), - title: "An instance owns its mind".into(), - answers: None, - choice: None, - ruling: "An instance owns its mind.".into(), - operator_quote: quote.map(Into::into), - ruled_on: Date("2026-10-10".into()), - precedents: vec![], - authority: RulingAuthority::Standing, - }) -} - -fn empty_page() -> PipelineSelectionPage { - PipelineSelectionPage { matched: 0, as_of: 1, next: None, items: PipelinePageItems::Headers(vec![]), edges: None } -} - -fn answer(operation: &str, response: &HuginnMindResponse) -> cultnet_rs::CultNetMessage { - encode_response("eureka-state-call", operation, response, "scripted").unwrap() -} - -/// A scripted server that records every request it is sent and answers a -/// query with an empty page. -fn recording() -> (Server, Arc>>) { - let seen = Arc::new(Mutex::new(Vec::new())); - let sink = Arc::clone(&seen); - let server = scripted(move |message| { - let (_, request) = decode_request(message).expect("a mind request"); - sink.lock().unwrap().push(request); - answer("query", &HuginnMindResponse::Query(empty_page())) - }); - (server, seen) -} - -/// The selection a command sent, and its semantic part. -fn sent(args: &[&str]) -> (Selection, Option<(String, u32)>) { - let (server, seen) = recording(); - let ran = at(server.addr, args, None); - assert_eq!(ran.code, 0, "{args:?}: {}", ran.err); - assert!(ran.out.contains("matched 0 as_of 1 next -"), "{}", ran.out); - let seen = seen.lock().unwrap(); - let [HuginnMindRequest::Query { instance, selection, semantic }] = &seen[..] else { - panic!("one query expected: {seen:?}"); - }; - assert_eq!(instance.0, INSTANCE); - (selection.clone(), semantic.as_ref().map(|asked| (asked.text.0.clone(), asked.top_k))) -} - -/// The page's literal as the selection it spells, with the CLI's default page. -fn page_literal(literal: Value) -> Selection { - let mut selection: Selection = serde_json::from_value(literal).unwrap(); - selection.limit = Some(50); - selection -} - -fn counting(replies: HuginnMindResponse, operation: &'static str) -> (Server, Arc>) { - let count = Arc::new(Mutex::new(0)); - let counter = Arc::clone(&count); - let server = scripted(move |_| { - *counter.lock().unwrap() += 1; - answer(operation, &replies) - }); - (server, count) -} - -#[test] -fn without_configuration_whoami_reports_it_and_every_other_command_refuses() { - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "campaign.json", &json!([campaign_json()])); - - let whoami = run(&[], &["whoami"], None); - assert_eq!(whoami.code, 2); - assert!(whoami.out.contains("instance unset\nendpoint unset\nclient "), "{}", whoami.out); - assert!(whoami.out.contains("reachable no"), "{}", whoami.out); - assert!(whoami.err.starts_with("Misconfigured: EUREKA_INSTANCE is not set"), "{}", whoami.err); - - for args in [ - vec!["view", "eureka-state:campaign:self"], - vec!["query", "{}"], - vec!["rulings", "eureka-state"], - admit_args(&file), - ] { - let ran = run(&[], &args, None); - assert_eq!(ran.code, 2, "{args:?}"); - assert!(ran.err.starts_with("Misconfigured:"), "{args:?}: {}", ran.err); - assert_eq!(ran.out, "", "{args:?}"); - } -} - -#[test] -fn a_bad_environment_is_misconfigured_with_its_own_reason() { - let cases: [(&[(&str, &str)], &str); 4] = [ - (&[("HUGINN_ENDPOINT", "rudp://127.0.0.1:1")], "EUREKA_INSTANCE is not set"), - (&[("EUREKA_INSTANCE", "Not A Slug"), ("HUGINN_ENDPOINT", "rudp://127.0.0.1:1")], "EUREKA_INSTANCE is not a valid"), - (&[("EUREKA_INSTANCE", "eureka")], "HUGINN_ENDPOINT is not set"), - (&[("EUREKA_INSTANCE", "eureka"), ("HUGINN_ENDPOINT", "127.0.0.1:1")], "HUGINN_ENDPOINT is not rudp://"), - ]; - for (env, expected) in cases { - let ran = run(env, &["whoami"], None); - assert_eq!(ran.code, 2, "{expected}"); - assert!(ran.err.starts_with("Misconfigured: "), "{}", ran.err); - assert!(ran.err.contains(expected), "{expected}: {}", ran.err); - } - let named = run(&[("EUREKA_INSTANCE", "eureka"), ("HUGINN_ENDPOINT", "rudp://not-an-address")], &["whoami"], None); - assert_eq!(named.code, 2); - assert!(named.out.contains("endpoint rudp://not-an-address"), "{}", named.out); - assert!(named.out.contains("instance eureka"), "{}", named.out); -} - -#[test] -fn whoami_reads_the_live_mind() { - let server = live(); - let ran = at(server.addr, &["whoami"], None); - assert_eq!(ran.code, 0, "{}", ran.err); - let lines: Vec<&str> = ran.out.lines().collect(); - assert_eq!(lines[0], format!("instance {INSTANCE}")); - assert_eq!(lines[1], format!("endpoint rudp://{}", server.addr)); - assert_eq!(lines[2], format!("client {}", option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown"))); - assert_eq!(lines[3], "reachable yes"); - assert_eq!(lines[4], "documents 2 receipts 2 index Current epoch epiphany.pipeline.epoch.v2"); - assert_eq!(lines[5], "persona absent"); - assert_eq!(lines.len(), 6); - assert_eq!(ran.err, ""); -} - -#[test] -fn an_index_that_is_behind_shows_its_count() { - let status = MindStatus { - instance: slug(INSTANCE), - schema_epoch: "epoch".into(), - documents: 7, - receipts: 9, - index: IndexStatus::Behind { pending: 3 }, - persona: PersonaStatus::Absent, - }; - let (server, _) = counting(HuginnMindResponse::Whoami(status), "whoami"); - let ran = at(server.addr, &["whoami"], None); - assert_eq!(ran.code, 0); - assert!(ran.out.contains("documents 7 receipts 9 index Behind pending=3 epoch epoch"), "{}", ran.out); -} - -#[test] -fn whoami_shows_the_persona_door_state_and_nothing_of_the_document() { - for (persona, line) in [ - (PersonaStatus::Stored { updated_at: "2026-10-10T10:00:00Z".into() }, "persona stored updatedAt=2026-10-10T10:00:00Z"), - (PersonaStatus::Unreadable, "persona unreadable"), - ] { - let status = MindStatus { instance: slug(INSTANCE), schema_epoch: "e".into(), documents: 1, receipts: 1, index: IndexStatus::Current, persona }; - let (server, _) = counting(HuginnMindResponse::Whoami(status), "whoami"); - let ran = at(server.addr, &["whoami"], None); - assert_eq!(ran.code, 0); - assert_eq!(ran.out.lines().last(), Some(line), "{}", ran.out); - } -} - -#[test] -fn admit_round_trips_and_is_idempotent() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "campaign.json", &json!([campaign_json()])); - - let first = at(server.addr, &admit_args(&file), None); - assert_eq!(first.code, 0, "{}", first.err); - let lines: Vec<&str> = first.out.lines().collect(); - assert!(lines[0].starts_with("Committed mind-commit-"), "{}", first.out); - assert!(lines[0].contains(" at "), "{}", first.out); - assert_eq!(lines[1], format!("wrote {CAMPAIGN}:campaign:self")); - assert_eq!(lines[2], "read back 1 equal"); - assert_eq!(lines.len(), 3, "{}", first.out); - - let again = at(server.addr, &admit_args(&file), None); - assert_eq!(again.code, 0, "{}", again.err); - let lines: Vec<&str> = again.out.lines().collect(); - assert!(lines[0].starts_with("AlreadyAdmitted mind-commit-"), "{}", again.out); - assert_eq!(lines[1], "read back 1 equal"); - - let id = format!("{CAMPAIGN}:campaign:self"); - let viewed = at(server.addr, &["view", &id], None); - assert_eq!(viewed.code, 0, "{}", viewed.err); - let lines: Vec<&str> = viewed.out.lines().collect(); - assert_eq!(lines[0], format!("{id} InForce")); - assert!(lines[1].starts_with("admitted "), "{}", viewed.out); - assert!(lines[1].contains(" ordinal 3 Hands/claude session session-7 tool huginn receipt mind-commit-"), "{}", lines[1]); - let shown: Value = serde_json::from_str(&lines[2..].join("\n")).unwrap(); - assert_eq!(shown, campaign_json()); - - let raw = at(server.addr, &["view", &id, "--raw"], None); - assert_eq!(raw.code, 0); - assert_eq!(serde_json::from_str::(&raw.out).unwrap(), campaign_json()); - assert!(raw.out.starts_with('{'), "{}", raw.out); - - let fed_back = at(server.addr, &admit_args("-"), Some(&raw.out)); - assert_eq!(fed_back.code, 0, "{}", fed_back.err); - assert!(fed_back.out.starts_with("AlreadyAdmitted "), "{}", fed_back.out); - - let status = at(server.addr, &["whoami"], None); - assert!(status.out.contains("documents 3 receipts 3"), "{}", status.out); -} - -#[test] -fn unknown_keys_are_refused_by_path_and_never_by_value() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let mut nested = campaign_json(); - nested["value"]["target_doc"]["pathh"] = json!("CANARY-NESTED"); - let mut top = campaign_json(); - top["surplus"] = json!("CANARY-TOP"); - let file = write(&dir, "bad.json", &json!([nested, top])); - - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 2); - assert_eq!(ran.out, ""); - assert!(ran.err.starts_with("InvalidInput: "), "{}", ran.err); - assert!(ran.err.contains("documents[0].value.target_doc.pathh"), "{}", ran.err); - assert!(ran.err.contains("documents[1].surplus"), "{}", ran.err); - assert!(!ran.err.contains("CANARY"), "{}", ran.err); - - let status = at(server.addr, &["whoami"], None); - assert!(status.out.contains("receipts 2 "), "nothing was sent: {}", status.out); - - let selection = at(server.addr, &["query", r#"{"limt": 5}"#], None); - assert_eq!(selection.code, 2); - assert!(selection.err.contains("selection.limt"), "{}", selection.err); -} - -#[test] -fn an_explicitly_empty_unknown_key_is_not_a_loss() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let mut doc = campaign_json(); - doc["value"]["ghost"] = Value::Null; - doc["value"]["ghosts"] = json!([]); - doc["value"]["ghost_map"] = json!({}); - doc["value"]["ghost_text"] = json!(""); - let file = write(&dir, "ghosts.json", &json!([doc])); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 0, "{}", ran.err); - assert!(ran.out.contains("read back 1 equal"), "{}", ran.out); -} - -#[test] -fn a_falsy_unknown_value_is_still_a_loss() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let mut doc = campaign_json(); - doc["value"]["zero"] = json!(0); - doc["value"]["no"] = json!(false); - let file = write(&dir, "falsy.json", &json!([doc])); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 2); - assert!(ran.err.contains("documents[0].value.zero") && ran.err.contains("documents[0].value.no"), "{}", ran.err); -} - -#[test] -fn a_document_that_does_not_decode_is_invalid_input() { - let dir = tempfile::tempdir().unwrap(); - let cases = [ - (json!([{ "kind": "nonsense", "value": {} }]), "documents does not decode"), - (json!("text"), "JSON array"), - (json!([[]]), "documents[0] must be a JSON object"), - (json!([]), "1 to 64"), - (json!((0..65).map(|_| campaign_json()).collect::>()), "1 to 64"), - ]; - for (n, (value, expected)) in cases.into_iter().enumerate() { - let file = write(&dir, &format!("case{n}.json"), &value); - let ran = at(closed_port(), &admit_args(&file), None); - assert_eq!(ran.code, 2, "{expected}: {}", ran.err); - assert!(ran.err.starts_with("InvalidInput: "), "{}", ran.err); - assert!(ran.err.contains(expected), "{expected}: {}", ran.err); - } - let broken = at(closed_port(), &admit_args("-"), Some("{ not json")); - assert_eq!(broken.code, 2); - assert!(broken.err.contains("not JSON"), "{}", broken.err); - let missing = at(closed_port(), &admit_args("/no/such/file.json"), None); - assert_eq!(missing.code, 2); - assert!(missing.err.contains("cannot read /no/such/file.json"), "{}", missing.err); -} - -#[test] -fn a_document_that_does_not_decode_never_echoes_its_values() { - let dir = tempfile::tempdir().unwrap(); - let mut string_for_number = report("canary"); - string_for_number["value"]["attempt"] = json!("CANARY-NUMBER"); - let mut long_string_for_list = campaign_json(); - long_string_for_list["value"]["repos"] = json!(format!("CANARY-LIST{}", "x".repeat(60_000))); - let unknown_kind = json!({ "kind": "CANARY-KIND", "value": {} }); - let mut unknown_variant = serde_json::to_value(ruling(None)).unwrap(); - unknown_variant["value"]["authority"] = json!("CANARY-VARIANT"); - for (n, document) in [string_for_number, long_string_for_list, unknown_kind, unknown_variant].into_iter().enumerate() { - let file = write(&dir, &format!("canary{n}.json"), &json!([document])); - let ran = at(closed_port(), &admit_args(&file), None); - assert_eq!(ran.code, 2, "case {n}: {}", ran.err); - assert!(ran.err.starts_with("InvalidInput: documents does not decode: "), "case {n}: {}", ran.err); - assert!(ran.err.contains(" at line 1 column "), "case {n}: {}", ran.err); - assert!(!ran.err.contains("CANARY") && !ran.out.contains("CANARY"), "case {n}: {}", ran.err); - assert!(ran.err.len() < 300, "stderr is bounded whatever the input: {} bytes", ran.err.len()); - } - let ran = at(closed_port(), &["query", r#"{"limit": "CANARY-LIMIT"}"#], None); - assert_eq!(ran.code, 2); - assert!(ran.err.starts_with("InvalidInput: selection does not decode: "), "{}", ran.err); - assert!(!ran.err.contains("CANARY") && ran.err.len() < 300, "{}", ran.err); - let ran = at(closed_port(), &admit_args("-"), Some(r#"[{"kind": "campaign", "value": CANARY-SYNTAX}]"#)); - assert_eq!(ran.code, 2); - assert!(ran.err.starts_with("InvalidInput: not JSON: syntax at line 1 column "), "{}", ran.err); - assert!(!ran.err.contains("CANARY"), "{}", ran.err); -} - -#[test] -fn a_refused_read_back_is_the_minds_no_with_the_receipt_printed() { - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "ruling.json", &json!([ruling(None)])); - let server = scripted(|message| { - let (_, request) = decode_request(message).expect("a mind request"); - match request { - HuginnMindRequest::Admit(_) => answer( - "admit", - &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { - receipt_id: "mind-commit-x".into(), - committed_at: "2026-10-10T00:00:00Z".into(), - writes: vec![], - }), - ), - _ => answer("query", &HuginnMindResponse::Refused(MindRefusal::MissingIdentity)), - } - }); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 1, "{}", ran.err); - assert!(ran.out.starts_with("Committed mind-commit-x at "), "{}", ran.out); - assert!(ran.out.contains("Refused MissingIdentity"), "{}", ran.out); - assert_eq!(ran.err, ""); -} - -fn view_of(document: &PipelineDocument) -> PipelineDocumentView { - PipelineDocumentView { - id: PipelineRef { kind: document.kind(), id: Short(pipeline_key(document).unwrap()) }, - document: document.clone(), - admission: AdmissionFacts { - receipt_id: "mind-commit-x".into(), - admitted_at: "2026-10-10T00:00:00Z".into(), - provenance: PipelineProvenance { - faculty: huginn_mind::Faculty::Hands, - agent: Short("a".into()), - session: Short("s".into()), - tool: Short("huginn".into()), - }, - ordinal: 1, - }, - status: PipelineStatus::InForce, - } -} - -/// Admits `Committed` and answers the keys query with `stored`. -fn committing(stored: Vec) -> Server { - scripted(move |message| { - let (_, request) = decode_request(message).expect("a mind request"); - match request { - HuginnMindRequest::Admit(_) => answer( - "admit", - &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { - receipt_id: "mind-commit-x".into(), - committed_at: "2026-10-10T00:00:00Z".into(), - writes: vec![], - }), - ), - HuginnMindRequest::Query { selection, .. } => { - assert_eq!(selection.projection, "document"); - assert_eq!(selection.limit, Some(u32::try_from(selection.keys.as_ref().unwrap().len()).unwrap())); - let page = PipelineSelectionPage { - matched: u32::try_from(stored.len()).unwrap(), - as_of: 2, - next: None, - items: PipelinePageItems::Documents(stored.clone()), - edges: None, - }; - answer("query", &HuginnMindResponse::Query(page)) - } - other => panic!("unexpected {other:?}"), - } - }) -} - -#[test] -fn a_field_the_mind_dropped_is_reported_with_the_receipt_printed() { - let dir = tempfile::tempdir().unwrap(); - let sent = ruling(Some("CANARY-QUOTE")); - let file = write(&dir, "ruling.json", &json!([sent])); - let key = pipeline_key(&sent).unwrap(); - - let server = committing(vec![view_of(&ruling(None))]); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 5); - assert!(ran.out.starts_with("Committed mind-commit-x at 2026-10-10T00:00:00Z"), "{}", ran.out); - assert!(!ran.out.contains("read back"), "{}", ran.out); - assert!(ran.err.starts_with(&format!("ReadBackDiffers: {key}: value.operator_quote;")), "{}", ran.err); - assert!(ran.err.contains("supersede"), "{}", ran.err); - - let missing = committing(vec![]); - let ran = at(missing.addr, &admit_args(&file), None); - assert_eq!(ran.code, 5); - assert!(ran.err.contains(&format!("{key}: missing from the read-back")), "{}", ran.err); - - let equal = committing(vec![view_of(&sent)]); - let ran = at(equal.addr, &admit_args(&file), None); - assert_eq!(ran.code, 0, "{}", ran.err); - assert!(ran.out.ends_with("read back 1 equal\n"), "{}", ran.out); -} - -#[test] -fn a_difference_deep_in_a_list_names_its_path() { - let dir = tempfile::tempdir().unwrap(); - let mut sent = serde_json::from_value::(spec("A")).unwrap(); - let rulings = |document: &mut PipelineDocument, ids: &[&str]| { - if let PipelineDocument::CutSpec(value) = document { - value.rulings = ids.iter().map(|id| Short(format!("{CAMPAIGN}:ruling:{id}"))).collect(); - } - }; - rulings(&mut sent, &["R1"]); - let file = write(&dir, "spec.json", &json!([sent])); - - let mut stored = sent.clone(); - rulings(&mut stored, &["R2"]); - if let PipelineDocument::CutSpec(value) = &mut stored { - value.title = "Another".into(); - } - let server = committing(vec![view_of(&stored)]); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 5); - assert!(ran.err.contains("value.rulings[0], value.title;"), "{}", ran.err); - - let mut longer = sent.clone(); - rulings(&mut longer, &["R1", "R2"]); - let server = committing(vec![view_of(&longer)]); - let ran = at(server.addr, &admit_args(&file), None); - assert_eq!(ran.code, 5); - assert!(ran.err.contains("value.rulings;"), "{}", ran.err); - assert!(!ran.err.contains("rulings["), "{}", ran.err); -} - -#[test] -fn a_full_batch_passes_the_door() { - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "full.json", &json!((0..64).map(|_| campaign_json()).collect::>())); - let ran = at(closed_port(), &admit_args(&file), None); - assert_eq!(ran.code, 3, "64 documents are a batch; the daemon is what is down: {}", ran.err); -} - -#[test] -fn exit_codes_follow_the_answer() { - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "campaign.json", &json!([campaign_json()])); - - // Nothing listening: Unavailable, naming the endpoint, whoami included. - let port = closed_port(); - let down = at(port, &["view", "eureka-state:campaign:self"], None); - assert_eq!(down.code, 3); - assert!(down.err.starts_with("Unavailable: "), "{}", down.err); - assert!(down.err.contains(&format!("rudp://{port}")), "{}", down.err); - let whoami = at(port, &["whoami"], None); - assert_eq!(whoami.code, 3); - assert!(whoami.out.contains("reachable no"), "{}", whoami.out); - - // The daemon rejecting the envelope. - let rejecting = scripted(|_| { - encode_failure( - "eureka-state-call", - "view", - &OperationFailure { code: "wrong-service".into(), message: "not huginn.mind".into() }, - "scripted", - ) - }); - let rejected = at(rejecting.addr, &["view", "eureka-state:campaign:self"], None); - assert_eq!(rejected.code, 4); - assert!(rejected.err.starts_with("Rejected: "), "{}", rejected.err); - assert!(rejected.err.contains("wrong-service"), "{}", rejected.err); - - // An answer of another operation's shape. - let status = MindStatus { - instance: slug(INSTANCE), - schema_epoch: "e".into(), - documents: 0, - receipts: 0, - index: IndexStatus::Current, - persona: PersonaStatus::Absent, - }; - let (odd, _) = counting(HuginnMindResponse::Whoami(status), "view"); - let internal = at(odd.addr, &["view", "eureka-state:campaign:self"], None); - assert_eq!(internal.code, 4); - assert!(internal.err.starts_with("Internal: "), "{}", internal.err); - - // A batch no single send carries, refused before sending. - let mut huge = campaign_json(); - huge["value"]["working_branch"] = json!("b".repeat(90_000)); - let big = write(&dir, "huge.json", &json!([huge])); - let too_large = at(closed_port(), &admit_args(&big), None); - assert_eq!(too_large.code, 2); - assert!(too_large.err.starts_with("TooLarge: "), "{}", too_large.err); - assert!(too_large.err.contains(&eureka_state::MAX_REQUEST_BYTES.to_string()), "{}", too_large.err); - - // The mind saying no: a refusal is an answer on stdout. - let live = live(); - let refused = at(live.addr, &["admit", "--faculty", "Hands", "--agent", "a", "--session", "", &file], None); - assert_eq!(refused.code, 1); - assert!(refused.out.starts_with("Refused "), "{}", refused.out); - assert!(refused.out.contains("provenance.session"), "{}", refused.out); - assert_eq!(refused.err, ""); - - // Absent: the mind answered null. - let absent = at(live.addr, &["view", "eureka-state:cut_spec:cut-99.r1"], None); - assert_eq!(absent.code, 1); - assert_eq!(absent.out, "absent eureka-state:cut_spec:cut-99.r1\n"); - - // Another instance's mind: refused on the read side too. - let foreign = run( - &[("EUREKA_INSTANCE", "thought-cage"), ("HUGINN_ENDPOINT", &format!("rudp://{}", live.addr))], - &["query", "{}"], - None, - ); - assert_eq!(foreign.code, 1); - assert!(foreign.out.starts_with("Refused "), "{}", foreign.out); -} - -#[test] -fn a_call_that_is_wrong_exits_two_without_sending() { - let (server, count) = counting(HuginnMindResponse::View(None), "view"); - for args in [ - vec!["view", "eureka-state:nonsense:x"], - vec!["view", "no-kind-segment"], - vec!["history", "eureka-state:nonsense:x"], - vec!["query", "{ not json"], - vec!["query", "[]"], - vec!["admit", "--faculty", "Nope", "--agent", "a", "--session", "s", "x.json"], - vec!["schema", "no-such-kind"], - vec!["bogus"], - vec!["view"], - vec![], - ] { - let ran = at(server.addr, &args, None); - assert_eq!(ran.code, 2, "{args:?}"); - assert!(ran.err.starts_with("InvalidInput: "), "{args:?}: {}", ran.err); - assert_eq!(ran.out, "", "{args:?}"); - } - assert_eq!(*count.lock().unwrap(), 0); -} - -#[test] -fn the_recipes_send_exactly_the_pages_selections() { - let schema = |kind: &str| format!("epiphany.pipeline.{kind}.v2"); - let root = |values: &[&str]| json!({ "index": "root", "op": "any_of", "values": values }); - let in_force = json!({ "index": "in_force", "op": "any_of", "values": ["true"] }); - let c = "eureka-substrate"; - - let cases = [ - (vec!["campaigns"], json!({ "schemas": [schema("campaign")] })), - ( - vec!["target", c], - json!({ "schemas": [schema("target")], "fields": [root(&[c]), in_force], "projection": "document" }), - ), - ( - vec!["rulings", c, "eureka-body"], - json!({ "schemas": [schema("ruling")], "fields": [root(&[c, "eureka-body"]), in_force] }), - ), - ( - vec!["open", c], - json!({ "schemas": [schema("question"), schema("follow_up")], "fields": [root(&[c]), in_force] }), - ), - ( - vec!["findings", c], - json!({ - "schemas": [schema("finding")], - "fields": [root(&[c]), in_force, { "index": "faculty", "op": "any_of", "values": ["Soul"] }], - }), - ), - ( - vec!["findings", c, "--blocking"], - json!({ - "schemas": [schema("finding")], - "fields": [ - root(&[c]), - in_force, - { "index": "faculty", "op": "any_of", "values": ["Soul"] }, - { "index": "severity", "op": "any_of", "values": ["Blocker", "High"] }, - ], - }), - ), - ( - vec!["unreported", c], - json!({ - "schemas": [schema("cut_spec")], - "fields": [root(&[c]), in_force], - "cited": { "role": "cut_spec", "exists": false }, - }), - ), - ( - vec!["blocked", "eureka-substrate:cut_spec:cut-x.r1"], - json!({ - "schemas": [schema("question")], - "fields": [in_force], - "cites": { - "target": { "schemaId": schema("cut_spec"), "recordKey": "eureka-substrate:cut_spec:cut-x.r1" }, - "role": "raised_in", - }, - }), - ), - ( - vec!["unjudged", c], - json!({ - "schemas": [schema("cut_report")], - "fields": [root(&[c])], - "cited": { "role": "cut_report", "exists": false }, - }), - ), - ( - vec!["history", "eureka-substrate:ruling:R1"], - json!({ - "schemas": [schema("resolution")], - "cites": { "target": { "schemaId": schema("ruling"), "recordKey": "eureka-substrate:ruling:R1" }, "role": "subject" }, - "descending": true, - }), - ), - ( - vec!["cut", c, "huginn-cli"], - json!({ - "schemas": [schema("cut_spec"), schema("cut_report"), schema("verdict"), schema("finding"), schema("resolution")], - "fields": [root(&[c]), { "index": "cut", "op": "any_of", "values": ["huginn-cli"] }], - }), - ), - ( - vec!["ledger", c], - json!({ "schemas": [schema("cut_spec"), schema("cut_report")], "fields": [root(&[c])], "projection": "document" }), - ), - ( - vec!["precedent", c, "the question in plain words"], - json!({ "schemas": [schema("ruling"), schema("resolution"), schema("finding")], "fields": [root(&[c])] }), - ), - ( - vec!["gaps"], - json!({ "schemas": [schema("follow_up")], "fields": [root(&["eureka-substrate"]), in_force] }), - ), - ]; - for (args, literal) in cases { - let (selection, semantic) = sent(&args); - assert_eq!(selection, page_literal(literal), "{args:?}"); - let expected = (args[0] == "precedent").then(|| ("the question in plain words".to_string(), 10)); - assert_eq!(semantic, expected, "{args:?}"); - } -} - -#[test] -fn paging_and_query_flags_shape_the_selection() { - let (selection, semantic) = sent(&["gaps", "--cursor", "abc", "--documents"]); - assert_eq!(selection.cursor.as_deref(), Some("abc")); - assert_eq!(selection.projection, "document"); - assert_eq!(selection.limit, Some(50)); - assert_eq!(semantic, None); - - let (selection, _) = sent(&["gaps"]); - assert_eq!(selection.cursor, None); - assert_eq!(selection.projection, "header"); - - let (selection, semantic) = sent(&["query", "{}", "--near", "drift", "--top-k", "7"]); - assert_eq!(selection, page_literal(json!({}))); - assert_eq!(semantic, Some(("drift".to_string(), 7))); - let (_, semantic) = sent(&["query", "{}", "--near", "drift"]); - assert_eq!(semantic, Some(("drift".to_string(), 10))); - - let (selection, _) = sent(&["query", r#"{"limit": 5, "descending": true}"#]); - assert_eq!(selection.limit, Some(5)); - assert!(selection.descending); - let (selection, _) = sent(&["query", r#"{"projection": "header"}"#, "--documents"]); - assert_eq!(selection.projection, "document"); - - let ran = at(closed_port(), &["query", "{}", "--top-k", "3"], None); - assert_eq!(ran.code, 2, "--top-k needs --near"); - - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "selection.json", &json!({ "schemas": ["epiphany.pipeline.campaign.v2"] })); - let (selection, _) = sent(&["query", &format!("@{file}")]); - assert_eq!(selection.schemas, Some(vec!["epiphany.pipeline.campaign.v2".to_string()])); - let (server, seen) = recording(); - let ran = at(server.addr, &["query", "-"], Some(r#"{"keys": ["a:campaign:self"]}"#)); - assert_eq!(ran.code, 0, "{}", ran.err); - let seen = seen.lock().unwrap(); - let [HuginnMindRequest::Query { selection, .. }] = &seen[..] else { panic!("{seen:?}") }; - assert_eq!(selection.keys, Some(vec!["a:campaign:self".to_string()])); -} - -#[test] -fn recipes_list_what_the_mind_holds() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let campaign = write(&dir, "campaign.json", &json!([campaign_json()])); - let ran = at(server.addr, &admit_args(&campaign), None); - assert_eq!(ran.code, 0, "{}", ran.err); - let specs = write(&dir, "specs.json", &json!([spec("A"), spec("B")])); - let ran = at(server.addr, &admit_args(&specs), None); - assert_eq!(ran.code, 0, "{}", ran.err); - - let unreported = at(server.addr, &["unreported", CAMPAIGN], None); - assert_eq!(unreported.code, 0, "{}", unreported.err); - let mut lines: Vec<&str> = unreported.out.lines().collect(); - assert_eq!(lines.pop().unwrap().split(' ').take(2).collect::>(), ["matched", "2"]); - assert_eq!(lines.len(), 2); - - let reports = write(&dir, "report.json", &json!([report("B")])); - let ran = at(server.addr, &admit_args(&reports), None); - assert_eq!(ran.code, 0, "{}", ran.err); - - let unreported = at(server.addr, &["unreported", CAMPAIGN], None); - let lines: Vec<&str> = unreported.out.lines().collect(); - assert_eq!(lines.len(), 2, "{}", unreported.out); - let tokens: Vec<&str> = lines[0].split(' ').collect(); - let id = format!("{CAMPAIGN}:cut_spec:cut-A.r1"); - assert_eq!(tokens[..5], [id.as_str(), "InForce", "Hands", "A", "cut"]); - for fact in ["cut=A", "repo=GameCult/Epiphany", "revision=1", "base=5f98228d", "branch=codex/eureka-pipeline-state"] { - assert!(tokens.contains(&fact), "{fact}: {}", lines[0]); - } - assert!(lines[1].starts_with("matched 1 as_of "), "{}", lines[1]); - assert!(lines[1].ends_with(" next -"), "{}", lines[1]); - assert!(!unreported.out.contains("cut-B.r1"), "{}", unreported.out); - - let unjudged = at(server.addr, &["unjudged", CAMPAIGN], None); - assert!(unjudged.out.contains(&format!("{CAMPAIGN}:cut_report:cut-B.h1")), "{}", unjudged.out); - assert!(unjudged.out.contains("matched 1 "), "{}", unjudged.out); - - let campaigns = at(server.addr, &["campaigns"], None); - assert!(campaigns.out.starts_with(&format!("{CAMPAIGN}:campaign:self InForce Hands Eureka pipeline state repos={REPO}\n")), "{}", campaigns.out); - - let whole = at(server.addr, &["ledger", CAMPAIGN], None); - assert_eq!(whole.code, 0, "{}", whole.err); - assert_eq!(whole.out.matches("admitted ").count(), 3, "{}", whole.out); - assert!(!whole.out.starts_with('\n'), "{}", whole.out); - assert_eq!(whole.out.matches("\n\n").count(), 2, "documents are separated by one blank line: {}", whole.out); - - let documents = at(server.addr, &["campaigns", "--documents"], None); - assert!(documents.out.contains("\nadmitted "), "{}", documents.out); - assert!(documents.out.contains("\"kind\": \"campaign\""), "{}", documents.out); -} - -#[test] -fn a_long_header_is_cut() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let mut doc = campaign_json(); - doc["value"]["title"] = json!("t".repeat(200)); - doc["value"]["working_branch"] = json!("b"); - let file = write(&dir, "long.json", &json!([doc])); - assert_eq!(at(server.addr, &admit_args(&file), None).code, 0); - let ran = at(server.addr, &["campaigns"], None); - let header = ran.out.lines().next().unwrap(); - assert_eq!(header.chars().count(), 240); -} - -#[test] -fn a_resolved_document_shows_its_closing_record() { - let server = live(); - let dir = tempfile::tempdir().unwrap(); - let question = json!({ - "kind": "question", - "value": { - "campaign": CAMPAIGN, - "label": "Q1", - "title": "Who owns the state?", - "question": "Who owns the state?", - "options": [{ "label": "A", "text": "an instance" }, { "label": "B", "text": "a repo" }], - "recommended": "A", - "depends": [], - "raised_in": null, - "asked_on": "2026-10-10", - }, - }); - let setup = write(&dir, "setup.json", &json!([campaign_json(), question])); - let ran = at(server.addr, &admit_args(&setup), None); - assert_eq!(ran.code, 0, "{}{}", ran.out, ran.err); - let resolution = json!({ - "kind": "resolution", - "value": { - "subject": { "kind": "Question", "id": format!("{CAMPAIGN}:question:Q1") }, - "sequence": 1, - "outcome": { "Withdrawn": { "reason": "moot" } }, - "rationale": "Resolved.", - "resolved_on": "2026-10-10", - }, - }); - let closing = write(&dir, "closing.json", &json!([resolution])); - let ran = at(server.addr, &admit_args(&closing), None); - assert_eq!(ran.code, 0, "{}{}", ran.out, ran.err); - - let id = format!("{CAMPAIGN}:question:Q1"); - let closer = format!("{CAMPAIGN}:resolution:question.Q1.n1"); - let viewed = at(server.addr, &["view", &id], None); - assert_eq!(viewed.out.lines().next().unwrap(), format!("{id} Resolved Withdrawn by {closer}")); - - let history = at(server.addr, &["history", &id], None); - assert_eq!(history.code, 0, "{}", history.err); - assert!(history.out.starts_with(&format!("{closer} InForce Hands ")), "{}", history.out); - assert!(history.out.contains("sequence=1"), "{}", history.out); - - let open = at(server.addr, &["open", CAMPAIGN], None); - assert!(open.out.contains("matched 0 "), "a resolved question is not open: {}", open.out); - - let header = at(server.addr, &["query", r#"{"schemas": ["epiphany.pipeline.question.v2"]}"#], None); - assert!(header.out.starts_with(&format!("{id} Resolved:Withdrawn Hands Who owns the state? ")), "{}", header.out); - assert!(header.out.contains("options=A,B") && header.out.contains("recommended=A"), "{}", header.out); -} - -#[test] -fn schema_prints_the_published_files() { - let manifest = Path::new(env!("CARGO_MANIFEST_DIR")); - for kind in ["cut_spec", "campaign", "hand_off", "run"] { - let ran = run(&[], &["schema", kind], None); - assert_eq!(ran.code, 0); - let published = std::fs::read_to_string(manifest.join(format!("../../schemas/cultnet/epiphany.pipeline.{kind}.v2.schema.json"))).unwrap(); - assert_eq!(ran.out, published, "{kind}"); - } - let selection = run(&[], &["schema", "selection"], None); - assert_eq!(selection.out, std::fs::read_to_string(manifest.join("schemas/cultnet.selection.schema.json")).unwrap()); - let names = run(&[], &["schema"], None); - assert_eq!(names.code, 0); - let names: Vec<&str> = names.out.lines().collect(); - assert_eq!(names.len(), 15, "{names:?}"); - assert_eq!(names[0], "campaign"); - assert_eq!(names[14], "selection"); - for kind in PipelineKind::ALL { - assert!(names.contains(&kind.name()), "{}", kind.name()); - } - let unknown = run(&[], &["schema", "no-such-kind"], None); - assert_eq!(unknown.code, 2); - assert!(unknown.err.starts_with("InvalidInput: "), "{}", unknown.err); -} - -#[test] -fn help_is_the_schema_surface() { - let rulings = run(&[], &["rulings", "--help"], None); - assert_eq!(rulings.code, 0); - let (_, printed) = rulings.out.split_once("selection:\n").expect("the selection is in the help"); - let selection: Value = serde_json::from_str(printed.trim()).unwrap(); - assert_eq!( - selection, - json!({ - "schemas": ["epiphany.pipeline.ruling.v2"], - "fields": [ - { "index": "root", "op": "any_of", "values": [""] }, - { "index": "in_force", "op": "any_of", "values": ["true"] }, - ], - }) - ); - let history = run(&[], &["history", "--help"], None); - assert!(history.out.contains("epiphany.pipeline..v2"), "{}", history.out); - let findings = run(&[], &["findings", "--help"], None); - assert!(findings.out.contains("\"severity\"") && findings.out.contains("Blocker"), "{}", findings.out); - let precedent = run(&[], &["precedent", "--help"], None); - assert!(precedent.out.contains("\"top_k\": 10"), "{}", precedent.out); - let admit = run(&[], &["admit", "--help"], None); - let admit_text = admit.out.split_whitespace().collect::>().join(" "); - assert!(admit_text.contains("{\"kind\": , \"value\": {...}}"), "{admit_text}"); - assert!(admit_text.contains("exit 5"), "{admit_text}"); - - let version = run(&[], &["--version"], None); - assert_eq!(version.code, 0); - let sha = option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown"); - assert_eq!(version.out, format!("huginn {} ({sha})\n", env!("CARGO_PKG_VERSION"))); -} - -#[test] -fn every_recipe_has_help() { - for recipe in [ - "campaigns", "target", "rulings", "open", "findings", "unreported", "blocked", "unjudged", "history", "cut", "ledger", - "precedent", "gaps", - ] { - let ran = run(&[], &[recipe, "--help"], None); - assert_eq!(ran.code, 0, "{recipe}"); - assert!(ran.out.contains("epiphany.pipeline."), "{recipe}: {}", ran.out); - assert!(ran.out.contains("--cursor"), "{recipe}: {}", ran.out); - } -} - -#[test] -fn a_conflicting_batch_is_the_minds_no() { - let conflict = scripted(|message| { - let (_, request) = decode_request(message).expect("a mind request"); - assert!(matches!(request, HuginnMindRequest::Admit(_))); - answer( - "admit", - &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { - identities: vec![PipelineRef { kind: PipelineKind::Campaign, id: Short(format!("{CAMPAIGN}:campaign:self")) }], - }), - ) - }); - let dir = tempfile::tempdir().unwrap(); - let file = write(&dir, "campaign.json", &json!([campaign_json()])); - let ran = at(conflict.addr, &admit_args(&file), None); - assert_eq!(ran.code, 1); - assert_eq!(ran.out, format!("Conflict\nconflicts {CAMPAIGN}:campaign:self\n")); -} +//! The `huginn` binary as an agent drives it: a real process, its stdout, its +//! stderr and its exit code, against a real daemon in-process or a scripted +//! server where the daemon cannot be made to misbehave. + +use std::io::Write; +use std::net::{SocketAddr, UdpSocket}; +use std::path::Path; +use std::process::{Command, Stdio}; +use std::sync::{Arc, Mutex}; + +use cultnet_rs::Selection; +use huginn_mind::envelope::{OperationFailure, decode_request, encode_failure, encode_response}; +use huginn_mind::eureka_pipeline::{ + CodeLocation, CommitRange, CutVerification, Date, Evidence, EvidenceKind, MutationRecord, OrgRepo, PipelineCutReport, + PipelineCutSpec, PipelineDocument, PipelineKind, PipelineRef, PipelineRuling, Promise, ReportCommit, RulingAuthority, Short, + StructuralDelta, pipeline_key, +}; +use huginn_mind::{ + AdmissionFacts, HuginnMindRequest, HuginnMindResponse, IndexStatus, MindRefusal, MindStatus, PersonaStatus, PipelineAdmissionOutcome, PipelineDocumentView, + PipelinePageItems, PipelineProvenance, PipelineSelectionPage, PipelineStatus, +}; +use serde_json::{Value, json}; +use tempfile::TempDir; + +mod common; +use common::*; + +struct Run { + code: i32, + out: String, + err: String, +} + +fn run(env: &[(&str, &str)], args: &[&str], stdin: Option<&str>) -> Run { + let mut command = Command::new(env!("CARGO_BIN_EXE_huginn")); + command + .env_remove("EUREKA_INSTANCE") + .env_remove("HUGINN_ENDPOINT") + .envs(env.iter().copied()) + .args(args) + .stdin(if stdin.is_some() { Stdio::piped() } else { Stdio::null() }) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + let mut child = command.spawn().expect("the binary starts"); + if let Some(text) = stdin { + child.stdin.take().unwrap().write_all(text.as_bytes()).unwrap(); + } + let output = child.wait_with_output().unwrap(); + Run { + code: output.status.code().expect("exited, not killed"), + out: String::from_utf8(output.stdout).unwrap(), + err: String::from_utf8(output.stderr).unwrap(), + } +} + +/// Configured for the test instance against a daemon at `addr`. +fn at(addr: SocketAddr, args: &[&str], stdin: Option<&str>) -> Run { + run(&[("EUREKA_INSTANCE", INSTANCE), ("HUGINN_ENDPOINT", &format!("rudp://{addr}"))], args, stdin) +} + +/// A loopback UDP port nothing listens on. +fn closed_port() -> SocketAddr { + UdpSocket::bind("127.0.0.1:0").unwrap().local_addr().unwrap() +} + +fn write(dir: &TempDir, name: &str, value: &Value) -> String { + let path = dir.path().join(name); + std::fs::write(&path, value.to_string()).unwrap(); + path.to_str().unwrap().to_string() +} + +fn campaign_json() -> Value { + serde_json::to_value(campaign()).unwrap() +} + +fn live() -> Server { + let (root, daemon) = mind(vec![vec![stewardship()]]); + serve(root, daemon) +} + +fn admit_args(file: &str) -> Vec<&str> { + vec!["admit", "--faculty", "Hands", "--agent", "claude", "--session", "session-7", file] +} + +fn delta() -> StructuralDelta { + StructuralDelta { + lines_added: 0, + lines_removed: 0, + dependencies_added: vec![], + dependencies_removed: vec![], + formats_added: vec![], + formats_removed: vec![], + targets_added: vec![], + targets_removed: vec![], + } +} + +fn spec(cut: &str) -> Value { + serde_json::to_value(PipelineDocument::CutSpec(PipelineCutSpec { + campaign: slug(CAMPAIGN), + cut: cut.into(), + revision: 1, + title: "A cut".into(), + repo: OrgRepo(REPO.into()), + branch: "codex/eureka-pipeline-state".into(), + base: sha(), + depends_on: vec![], + first: vec![], + deletes: vec![], + keeps_moves: vec![], + adds: vec![], + file_changes: vec![], + reads: vec![], + authority_map: None, + verification: CutVerification { builds: vec![], tests: vec![], negative: vec![], operator: vec![] }, + estimate: delta(), + rulings: vec![], + questions: vec![], + })) + .unwrap() +} + +fn report(cut: &str) -> Value { + serde_json::to_value(PipelineDocument::CutReport(PipelineCutReport { + campaign: slug(CAMPAIGN), + cut_spec: Short(format!("{CAMPAIGN}:cut_spec:cut-{cut}.r1")), + attempt: 1, + repo: OrgRepo(REPO.into()), + branch: "codex/eureka-pipeline-state".into(), + commits: vec![ReportCommit { sha: sha(), subject: "Land the cut".into(), builds: true }], + range: CommitRange { base: sha(), head: sha() }, + verification: vec![Evidence { kind: EvidenceKind::Test, locator: "cargo test".into(), result: "ok".into() }], + mutations: vec![MutationRecord { + label: "M1".into(), + rule: "the rule".into(), + location: CodeLocation { path: Short("crates/x.rs".into()), line: 1, end_line: None, symbol: None }, + before: "before".into(), + after: "after".into(), + commit: sha(), + failed_as_expected: true, + }], + deviations: vec![], + forks: vec![], + structural_delta: delta(), + landed_names: vec![], + undone: vec![], + promises: vec![Promise { label: "P1".into(), text: "One derived key per document.".into() }], + })) + .unwrap() +} + +fn ruling(quote: Option<&str>) -> PipelineDocument { + PipelineDocument::Ruling(PipelineRuling { + campaign: slug(CAMPAIGN), + label: "R1".into(), + title: "An instance owns its mind".into(), + answers: None, + choice: None, + ruling: "An instance owns its mind.".into(), + operator_quote: quote.map(Into::into), + ruled_on: Date("2026-10-10".into()), + precedents: vec![], + authority: RulingAuthority::Standing, + }) +} + +fn empty_page() -> PipelineSelectionPage { + PipelineSelectionPage { matched: 0, as_of: 1, next: None, items: PipelinePageItems::Headers(vec![]), edges: None } +} + +fn answer(operation: &str, response: &HuginnMindResponse) -> cultnet_rs::CultNetMessage { + encode_response("eureka-state-call", operation, response, "scripted").unwrap() +} + +/// A scripted server that records every request it is sent and answers a +/// query with an empty page. +fn recording() -> (Server, Arc>>) { + let seen = Arc::new(Mutex::new(Vec::new())); + let sink = Arc::clone(&seen); + let server = scripted(move |message| { + let (_, request) = decode_request(message).expect("a mind request"); + sink.lock().unwrap().push(request); + answer("query", &HuginnMindResponse::Query(empty_page())) + }); + (server, seen) +} + +/// The selection a command sent, and its semantic part. +fn sent(args: &[&str]) -> (Selection, Option<(String, u32)>) { + let (server, seen) = recording(); + let ran = at(server.addr, args, None); + assert_eq!(ran.code, 0, "{args:?}: {}", ran.err); + assert!(ran.out.contains("matched 0 as_of 1 next -"), "{}", ran.out); + let seen = seen.lock().unwrap(); + let [HuginnMindRequest::Query { instance, selection, semantic }] = &seen[..] else { + panic!("one query expected: {seen:?}"); + }; + assert_eq!(instance.0, INSTANCE); + (selection.clone(), semantic.as_ref().map(|asked| (asked.text.0.clone(), asked.top_k))) +} + +/// The page's literal as the selection it spells, with the CLI's default page. +fn page_literal(literal: Value) -> Selection { + let mut selection: Selection = serde_json::from_value(literal).unwrap(); + selection.limit = Some(50); + selection +} + +fn counting(replies: HuginnMindResponse, operation: &'static str) -> (Server, Arc>) { + let count = Arc::new(Mutex::new(0)); + let counter = Arc::clone(&count); + let server = scripted(move |_| { + *counter.lock().unwrap() += 1; + answer(operation, &replies) + }); + (server, count) +} + +#[test] +fn without_configuration_whoami_reports_it_and_every_other_command_refuses() { + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "campaign.json", &json!([campaign_json()])); + + let whoami = run(&[], &["whoami"], None); + assert_eq!(whoami.code, 2); + assert!(whoami.out.contains("instance unset\nendpoint unset\nclient "), "{}", whoami.out); + assert!(whoami.out.contains("reachable no"), "{}", whoami.out); + assert!(whoami.err.starts_with("Misconfigured: EUREKA_INSTANCE is not set"), "{}", whoami.err); + + for args in [ + vec!["view", "eureka-state:campaign:self"], + vec!["query", "{}"], + vec!["rulings", "eureka-state"], + admit_args(&file), + ] { + let ran = run(&[], &args, None); + assert_eq!(ran.code, 2, "{args:?}"); + assert!(ran.err.starts_with("Misconfigured:"), "{args:?}: {}", ran.err); + assert_eq!(ran.out, "", "{args:?}"); + } +} + +#[test] +fn a_bad_environment_is_misconfigured_with_its_own_reason() { + let cases: [(&[(&str, &str)], &str); 4] = [ + (&[("HUGINN_ENDPOINT", "rudp://127.0.0.1:1")], "EUREKA_INSTANCE is not set"), + (&[("EUREKA_INSTANCE", "Not A Slug"), ("HUGINN_ENDPOINT", "rudp://127.0.0.1:1")], "EUREKA_INSTANCE is not a valid"), + (&[("EUREKA_INSTANCE", "eureka")], "HUGINN_ENDPOINT is not set"), + (&[("EUREKA_INSTANCE", "eureka"), ("HUGINN_ENDPOINT", "127.0.0.1:1")], "HUGINN_ENDPOINT is not rudp://"), + ]; + for (env, expected) in cases { + let ran = run(env, &["whoami"], None); + assert_eq!(ran.code, 2, "{expected}"); + assert!(ran.err.starts_with("Misconfigured: "), "{}", ran.err); + assert!(ran.err.contains(expected), "{expected}: {}", ran.err); + } + let named = run(&[("EUREKA_INSTANCE", "eureka"), ("HUGINN_ENDPOINT", "rudp://not-an-address")], &["whoami"], None); + assert_eq!(named.code, 2); + assert!(named.out.contains("endpoint rudp://not-an-address"), "{}", named.out); + assert!(named.out.contains("instance eureka"), "{}", named.out); +} + +#[test] +fn whoami_reads_the_live_mind() { + let server = live(); + let ran = at(server.addr, &["whoami"], None); + assert_eq!(ran.code, 0, "{}", ran.err); + let lines: Vec<&str> = ran.out.lines().collect(); + assert_eq!(lines[0], format!("instance {INSTANCE}")); + assert_eq!(lines[1], format!("endpoint rudp://{}", server.addr)); + assert_eq!(lines[2], format!("client {}", option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown"))); + assert_eq!(lines[3], "reachable yes"); + assert_eq!(lines[4], "documents 2 receipts 2 index Current epoch epiphany.pipeline.epoch.v2"); + assert_eq!(lines[5], "persona absent"); + assert_eq!(lines.len(), 6); + assert_eq!(ran.err, ""); +} + +#[test] +fn an_index_that_is_behind_shows_its_count() { + let status = MindStatus { + instance: slug(INSTANCE), + schema_epoch: "epoch".into(), + documents: 7, + receipts: 9, + index: IndexStatus::Behind { pending: 3 }, + persona: PersonaStatus::Absent, + }; + let (server, _) = counting(HuginnMindResponse::Whoami(status), "whoami"); + let ran = at(server.addr, &["whoami"], None); + assert_eq!(ran.code, 0); + assert!(ran.out.contains("documents 7 receipts 9 index Behind pending=3 epoch epoch"), "{}", ran.out); +} + +#[test] +fn whoami_shows_the_persona_door_state_and_nothing_of_the_document() { + for (persona, line) in [ + (PersonaStatus::Stored { updated_at: "2026-10-10T10:00:00Z".into() }, "persona stored updatedAt=2026-10-10T10:00:00Z"), + (PersonaStatus::Unreadable, "persona unreadable"), + ] { + let status = MindStatus { instance: slug(INSTANCE), schema_epoch: "e".into(), documents: 1, receipts: 1, index: IndexStatus::Current, persona }; + let (server, _) = counting(HuginnMindResponse::Whoami(status), "whoami"); + let ran = at(server.addr, &["whoami"], None); + assert_eq!(ran.code, 0); + assert_eq!(ran.out.lines().last(), Some(line), "{}", ran.out); + } +} + +#[test] +fn admit_round_trips_and_is_idempotent() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "campaign.json", &json!([campaign_json()])); + + let first = at(server.addr, &admit_args(&file), None); + assert_eq!(first.code, 0, "{}", first.err); + let lines: Vec<&str> = first.out.lines().collect(); + assert!(lines[0].starts_with("Committed mind-commit-"), "{}", first.out); + assert!(lines[0].contains(" at "), "{}", first.out); + assert_eq!(lines[1], format!("wrote {CAMPAIGN}:campaign:self")); + assert_eq!(lines[2], "read back 1 equal"); + assert_eq!(lines.len(), 3, "{}", first.out); + + let again = at(server.addr, &admit_args(&file), None); + assert_eq!(again.code, 0, "{}", again.err); + let lines: Vec<&str> = again.out.lines().collect(); + assert!(lines[0].starts_with("AlreadyAdmitted mind-commit-"), "{}", again.out); + assert_eq!(lines[1], "read back 1 equal"); + + let id = format!("{CAMPAIGN}:campaign:self"); + let viewed = at(server.addr, &["view", &id], None); + assert_eq!(viewed.code, 0, "{}", viewed.err); + let lines: Vec<&str> = viewed.out.lines().collect(); + assert_eq!(lines[0], format!("{id} InForce")); + assert!(lines[1].starts_with("admitted "), "{}", viewed.out); + assert!(lines[1].contains(" ordinal 3 Hands/claude session session-7 tool huginn receipt mind-commit-"), "{}", lines[1]); + let shown: Value = serde_json::from_str(&lines[2..].join("\n")).unwrap(); + assert_eq!(shown, campaign_json()); + + let raw = at(server.addr, &["view", &id, "--raw"], None); + assert_eq!(raw.code, 0); + assert_eq!(serde_json::from_str::(&raw.out).unwrap(), campaign_json()); + assert!(raw.out.starts_with('{'), "{}", raw.out); + + let fed_back = at(server.addr, &admit_args("-"), Some(&raw.out)); + assert_eq!(fed_back.code, 0, "{}", fed_back.err); + assert!(fed_back.out.starts_with("AlreadyAdmitted "), "{}", fed_back.out); + + let status = at(server.addr, &["whoami"], None); + assert!(status.out.contains("documents 3 receipts 3"), "{}", status.out); +} + +#[test] +fn unknown_keys_are_refused_by_path_and_never_by_value() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let mut nested = campaign_json(); + nested["value"]["target_doc"]["pathh"] = json!("CANARY-NESTED"); + let mut top = campaign_json(); + top["surplus"] = json!("CANARY-TOP"); + let file = write(&dir, "bad.json", &json!([nested, top])); + + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 2); + assert_eq!(ran.out, ""); + assert!(ran.err.starts_with("InvalidInput: "), "{}", ran.err); + assert!(ran.err.contains("documents[0].value.target_doc.pathh"), "{}", ran.err); + assert!(ran.err.contains("documents[1].surplus"), "{}", ran.err); + assert!(!ran.err.contains("CANARY"), "{}", ran.err); + + let status = at(server.addr, &["whoami"], None); + assert!(status.out.contains("receipts 2 "), "nothing was sent: {}", status.out); + + let selection = at(server.addr, &["query", r#"{"limt": 5}"#], None); + assert_eq!(selection.code, 2); + assert!(selection.err.contains("selection.limt"), "{}", selection.err); +} + +#[test] +fn an_explicitly_empty_unknown_key_is_not_a_loss() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let mut doc = campaign_json(); + doc["value"]["ghost"] = Value::Null; + doc["value"]["ghosts"] = json!([]); + doc["value"]["ghost_map"] = json!({}); + doc["value"]["ghost_text"] = json!(""); + let file = write(&dir, "ghosts.json", &json!([doc])); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 0, "{}", ran.err); + assert!(ran.out.contains("read back 1 equal"), "{}", ran.out); +} + +#[test] +fn a_falsy_unknown_value_is_still_a_loss() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let mut doc = campaign_json(); + doc["value"]["zero"] = json!(0); + doc["value"]["no"] = json!(false); + let file = write(&dir, "falsy.json", &json!([doc])); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 2); + assert!(ran.err.contains("documents[0].value.zero") && ran.err.contains("documents[0].value.no"), "{}", ran.err); +} + +#[test] +fn a_document_that_does_not_decode_is_invalid_input() { + let dir = tempfile::tempdir().unwrap(); + let cases = [ + (json!([{ "kind": "nonsense", "value": {} }]), "documents does not decode"), + (json!("text"), "JSON array"), + (json!([[]]), "documents[0] must be a JSON object"), + (json!([]), "1 to 64"), + (json!((0..65).map(|_| campaign_json()).collect::>()), "1 to 64"), + ]; + for (n, (value, expected)) in cases.into_iter().enumerate() { + let file = write(&dir, &format!("case{n}.json"), &value); + let ran = at(closed_port(), &admit_args(&file), None); + assert_eq!(ran.code, 2, "{expected}: {}", ran.err); + assert!(ran.err.starts_with("InvalidInput: "), "{}", ran.err); + assert!(ran.err.contains(expected), "{expected}: {}", ran.err); + } + let broken = at(closed_port(), &admit_args("-"), Some("{ not json")); + assert_eq!(broken.code, 2); + assert!(broken.err.contains("not JSON"), "{}", broken.err); + let missing = at(closed_port(), &admit_args("/no/such/file.json"), None); + assert_eq!(missing.code, 2); + assert!(missing.err.contains("cannot read /no/such/file.json"), "{}", missing.err); +} + +#[test] +fn a_document_that_does_not_decode_never_echoes_its_values() { + let dir = tempfile::tempdir().unwrap(); + let mut string_for_number = report("canary"); + string_for_number["value"]["attempt"] = json!("CANARY-NUMBER"); + let mut long_string_for_list = campaign_json(); + long_string_for_list["value"]["repos"] = json!(format!("CANARY-LIST{}", "x".repeat(60_000))); + let unknown_kind = json!({ "kind": "CANARY-KIND", "value": {} }); + let mut unknown_variant = serde_json::to_value(ruling(None)).unwrap(); + unknown_variant["value"]["authority"] = json!("CANARY-VARIANT"); + for (n, document) in [string_for_number, long_string_for_list, unknown_kind, unknown_variant].into_iter().enumerate() { + let file = write(&dir, &format!("canary{n}.json"), &json!([document])); + let ran = at(closed_port(), &admit_args(&file), None); + assert_eq!(ran.code, 2, "case {n}: {}", ran.err); + assert!(ran.err.starts_with("InvalidInput: documents does not decode: "), "case {n}: {}", ran.err); + assert!(ran.err.contains(" at line 1 column "), "case {n}: {}", ran.err); + assert!(!ran.err.contains("CANARY") && !ran.out.contains("CANARY"), "case {n}: {}", ran.err); + assert!(ran.err.len() < 300, "stderr is bounded whatever the input: {} bytes", ran.err.len()); + } + let ran = at(closed_port(), &["query", r#"{"limit": "CANARY-LIMIT"}"#], None); + assert_eq!(ran.code, 2); + assert!(ran.err.starts_with("InvalidInput: selection does not decode: "), "{}", ran.err); + assert!(!ran.err.contains("CANARY") && ran.err.len() < 300, "{}", ran.err); + let ran = at(closed_port(), &admit_args("-"), Some(r#"[{"kind": "campaign", "value": CANARY-SYNTAX}]"#)); + assert_eq!(ran.code, 2); + assert!(ran.err.starts_with("InvalidInput: not JSON: syntax at line 1 column "), "{}", ran.err); + assert!(!ran.err.contains("CANARY"), "{}", ran.err); +} + +#[test] +fn a_refused_read_back_is_the_minds_no_with_the_receipt_printed() { + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "ruling.json", &json!([ruling(None)])); + let server = scripted(|message| { + let (_, request) = decode_request(message).expect("a mind request"); + match request { + HuginnMindRequest::Admit(_) => answer( + "admit", + &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { + receipt_id: "mind-commit-x".into(), + committed_at: "2026-10-10T00:00:00Z".into(), + writes: vec![], + }), + ), + _ => answer("query", &HuginnMindResponse::Refused(MindRefusal::MissingIdentity)), + } + }); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 1, "{}", ran.err); + assert!(ran.out.starts_with("Committed mind-commit-x at "), "{}", ran.out); + assert!(ran.out.contains("Refused MissingIdentity"), "{}", ran.out); + assert_eq!(ran.err, ""); +} + +fn view_of(document: &PipelineDocument) -> PipelineDocumentView { + PipelineDocumentView { + id: PipelineRef { kind: document.kind(), id: Short(pipeline_key(document).unwrap()) }, + document: document.clone(), + admission: AdmissionFacts { + receipt_id: "mind-commit-x".into(), + admitted_at: "2026-10-10T00:00:00Z".into(), + provenance: PipelineProvenance { + faculty: huginn_mind::Faculty::Hands, + agent: Short("a".into()), + session: Short("s".into()), + tool: Short("huginn".into()), + }, + ordinal: 1, + }, + status: PipelineStatus::InForce, + } +} + +/// Admits `Committed` and answers the keys query with `stored`. +fn committing(stored: Vec) -> Server { + scripted(move |message| { + let (_, request) = decode_request(message).expect("a mind request"); + match request { + HuginnMindRequest::Admit(_) => answer( + "admit", + &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Committed { + receipt_id: "mind-commit-x".into(), + committed_at: "2026-10-10T00:00:00Z".into(), + writes: vec![], + }), + ), + HuginnMindRequest::Query { selection, .. } => { + assert_eq!(selection.projection, "document"); + assert_eq!(selection.limit, Some(u32::try_from(selection.keys.as_ref().unwrap().len()).unwrap())); + let page = PipelineSelectionPage { + matched: u32::try_from(stored.len()).unwrap(), + as_of: 2, + next: None, + items: PipelinePageItems::Documents(stored.clone()), + edges: None, + }; + answer("query", &HuginnMindResponse::Query(page)) + } + other => panic!("unexpected {other:?}"), + } + }) +} + +#[test] +fn a_field_the_mind_dropped_is_reported_with_the_receipt_printed() { + let dir = tempfile::tempdir().unwrap(); + let sent = ruling(Some("CANARY-QUOTE")); + let file = write(&dir, "ruling.json", &json!([sent])); + let key = pipeline_key(&sent).unwrap(); + + let server = committing(vec![view_of(&ruling(None))]); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 5); + assert!(ran.out.starts_with("Committed mind-commit-x at 2026-10-10T00:00:00Z"), "{}", ran.out); + assert!(!ran.out.contains("read back"), "{}", ran.out); + assert!(ran.err.starts_with(&format!("ReadBackDiffers: {key}: value.operator_quote;")), "{}", ran.err); + assert!(ran.err.contains("supersede"), "{}", ran.err); + + let missing = committing(vec![]); + let ran = at(missing.addr, &admit_args(&file), None); + assert_eq!(ran.code, 5); + assert!(ran.err.contains(&format!("{key}: missing from the read-back")), "{}", ran.err); + + let equal = committing(vec![view_of(&sent)]); + let ran = at(equal.addr, &admit_args(&file), None); + assert_eq!(ran.code, 0, "{}", ran.err); + assert!(ran.out.ends_with("read back 1 equal\n"), "{}", ran.out); +} + +#[test] +fn a_difference_deep_in_a_list_names_its_path() { + let dir = tempfile::tempdir().unwrap(); + let mut sent = serde_json::from_value::(spec("A")).unwrap(); + let rulings = |document: &mut PipelineDocument, ids: &[&str]| { + if let PipelineDocument::CutSpec(value) = document { + value.rulings = ids.iter().map(|id| Short(format!("{CAMPAIGN}:ruling:{id}"))).collect(); + } + }; + rulings(&mut sent, &["R1"]); + let file = write(&dir, "spec.json", &json!([sent])); + + let mut stored = sent.clone(); + rulings(&mut stored, &["R2"]); + if let PipelineDocument::CutSpec(value) = &mut stored { + value.title = "Another".into(); + } + let server = committing(vec![view_of(&stored)]); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 5); + assert!(ran.err.contains("value.rulings[0], value.title;"), "{}", ran.err); + + let mut longer = sent.clone(); + rulings(&mut longer, &["R1", "R2"]); + let server = committing(vec![view_of(&longer)]); + let ran = at(server.addr, &admit_args(&file), None); + assert_eq!(ran.code, 5); + assert!(ran.err.contains("value.rulings;"), "{}", ran.err); + assert!(!ran.err.contains("rulings["), "{}", ran.err); +} + +#[test] +fn a_full_batch_passes_the_door() { + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "full.json", &json!((0..64).map(|_| campaign_json()).collect::>())); + let ran = at(closed_port(), &admit_args(&file), None); + assert_eq!(ran.code, 3, "64 documents are a batch; the daemon is what is down: {}", ran.err); +} + +#[test] +fn exit_codes_follow_the_answer() { + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "campaign.json", &json!([campaign_json()])); + + // Nothing listening: Unavailable, naming the endpoint, whoami included. + let port = closed_port(); + let down = at(port, &["view", "eureka-state:campaign:self"], None); + assert_eq!(down.code, 3); + assert!(down.err.starts_with("Unavailable: "), "{}", down.err); + assert!(down.err.contains(&format!("rudp://{port}")), "{}", down.err); + let whoami = at(port, &["whoami"], None); + assert_eq!(whoami.code, 3); + assert!(whoami.out.contains("reachable no"), "{}", whoami.out); + + // The daemon rejecting the envelope. + let rejecting = scripted(|_| { + encode_failure( + "eureka-state-call", + "view", + &OperationFailure { code: "wrong-service".into(), message: "not huginn.mind".into() }, + "scripted", + ) + }); + let rejected = at(rejecting.addr, &["view", "eureka-state:campaign:self"], None); + assert_eq!(rejected.code, 4); + assert!(rejected.err.starts_with("Rejected: "), "{}", rejected.err); + assert!(rejected.err.contains("wrong-service"), "{}", rejected.err); + + // An answer of another operation's shape. + let status = MindStatus { + instance: slug(INSTANCE), + schema_epoch: "e".into(), + documents: 0, + receipts: 0, + index: IndexStatus::Current, + persona: PersonaStatus::Absent, + }; + let (odd, _) = counting(HuginnMindResponse::Whoami(status), "view"); + let internal = at(odd.addr, &["view", "eureka-state:campaign:self"], None); + assert_eq!(internal.code, 4); + assert!(internal.err.starts_with("Internal: "), "{}", internal.err); + + // A batch no single send carries, refused before sending. + let mut huge = campaign_json(); + huge["value"]["working_branch"] = json!("b".repeat(90_000)); + let big = write(&dir, "huge.json", &json!([huge])); + let too_large = at(closed_port(), &admit_args(&big), None); + assert_eq!(too_large.code, 2); + assert!(too_large.err.starts_with("TooLarge: "), "{}", too_large.err); + assert!(too_large.err.contains(&eureka_state::MAX_REQUEST_BYTES.to_string()), "{}", too_large.err); + + // The mind saying no: a refusal is an answer on stdout. + let live = live(); + let refused = at(live.addr, &["admit", "--faculty", "Hands", "--agent", "a", "--session", "", &file], None); + assert_eq!(refused.code, 1); + assert!(refused.out.starts_with("Refused "), "{}", refused.out); + assert!(refused.out.contains("provenance.session"), "{}", refused.out); + assert_eq!(refused.err, ""); + + // Absent: the mind answered null. + let absent = at(live.addr, &["view", "eureka-state:cut_spec:cut-99.r1"], None); + assert_eq!(absent.code, 1); + assert_eq!(absent.out, "absent eureka-state:cut_spec:cut-99.r1\n"); + + // Another instance's mind: refused on the read side too. + let foreign = run( + &[("EUREKA_INSTANCE", "thought-cage"), ("HUGINN_ENDPOINT", &format!("rudp://{}", live.addr))], + &["query", "{}"], + None, + ); + assert_eq!(foreign.code, 1); + assert!(foreign.out.starts_with("Refused "), "{}", foreign.out); +} + +#[test] +fn a_call_that_is_wrong_exits_two_without_sending() { + let (server, count) = counting(HuginnMindResponse::View(None), "view"); + for args in [ + vec!["view", "eureka-state:nonsense:x"], + vec!["view", "no-kind-segment"], + vec!["history", "eureka-state:nonsense:x"], + vec!["query", "{ not json"], + vec!["query", "[]"], + vec!["admit", "--faculty", "Nope", "--agent", "a", "--session", "s", "x.json"], + vec!["schema", "no-such-kind"], + vec!["bogus"], + vec!["view"], + vec![], + ] { + let ran = at(server.addr, &args, None); + assert_eq!(ran.code, 2, "{args:?}"); + assert!(ran.err.starts_with("InvalidInput: "), "{args:?}: {}", ran.err); + assert_eq!(ran.out, "", "{args:?}"); + } + assert_eq!(*count.lock().unwrap(), 0); +} + +#[test] +fn the_recipes_send_exactly_the_pages_selections() { + let schema = |kind: &str| format!("epiphany.pipeline.{kind}.v2"); + let root = |values: &[&str]| json!({ "index": "root", "op": "any_of", "values": values }); + let in_force = json!({ "index": "in_force", "op": "any_of", "values": ["true"] }); + let c = "eureka-substrate"; + + let cases = [ + (vec!["campaigns"], json!({ "schemas": [schema("campaign")] })), + ( + vec!["target", c], + json!({ "schemas": [schema("target")], "fields": [root(&[c]), in_force], "projection": "document" }), + ), + ( + vec!["rulings", c, "eureka-body"], + json!({ "schemas": [schema("ruling")], "fields": [root(&[c, "eureka-body"]), in_force] }), + ), + ( + vec!["open", c], + json!({ "schemas": [schema("question"), schema("follow_up")], "fields": [root(&[c]), in_force] }), + ), + ( + vec!["findings", c], + json!({ + "schemas": [schema("finding")], + "fields": [root(&[c]), in_force, { "index": "faculty", "op": "any_of", "values": ["Soul"] }], + }), + ), + ( + vec!["findings", c, "--blocking"], + json!({ + "schemas": [schema("finding")], + "fields": [ + root(&[c]), + in_force, + { "index": "faculty", "op": "any_of", "values": ["Soul"] }, + { "index": "severity", "op": "any_of", "values": ["Blocker", "High"] }, + ], + }), + ), + ( + vec!["unreported", c], + json!({ + "schemas": [schema("cut_spec")], + "fields": [root(&[c]), in_force], + "cited": { "role": "cut_spec", "exists": false }, + }), + ), + ( + vec!["blocked", "eureka-substrate:cut_spec:cut-x.r1"], + json!({ + "schemas": [schema("question")], + "fields": [in_force], + "cites": { + "target": { "schemaId": schema("cut_spec"), "recordKey": "eureka-substrate:cut_spec:cut-x.r1" }, + "role": "raised_in", + }, + }), + ), + ( + vec!["unjudged", c], + json!({ + "schemas": [schema("cut_report")], + "fields": [root(&[c])], + "cited": { "role": "cut_report", "exists": false }, + }), + ), + ( + vec!["history", "eureka-substrate:ruling:R1"], + json!({ + "schemas": [schema("resolution")], + "cites": { "target": { "schemaId": schema("ruling"), "recordKey": "eureka-substrate:ruling:R1" }, "role": "subject" }, + "descending": true, + }), + ), + ( + vec!["cut", c, "huginn-cli"], + json!({ + "schemas": [schema("cut_spec"), schema("cut_report"), schema("verdict"), schema("finding"), schema("resolution")], + "fields": [root(&[c]), { "index": "cut", "op": "any_of", "values": ["huginn-cli"] }], + }), + ), + ( + vec!["ledger", c], + json!({ "schemas": [schema("cut_spec"), schema("cut_report")], "fields": [root(&[c])], "projection": "document" }), + ), + ( + vec!["precedent", c, "the question in plain words"], + json!({ "schemas": [schema("ruling"), schema("resolution"), schema("finding")], "fields": [root(&[c])] }), + ), + ( + vec!["gaps"], + json!({ "schemas": [schema("follow_up")], "fields": [root(&["eureka-substrate"]), in_force] }), + ), + ]; + for (args, literal) in cases { + let (selection, semantic) = sent(&args); + assert_eq!(selection, page_literal(literal), "{args:?}"); + let expected = (args[0] == "precedent").then(|| ("the question in plain words".to_string(), 10)); + assert_eq!(semantic, expected, "{args:?}"); + } +} + +#[test] +fn paging_and_query_flags_shape_the_selection() { + let (selection, semantic) = sent(&["gaps", "--cursor", "abc", "--documents"]); + assert_eq!(selection.cursor.as_deref(), Some("abc")); + assert_eq!(selection.projection, "document"); + assert_eq!(selection.limit, Some(50)); + assert_eq!(semantic, None); + + let (selection, _) = sent(&["gaps"]); + assert_eq!(selection.cursor, None); + assert_eq!(selection.projection, "header"); + + let (selection, semantic) = sent(&["query", "{}", "--near", "drift", "--top-k", "7"]); + assert_eq!(selection, page_literal(json!({}))); + assert_eq!(semantic, Some(("drift".to_string(), 7))); + let (_, semantic) = sent(&["query", "{}", "--near", "drift"]); + assert_eq!(semantic, Some(("drift".to_string(), 10))); + + let (selection, _) = sent(&["query", r#"{"limit": 5, "descending": true}"#]); + assert_eq!(selection.limit, Some(5)); + assert!(selection.descending); + let (selection, _) = sent(&["query", r#"{"projection": "header"}"#, "--documents"]); + assert_eq!(selection.projection, "document"); + + let ran = at(closed_port(), &["query", "{}", "--top-k", "3"], None); + assert_eq!(ran.code, 2, "--top-k needs --near"); + + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "selection.json", &json!({ "schemas": ["epiphany.pipeline.campaign.v2"] })); + let (selection, _) = sent(&["query", &format!("@{file}")]); + assert_eq!(selection.schemas, Some(vec!["epiphany.pipeline.campaign.v2".to_string()])); + let (server, seen) = recording(); + let ran = at(server.addr, &["query", "-"], Some(r#"{"keys": ["a:campaign:self"]}"#)); + assert_eq!(ran.code, 0, "{}", ran.err); + let seen = seen.lock().unwrap(); + let [HuginnMindRequest::Query { selection, .. }] = &seen[..] else { panic!("{seen:?}") }; + assert_eq!(selection.keys, Some(vec!["a:campaign:self".to_string()])); +} + +#[test] +fn recipes_list_what_the_mind_holds() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let campaign = write(&dir, "campaign.json", &json!([campaign_json()])); + let ran = at(server.addr, &admit_args(&campaign), None); + assert_eq!(ran.code, 0, "{}", ran.err); + let specs = write(&dir, "specs.json", &json!([spec("A"), spec("B")])); + let ran = at(server.addr, &admit_args(&specs), None); + assert_eq!(ran.code, 0, "{}", ran.err); + + let unreported = at(server.addr, &["unreported", CAMPAIGN], None); + assert_eq!(unreported.code, 0, "{}", unreported.err); + let mut lines: Vec<&str> = unreported.out.lines().collect(); + assert_eq!(lines.pop().unwrap().split(' ').take(2).collect::>(), ["matched", "2"]); + assert_eq!(lines.len(), 2); + + let reports = write(&dir, "report.json", &json!([report("B")])); + let ran = at(server.addr, &admit_args(&reports), None); + assert_eq!(ran.code, 0, "{}", ran.err); + + let unreported = at(server.addr, &["unreported", CAMPAIGN], None); + let lines: Vec<&str> = unreported.out.lines().collect(); + assert_eq!(lines.len(), 2, "{}", unreported.out); + let tokens: Vec<&str> = lines[0].split(' ').collect(); + let id = format!("{CAMPAIGN}:cut_spec:cut-A.r1"); + assert_eq!(tokens[..5], [id.as_str(), "InForce", "Hands", "A", "cut"]); + for fact in ["cut=A", "repo=GameCult/Epiphany", "revision=1", "base=5f98228d", "branch=codex/eureka-pipeline-state"] { + assert!(tokens.contains(&fact), "{fact}: {}", lines[0]); + } + assert!(lines[1].starts_with("matched 1 as_of "), "{}", lines[1]); + assert!(lines[1].ends_with(" next -"), "{}", lines[1]); + assert!(!unreported.out.contains("cut-B.r1"), "{}", unreported.out); + + let unjudged = at(server.addr, &["unjudged", CAMPAIGN], None); + assert!(unjudged.out.contains(&format!("{CAMPAIGN}:cut_report:cut-B.h1")), "{}", unjudged.out); + assert!(unjudged.out.contains("matched 1 "), "{}", unjudged.out); + + let campaigns = at(server.addr, &["campaigns"], None); + assert!(campaigns.out.starts_with(&format!("{CAMPAIGN}:campaign:self InForce Hands Eureka pipeline state repos={REPO}\n")), "{}", campaigns.out); + + let whole = at(server.addr, &["ledger", CAMPAIGN], None); + assert_eq!(whole.code, 0, "{}", whole.err); + assert_eq!(whole.out.matches("admitted ").count(), 3, "{}", whole.out); + assert!(!whole.out.starts_with('\n'), "{}", whole.out); + assert_eq!(whole.out.matches("\n\n").count(), 2, "documents are separated by one blank line: {}", whole.out); + + let documents = at(server.addr, &["campaigns", "--documents"], None); + assert!(documents.out.contains("\nadmitted "), "{}", documents.out); + assert!(documents.out.contains("\"kind\": \"campaign\""), "{}", documents.out); +} + +#[test] +fn a_long_header_is_cut() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let mut doc = campaign_json(); + doc["value"]["title"] = json!("t".repeat(200)); + doc["value"]["working_branch"] = json!("b"); + let file = write(&dir, "long.json", &json!([doc])); + assert_eq!(at(server.addr, &admit_args(&file), None).code, 0); + let ran = at(server.addr, &["campaigns"], None); + let header = ran.out.lines().next().unwrap(); + assert_eq!(header.chars().count(), 240); +} + +#[test] +fn a_resolved_document_shows_its_closing_record() { + let server = live(); + let dir = tempfile::tempdir().unwrap(); + let question = json!({ + "kind": "question", + "value": { + "campaign": CAMPAIGN, + "label": "Q1", + "title": "Who owns the state?", + "question": "Who owns the state?", + "options": [{ "label": "A", "text": "an instance" }, { "label": "B", "text": "a repo" }], + "recommended": "A", + "depends": [], + "raised_in": null, + "asked_on": "2026-10-10", + }, + }); + let setup = write(&dir, "setup.json", &json!([campaign_json(), question])); + let ran = at(server.addr, &admit_args(&setup), None); + assert_eq!(ran.code, 0, "{}{}", ran.out, ran.err); + let resolution = json!({ + "kind": "resolution", + "value": { + "subject": { "kind": "Question", "id": format!("{CAMPAIGN}:question:Q1") }, + "sequence": 1, + "outcome": { "Withdrawn": { "reason": "moot" } }, + "rationale": "Resolved.", + "resolved_on": "2026-10-10", + }, + }); + let closing = write(&dir, "closing.json", &json!([resolution])); + let ran = at(server.addr, &admit_args(&closing), None); + assert_eq!(ran.code, 0, "{}{}", ran.out, ran.err); + + let id = format!("{CAMPAIGN}:question:Q1"); + let closer = format!("{CAMPAIGN}:resolution:question.Q1.n1"); + let viewed = at(server.addr, &["view", &id], None); + assert_eq!(viewed.out.lines().next().unwrap(), format!("{id} Resolved Withdrawn by {closer}")); + + let history = at(server.addr, &["history", &id], None); + assert_eq!(history.code, 0, "{}", history.err); + assert!(history.out.starts_with(&format!("{closer} InForce Hands ")), "{}", history.out); + assert!(history.out.contains("sequence=1"), "{}", history.out); + + let open = at(server.addr, &["open", CAMPAIGN], None); + assert!(open.out.contains("matched 0 "), "a resolved question is not open: {}", open.out); + + let header = at(server.addr, &["query", r#"{"schemas": ["epiphany.pipeline.question.v2"]}"#], None); + assert!(header.out.starts_with(&format!("{id} Resolved:Withdrawn Hands Who owns the state? ")), "{}", header.out); + assert!(header.out.contains("options=A,B") && header.out.contains("recommended=A"), "{}", header.out); +} + +#[test] +fn schema_prints_the_published_files() { + let manifest = Path::new(env!("CARGO_MANIFEST_DIR")); + for kind in ["cut_spec", "campaign", "hand_off", "run"] { + let ran = run(&[], &["schema", kind], None); + assert_eq!(ran.code, 0); + let published = std::fs::read_to_string(manifest.join(format!("../../schemas/cultnet/epiphany.pipeline.{kind}.v2.schema.json"))).unwrap(); + assert_eq!(ran.out, published, "{kind}"); + } + let selection = run(&[], &["schema", "selection"], None); + assert_eq!(selection.out, std::fs::read_to_string(manifest.join("schemas/cultnet.selection.schema.json")).unwrap()); + let names = run(&[], &["schema"], None); + assert_eq!(names.code, 0); + let names: Vec<&str> = names.out.lines().collect(); + assert_eq!(names.len(), 15, "{names:?}"); + assert_eq!(names[0], "campaign"); + assert_eq!(names[14], "selection"); + for kind in PipelineKind::ALL { + assert!(names.contains(&kind.name()), "{}", kind.name()); + } + let unknown = run(&[], &["schema", "no-such-kind"], None); + assert_eq!(unknown.code, 2); + assert!(unknown.err.starts_with("InvalidInput: "), "{}", unknown.err); +} + +#[test] +fn help_is_the_schema_surface() { + let rulings = run(&[], &["rulings", "--help"], None); + assert_eq!(rulings.code, 0); + let (_, printed) = rulings.out.split_once("selection:\n").expect("the selection is in the help"); + let selection: Value = serde_json::from_str(printed.trim()).unwrap(); + assert_eq!( + selection, + json!({ + "schemas": ["epiphany.pipeline.ruling.v2"], + "fields": [ + { "index": "root", "op": "any_of", "values": [""] }, + { "index": "in_force", "op": "any_of", "values": ["true"] }, + ], + }) + ); + let history = run(&[], &["history", "--help"], None); + assert!(history.out.contains("epiphany.pipeline..v2"), "{}", history.out); + let findings = run(&[], &["findings", "--help"], None); + assert!(findings.out.contains("\"severity\"") && findings.out.contains("Blocker"), "{}", findings.out); + let precedent = run(&[], &["precedent", "--help"], None); + assert!(precedent.out.contains("\"top_k\": 10"), "{}", precedent.out); + let admit = run(&[], &["admit", "--help"], None); + let admit_text = admit.out.split_whitespace().collect::>().join(" "); + assert!(admit_text.contains("{\"kind\": , \"value\": {...}}"), "{admit_text}"); + assert!(admit_text.contains("exit 5"), "{admit_text}"); + + let version = run(&[], &["--version"], None); + assert_eq!(version.code, 0); + let sha = option_env!("HUGINN_BUILD_SHA").unwrap_or("unknown"); + assert_eq!(version.out, format!("huginn {} ({sha})\n", env!("CARGO_PKG_VERSION"))); +} + +#[test] +fn every_recipe_has_help() { + for recipe in [ + "campaigns", "target", "rulings", "open", "findings", "unreported", "blocked", "unjudged", "history", "cut", "ledger", + "precedent", "gaps", + ] { + let ran = run(&[], &[recipe, "--help"], None); + assert_eq!(ran.code, 0, "{recipe}"); + assert!(ran.out.contains("epiphany.pipeline."), "{recipe}: {}", ran.out); + assert!(ran.out.contains("--cursor"), "{recipe}: {}", ran.out); + } +} + +#[test] +fn a_conflicting_batch_is_the_minds_no() { + let conflict = scripted(|message| { + let (_, request) = decode_request(message).expect("a mind request"); + assert!(matches!(request, HuginnMindRequest::Admit(_))); + answer( + "admit", + &HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { + identities: vec![PipelineRef { kind: PipelineKind::Campaign, id: Short(format!("{CAMPAIGN}:campaign:self")) }], + }), + ) + }); + let dir = tempfile::tempdir().unwrap(); + let file = write(&dir, "campaign.json", &json!([campaign_json()])); + let ran = at(conflict.addr, &admit_args(&file), None); + assert_eq!(ran.code, 1); + assert_eq!(ran.out, format!("Conflict\nconflicts {CAMPAIGN}:campaign:self\n")); +} diff --git a/crates/huginn-mind/src/persona.rs b/crates/huginn-mind/src/persona.rs index 2742120..a7677a9 100644 --- a/crates/huginn-mind/src/persona.rs +++ b/crates/huginn-mind/src/persona.rs @@ -1,585 +1,585 @@ -//! The persona document: one `gamecult.persona_state.v0` per mind, stored -//! opaque and replaced whole. -//! -//! The shape is the published schema's, `schemas/cultnet/`, read here with -//! `include_bytes!`; the mind holds no Rust type for it, only the value that -//! passed the schema. `put_persona` (admission.rs) owns whether a document may -//! enter; this module owns what it is checked against and how it is stored and -//! read back. Nothing here echoes a caller's value: a refusal names a schema -//! location and a keyword, never the text that failed. - -use std::collections::BTreeSet; -use std::sync::OnceLock; - -use cultcache_rs::{CultCacheEnvelope, DatabaseEntry}; -use jsonschema::paths::LocationSegment; -use jsonschema::error::ValidationErrorKind; -use jsonschema::Validator; -use schemars::JsonSchema; -use serde::{Deserialize, Serialize}; -use serde_json::Value; - -use crate::mind::Mind; -use crate::refusal::MindRefusal; -use crate::store::MindStore; - -const PERSONA_SCHEMA: &[u8] = include_bytes!("../../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); - -/// The stored envelope's payload: the document, one slot, keyed by the mind's -/// instance. The cache needs a registered entry type to hold the envelope; the -/// document inside stays a value. -#[derive(Clone, Debug, PartialEq, DatabaseEntry)] -#[cultcache(type = "gamecult.persona_state.v0", schema = "HuginnPersonaEntry")] -pub struct HuginnPersonaEntry { - #[cultcache(key = 0)] - pub value: Value, -} - -/// What `PersonaGet` answers: the stored document, its `updatedAt`, and the -/// receipt of the put that wrote it. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub struct PersonaStateView { - pub value: Value, - pub updated_at: String, - pub receipt_id: String, -} - -/// How a put ended. A refusal is an answer, as for `admit`. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum PersonaPutOutcome { - Committed { receipt_id: String }, - Refused(MindRefusal), -} - -struct Compiled { - validator: Validator, - /// Every property name the schema declares. A path segment outside this - /// set is a caller's key (`traitMap` keys are free), so it is withheld. - declared: BTreeSet, -} - -fn compiled() -> Result<&'static Compiled, MindRefusal> { - static COMPILED: OnceLock> = OnceLock::new(); - COMPILED - .get_or_init(|| { - let schema: Value = serde_json::from_slice(PERSONA_SCHEMA) - .map_err(|error| format!("the published persona schema does not parse: {error}"))?; - let validator = jsonschema::draft7::new(&schema) - .map_err(|error| format!("the published persona schema does not compile: {error}"))?; - let mut declared = BTreeSet::new(); - declared_names(&schema, &mut declared); - Ok(Compiled { validator, declared }) - }) - .as_ref() - .map_err(|detail| MindRefusal::Unavailable { detail: detail.clone() }) -} - -fn declared_names(node: &Value, names: &mut BTreeSet) { - match node { - Value::Object(map) => { - if let Some(Value::Object(properties)) = map.get("properties") { - names.extend(properties.keys().cloned()); - } - map.values().for_each(|child| declared_names(child, names)); - } - Value::Array(items) => items.iter().for_each(|child| declared_names(child, names)), - _ => {} - } -} - -/// Rule 1: the document is valid against the published schema. The first -/// failure is the refusal; it names where and which keyword, never the value. -pub(crate) fn validate_shape(state: &Value) -> Result<(), MindRefusal> { - let compiled = compiled()?; - let Err(error) = compiled.validator.validate(state) else { return Ok(()) }; - let mut path = error - .instance_path() - .segments() - .map(|segment| match segment { - LocationSegment::Index(index) => index.to_string(), - LocationSegment::Property(name) if compiled.declared.contains(name.as_ref()) => name.into_owned(), - LocationSegment::Property(_) => "*".to_string(), - }) - .collect::>(); - match error.kind() { - ValidationErrorKind::Required { property } => path.extend(property.as_str().map(str::to_string)), - ValidationErrorKind::AdditionalProperties { .. } => path.push("*".to_string()), - _ => {} - } - Err(MindRefusal::PersonaInvalid { - path: format!("/{}", path.join("/")), - message: format!("fails the published schema's {} rule", error.kind().keyword()), - }) -} - -/// A stored persona envelope's document. -pub(crate) fn decode(envelope: &CultCacheEnvelope) -> Result { - rmp_serde::from_slice::(&envelope.payload) - .map(|entry| entry.value) - .map_err(|error| MindRefusal::Unavailable { detail: format!("the stored persona does not decode: {error}") }) -} - -/// A document's `updatedAt`; the schema makes it a required string. -pub(crate) fn updated_at(value: &Value) -> Option<&str> { - value.get("updatedAt").and_then(Value::as_str) -} - -impl Mind { - /// This mind's persona envelope, if one is stored. - pub(crate) fn persona_envelope(&self) -> Option<&CultCacheEnvelope> { - self.raw_envelope(HuginnPersonaEntry::TYPE, &self.instance().0) - } - - /// The stored `updatedAt`; none when no persona is stored. - pub(crate) fn stored_updated_at(&self) -> Result, MindRefusal> { - let Some(envelope) = self.persona_envelope() else { return Ok(None) }; - let value = decode(envelope)?; - updated_at(&value) - .map(|stamp| Some(stamp.to_string())) - .ok_or_else(|| MindRefusal::Unavailable { detail: "the stored persona has no updatedAt".into() }) - } - - /// `PersonaGet`: the document, its `updatedAt` and the receipt of the put - /// that wrote exactly these bytes. - pub fn persona(&self) -> Result, MindRefusal> { - let Some(envelope) = self.persona_envelope() else { return Ok(None) }; - let value = decode(envelope)?; - let integrity = |detail: &str| MindRefusal::Unavailable { detail: detail.into() }; - let updated_at = updated_at(&value).ok_or_else(|| integrity("the stored persona has no updatedAt"))?.to_string(); - let identity = (envelope.r#type.as_str(), envelope.key.as_str()); - let receipt_id = self - .receipts()? - .into_iter() - .filter(|receipt| receipt.writes.iter().any(|write| write.identity() == identity)) - .max_by_key(|receipt| receipt.ordinal) - .ok_or_else(|| integrity("the stored persona has no receipt"))? - .receipt_id; - Ok(Some(PersonaStateView { value, updated_at, receipt_id })) - } -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::fixtures::{INSTANCE, OTHER_INSTANCE, epoch, instance, opened, prepare, provenance, seed, slug}; - use crate::receipt::Faculty; - use crate::store::test_stores::{MemoryStore, RefusingStore, SwapCommand}; - use eureka_pipeline::PipelineKind; - use serde_json::json; - - const T1: &str = "2026-10-10T10:00:00Z"; - const T2: &str = "2026-10-10T10:00:01Z"; - const T3: &str = "2026-10-10T10:00:02Z"; - const CANARY: &str = "CANARY-7f3a91-do-not-echo"; - const NOT_LATER: &str = "must be later than the stored updatedAt"; - - /// A minimal document the published schema accepts. The test that follows - /// holds it to the schema file's own required list. - fn persona(id: &str, updated_at: &str) -> Value { - let traits = json!({ - "underlyingOrganization": {}, "stableDispositions": {}, "behavioralDimensions": {}, - "presentationStrategy": {}, "voiceStyle": {}, "situationalState": {} - }); - json!({ - "schemaVersion": "gamecult.persona_state.v0", - "provenance": { - "sourceSystem": "huginn", "sourceDocumentId": id, "sourceUpdatedAt": updated_at, - "exportedAt": updated_at, "authority": "canonical" - }, - "personaId": id, - "publicName": "Test Persona", - "presentation": { "voiceSummary": "plain" }, - "activationProfile": traits, - "thoughtMemory": { "shortTerm": [], "memories": [], "incubation": [] }, - "agencyPressure": { "pressures": [] }, - "candidateActions": { "actions": [] }, - "affect": { - "needs": [], "socialBonds": [], "statusReads": [], "moodDimensions": [], - "socialBiases": [], "doctrineStances": [] - }, - "updatedAt": updated_at - }) - } - - fn schema_file() -> Value { - let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); - serde_json::from_slice(&std::fs::read(path).unwrap()).unwrap() - } - - fn put(mind: &mut Mind, state: Value, expected: Option<&str>) -> PersonaPutOutcome { - let instance = mind.instance().clone(); - mind.put_persona(&instance, state, expected.map(str::to_string), provenance(Faculty::Hands), crate::fixtures::now()) - } - - fn committed(outcome: PersonaPutOutcome) -> String { - match outcome { - PersonaPutOutcome::Committed { receipt_id } => receipt_id, - other => panic!("expected a commit, got {other:?}"), - } - } - - fn refused(outcome: PersonaPutOutcome) -> MindRefusal { - match outcome { - PersonaPutOutcome::Refused(refusal) => refusal, - other => panic!("expected a refusal, got {other:?}"), - } - } - - fn invalid(path: &str, rule: &str) -> MindRefusal { - MindRefusal::PersonaInvalid { path: path.into(), message: format!("fails the published schema's {rule} rule") } - } - - fn not_later() -> MindRefusal { - MindRefusal::PersonaInvalid { path: "/updatedAt".into(), message: NOT_LATER.into() } - } - - fn stale(stored: Option<&str>) -> MindRefusal { - MindRefusal::PersonaStale { stored: stored.map(str::to_string) } - } - - fn seeded_over(store: &MemoryStore) -> Mind { - let mut mind = opened(store.clone(), INSTANCE); - seed(&mut mind); - mind - } - - fn persona_in_status(mind: &Mind) -> crate::wire::PersonaStatus { - mind.status(crate::wire::IndexStatus::Current).persona - } - - #[test] - fn the_fixture_is_valid_against_the_published_file_and_covers_its_required_fields() { - let schema = schema_file(); - let validator = jsonschema::draft7::new(&schema).unwrap(); - let document = persona(INSTANCE, T1); - assert!(validator.is_valid(&document)); - for name in schema["required"].as_array().unwrap() { - assert!(document.get(name.as_str().unwrap()).is_some(), "the fixture lacks {name}"); - } - } - - #[test] - fn declared_names_are_every_property_name_at_any_depth() { - let schema = json!({ - "properties": { "a": { "properties": { "b": {} } } }, - "allOf": [{ "properties": { "c": {} } }], - "definitions": { "d": { "properties": { "e": {} } } }, - "required": ["not-a-property"] - }); - let mut names = BTreeSet::new(); - declared_names(&schema, &mut names); - assert_eq!(names, BTreeSet::from(["a", "b", "c", "e"].map(String::from))); - } - - /// `identity-write-all-visible`: a put may change any field, the identity - /// fields included, and a change the next second is no less admissible. - #[test] - fn a_put_may_rewrite_identity_fields_and_every_change_lands() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - committed(put(&mut mind, persona(INSTANCE, T1), None)); - - let mut renamed = persona(INSTANCE, T2); - renamed["publicName"] = json!("A New Name"); - renamed["publicDescription"] = json!("who she says she is"); - renamed["presentation"] = json!({ "voiceSummary": "warmer", "pronouns": "she/her" }); - renamed["values"] = json!([{ "id": "v1", "label": "candor", "priority": 0.9 }]); - committed(put(&mut mind, renamed.clone(), Some(T1))); - assert_eq!(mind.persona().unwrap().unwrap().value, renamed); - - let mut again = persona(INSTANCE, T3); - again["publicName"] = json!("Another Name"); - committed(put(&mut mind, again.clone(), Some(T2))); - assert_eq!(mind.persona().unwrap().unwrap().value, again); - } - - #[test] - fn the_view_names_the_receipt_of_the_latest_put() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let mut previous: Option = None; - for second in 0..5 { - let stamp = format!("2026-10-10T10:00:0{second}Z"); - let receipt = committed(put(&mut mind, persona(INSTANCE, &stamp), previous.as_deref())); - assert_eq!(mind.persona().unwrap().unwrap().receipt_id, receipt, "after put {second}"); - previous = Some(stamp); - } - } - - #[test] - fn a_persona_document_is_validated_at_the_door() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let before = store.rows(); - - for name in schema_file()["required"].as_array().unwrap() { - let name = name.as_str().unwrap(); - let mut document = persona(INSTANCE, T1); - document.as_object_mut().unwrap().remove(name); - assert_eq!(refused(put(&mut mind, document, None)), invalid(&format!("/{name}"), "required"), "{name}"); - } - - let mut extra = persona(INSTANCE, T1); - extra["notInTheSchema"] = json!(1); - assert_eq!(refused(put(&mut mind, extra, None)), invalid("/*", "additionalProperties")); - - let mut wrong_type = persona(INSTANCE, T1); - wrong_type["publicName"] = json!(5); - assert_eq!(refused(put(&mut mind, wrong_type, None)), invalid("/publicName", "type")); - - let mut bad_stamp = persona(INSTANCE, T1); - bad_stamp["updatedAt"] = json!("yesterday"); - assert_eq!(refused(put(&mut mind, bad_stamp, None)), invalid("/updatedAt", "format")); - - let mut nested = persona(INSTANCE, T1); - nested["thoughtMemory"]["memories"] = json!([7]); - assert_eq!(refused(put(&mut mind, nested, None)), invalid("/thoughtMemory/memories/0", "type")); - - let mut free_key = persona(INSTANCE, T1); - free_key["activationProfile"]["voiceStyle"]["any-key"] = json!({}); - assert_eq!( - refused(put(&mut mind, free_key, None)), - invalid("/activationProfile/voiceStyle/*/mean", "required"), - "a key the schema does not declare is withheld from the path" - ); - - assert_eq!(store.rows(), before, "no refusal wrote anything"); - assert_eq!(mind.persona().unwrap(), None); - } - - #[test] - fn a_refusal_never_echoes_what_the_caller_sent() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - committed(put(&mut mind, persona(INSTANCE, T2), None)); - - let mut free_key = persona(INSTANCE, T3); - free_key["activationProfile"]["voiceStyle"][CANARY] = json!({}); - let mut extra_key = persona(INSTANCE, T3); - extra_key[CANARY] = json!(CANARY); - let mut bad_value = persona(INSTANCE, T3); - bad_value["updatedAt"] = json!(CANARY); - let mut bad_enum = persona(INSTANCE, T3); - bad_enum["provenance"]["authority"] = json!(CANARY); - let mut foreign = persona(CANARY, T3); - foreign["publicName"] = json!(CANARY); - let mut imported = persona(INSTANCE, T3); - imported["provenance"]["authority"] = json!("import"); - imported["provenance"]["sourceSystem"] = json!(CANARY); - let mut late = persona(INSTANCE, T1); - late["publicName"] = json!(CANARY); - - let cases: Vec<(Value, Option<&str>)> = vec![ - (free_key, Some(T2)), - (extra_key, Some(T2)), - (bad_value, Some(T2)), - (bad_enum, Some(T2)), - (foreign, Some(T2)), - (imported, Some(T2)), - (late, Some(T2)), - (persona(INSTANCE, T3), Some(CANARY)), - ]; - for (document, expected) in cases { - let refusal = refused(put(&mut mind, document, expected)); - assert!(!format!("{refusal:?}").contains(CANARY), "{refusal:?}"); - assert!(!serde_json::to_string(&refusal).unwrap().contains(CANARY)); - } - } - - #[test] - fn persona_id_must_be_the_instance() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let before = store.rows(); - let refusal = refused(put(&mut mind, persona(OTHER_INSTANCE, T1), None)); - assert_eq!(refusal, MindRefusal::PersonaForeign { instance: INSTANCE.into() }); - assert_eq!(store.rows(), before); - assert_eq!(mind.persona().unwrap(), None); - } - - #[test] - fn only_a_canonical_document_is_the_minds_persona() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - for authority in ["projection", "import"] { - let mut document = persona(INSTANCE, T1); - document["provenance"]["authority"] = json!(authority); - assert_eq!(refused(put(&mut mind, document, None)), MindRefusal::PersonaNotCanonical, "{authority}"); - } - assert_eq!(mind.persona().unwrap(), None); - } - - #[test] - fn a_persona_waits_for_the_minds_identity() { - let mut mind = opened(MemoryStore::new(), INSTANCE); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), None)), MindRefusal::MissingIdentity); - assert!(mind.is_empty()); - } - - #[test] - fn a_put_must_name_this_mind_and_a_named_asker() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let before = store.rows(); - let other = slug(OTHER_INSTANCE); - let outcome = mind.put_persona(&other, persona(INSTANCE, T1), None, provenance(Faculty::Hands), crate::fixtures::now()); - assert!(matches!(refused(outcome), MindRefusal::ForeignInstance { .. })); - let mut unnamed = provenance(Faculty::Hands); - unnamed.agent = eureka_pipeline::Short(" ".into()); - let instance = mind.instance().clone(); - let outcome = mind.put_persona(&instance, persona(INSTANCE, T1), None, unnamed, crate::fixtures::now()); - assert!(matches!(refused(outcome), MindRefusal::Document(_))); - assert_eq!(store.rows(), before); - } - - #[test] - fn a_put_is_a_compare_and_swap_on_updated_at() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Absent); - let receipts = |mind: &Mind| mind.receipts().unwrap().len(); - let base = receipts(&mind); - - // A first put expects nothing; claiming a stored document is stale. - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T1))), stale(None)); - let first = committed(put(&mut mind, persona(INSTANCE, T1), None)); - assert_eq!(receipts(&mind), base + 1); - let view = mind.persona().unwrap().unwrap(); - assert_eq!((view.updated_at.as_str(), view.receipt_id.as_str()), (T1, first.as_str())); - assert_eq!(view.value, persona(INSTANCE, T1)); - assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); - - // Two puts that read the same stored document: the second loses. - let second = committed(put(&mut mind, persona(INSTANCE, T2), Some(T1))); - assert_eq!(receipts(&mind), base + 2); - let rows = store.rows(); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), Some(T1))), stale(Some(T2))); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), None)), stale(Some(T2))); - assert_eq!(store.rows(), rows, "a stale put wrote nothing"); - - // The right expectation with an updatedAt that is not later. - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T2))), not_later()); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T2))), not_later()); - // Instants compare, not spellings: the same instant at another offset is not later. - assert_eq!(refused(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:01+02:00"), Some(T2))), not_later()); - assert_eq!(store.rows(), rows); - assert_eq!(receipts(&mind), base + 2); - committed(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:02+02:00"), Some(T2))); - assert_eq!(receipts(&mind), base + 3); - - // The second put's receipt read the first document and wrote the second. - let receipt = mind.receipts().unwrap().into_iter().find(|receipt| receipt.receipt_id == second).unwrap(); - assert_eq!((receipt.strong_reads.len(), receipt.writes.len()), (1, 1)); - assert_eq!(receipt.strong_reads[0].document_key, INSTANCE); - assert_ne!(receipt.strong_reads[0].payload_msgpack, receipt.writes[0].payload_msgpack); - assert_eq!(receipt.provenance, provenance(Faculty::Hands)); - } - - #[test] - fn a_put_whose_swap_is_lost_is_stale_and_changes_nothing() { - let store = RefusingStore::new(); - let mut mind = opened(store.clone(), INSTANCE); - seed(&mut mind); - committed(put(&mut mind, persona(INSTANCE, T1), None)); - let rows = store.rows(); - store.command(SwapCommand::Lose); - assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T1))), stale(Some(T1))); - assert_eq!(store.rows(), rows); - } - - #[test] - fn the_persona_is_not_a_pipeline_document_and_a_batch_cannot_carry_it() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - let documents = mind.status(crate::wire::IndexStatus::Current).documents; - committed(put(&mut mind, persona(INSTANCE, T1), None)); - assert_eq!(mind.status(crate::wire::IndexStatus::Current).documents, documents); - assert!(PipelineKind::ALL.iter().all(|kind| kind.type_id() != HuginnPersonaEntry::TYPE)); - let forged = mind.persona_envelope().unwrap().clone(); - let instance = mind.instance().clone(); - let outcome = mind.admit_prepared(&instance, provenance(Faculty::Hands), vec![forged], crate::fixtures::now()); - assert!(matches!(outcome, crate::admission::PipelineAdmissionOutcome::Refused(_)), "{outcome:?}"); - } - - #[test] - fn one_persona_per_mind_and_the_store_still_opens() { - let yggdrasil = slug(INSTANCE); - let cache = crate::mind::schema_cache().unwrap(); - let entry = |key: &str, value: Value| cache.prepare_entry_named(key, &HuginnPersonaEntry { value }).unwrap().0; - let planted = |rows: Vec| { - let store = MemoryStore::new(); - rows.into_iter().for_each(|row| store.plant(row)); - store - }; - let base = || vec![epoch(), prepare(&instance(INSTANCE))]; - - // A store written before this type existed opens unchanged. - assert!(Mind::open_with(planted(base()), &yggdrasil).is_ok()); - - // One persona opens; a planted row has no writing receipt, so the door and the status both call it unreadable. - let mut with_one = base(); - with_one.push(entry(INSTANCE, persona(INSTANCE, T1))); - let mind = Mind::open_with(planted(with_one.clone()), &yggdrasil).unwrap(); - assert_eq!(mind.envelopes().len(), 3); - assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Unreadable); - assert!(mind.persona().is_err()); - - // Two are no mind's. - with_one.push(entry("second", persona(INSTANCE, T2))); - assert_eq!( - Mind::open_with(planted(with_one), &yggdrasil).err(), - Some(MindRefusal::ForeignStore { r#type: HuginnPersonaEntry::TYPE.into() }) - ); - // The opener still refuses a type that is not one of the seventeen. - let mut stranger = base(); - let mut foreign = entry(INSTANCE, persona(INSTANCE, T1)); - foreign.r#type = "gamecult.persona_state.v1".into(); - stranger.push(foreign); - assert!(matches!(Mind::open_with(planted(stranger), &yggdrasil).err(), Some(MindRefusal::ForeignStore { .. }))); - } - - /// Status answers in the door's own terms: a stored persona the door - /// cannot read is `Unreadable`, not the `Absent` of a mind with none, while - /// `PersonaGet` answers `Unavailable` for the same bytes. - #[test] - fn status_says_unreadable_where_the_door_says_unavailable() { - let yggdrasil = slug(INSTANCE); - let cache = crate::mind::schema_cache().unwrap(); - let readable = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: persona(INSTANCE, T1) }).unwrap().0; - let no_stamp = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: json!({}) }).unwrap().0; - let mut undecodable = readable.clone(); - undecodable.payload = vec![0xc1]; - // Planted rows have no writing receipt: the door cannot read them, so neither may the status. - for (row, status) in [ - (readable, crate::wire::PersonaStatus::Unreadable), - (no_stamp, crate::wire::PersonaStatus::Unreadable), - (undecodable, crate::wire::PersonaStatus::Unreadable), - ] { - let store = MemoryStore::new(); - store.plant(epoch()); - store.plant(prepare(&instance(INSTANCE))); - store.plant(row); - let mind = Mind::open_with(store, &yggdrasil).unwrap(); - assert_eq!(persona_in_status(&mind), status); - assert!(matches!(mind.persona(), Err(MindRefusal::Unavailable { .. })), "the door answers what the status says"); - } - // A row a put wrote: status and door agree it is stored, with one stamp. - let store = MemoryStore::new(); - let mut written = seeded_over(&store); - committed(put(&mut written, persona(INSTANCE, T1), None)); - assert_eq!(persona_in_status(&written), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); - assert_eq!(written.persona().unwrap().unwrap().updated_at, T1); - assert_eq!(persona_in_status(&seeded_over(&MemoryStore::new())), crate::wire::PersonaStatus::Absent); - } - - #[test] - fn the_stored_bytes_are_the_one_slot_array_the_catalogue_describes() { - let store = MemoryStore::new(); - let mut mind = seeded_over(&store); - committed(put(&mut mind, persona(INSTANCE, T1), None)); - let envelope = mind.persona_envelope().unwrap(); - assert_eq!((envelope.r#type.as_str(), envelope.key.as_str()), ("gamecult.persona_state.v0", INSTANCE)); - let slots: (Value,) = rmp_serde::from_slice(&envelope.payload).unwrap(); - assert_eq!(slots.0, persona(INSTANCE, T1)); - } -} +//! The persona document: one `gamecult.persona_state.v0` per mind, stored +//! opaque and replaced whole. +//! +//! The shape is the published schema's, `schemas/cultnet/`, read here with +//! `include_bytes!`; the mind holds no Rust type for it, only the value that +//! passed the schema. `put_persona` (admission.rs) owns whether a document may +//! enter; this module owns what it is checked against and how it is stored and +//! read back. Nothing here echoes a caller's value: a refusal names a schema +//! location and a keyword, never the text that failed. + +use std::collections::BTreeSet; +use std::sync::OnceLock; + +use cultcache_rs::{CultCacheEnvelope, DatabaseEntry}; +use jsonschema::paths::LocationSegment; +use jsonschema::error::ValidationErrorKind; +use jsonschema::Validator; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use crate::mind::Mind; +use crate::refusal::MindRefusal; +use crate::store::MindStore; + +const PERSONA_SCHEMA: &[u8] = include_bytes!("../../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); + +/// The stored envelope's payload: the document, one slot, keyed by the mind's +/// instance. The cache needs a registered entry type to hold the envelope; the +/// document inside stays a value. +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache(type = "gamecult.persona_state.v0", schema = "HuginnPersonaEntry")] +pub struct HuginnPersonaEntry { + #[cultcache(key = 0)] + pub value: Value, +} + +/// What `PersonaGet` answers: the stored document, its `updatedAt`, and the +/// receipt of the put that wrote it. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub struct PersonaStateView { + pub value: Value, + pub updated_at: String, + pub receipt_id: String, +} + +/// How a put ended. A refusal is an answer, as for `admit`. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum PersonaPutOutcome { + Committed { receipt_id: String }, + Refused(MindRefusal), +} + +struct Compiled { + validator: Validator, + /// Every property name the schema declares. A path segment outside this + /// set is a caller's key (`traitMap` keys are free), so it is withheld. + declared: BTreeSet, +} + +fn compiled() -> Result<&'static Compiled, MindRefusal> { + static COMPILED: OnceLock> = OnceLock::new(); + COMPILED + .get_or_init(|| { + let schema: Value = serde_json::from_slice(PERSONA_SCHEMA) + .map_err(|error| format!("the published persona schema does not parse: {error}"))?; + let validator = jsonschema::draft7::new(&schema) + .map_err(|error| format!("the published persona schema does not compile: {error}"))?; + let mut declared = BTreeSet::new(); + declared_names(&schema, &mut declared); + Ok(Compiled { validator, declared }) + }) + .as_ref() + .map_err(|detail| MindRefusal::Unavailable { detail: detail.clone() }) +} + +fn declared_names(node: &Value, names: &mut BTreeSet) { + match node { + Value::Object(map) => { + if let Some(Value::Object(properties)) = map.get("properties") { + names.extend(properties.keys().cloned()); + } + map.values().for_each(|child| declared_names(child, names)); + } + Value::Array(items) => items.iter().for_each(|child| declared_names(child, names)), + _ => {} + } +} + +/// Rule 1: the document is valid against the published schema. The first +/// failure is the refusal; it names where and which keyword, never the value. +pub(crate) fn validate_shape(state: &Value) -> Result<(), MindRefusal> { + let compiled = compiled()?; + let Err(error) = compiled.validator.validate(state) else { return Ok(()) }; + let mut path = error + .instance_path() + .segments() + .map(|segment| match segment { + LocationSegment::Index(index) => index.to_string(), + LocationSegment::Property(name) if compiled.declared.contains(name.as_ref()) => name.into_owned(), + LocationSegment::Property(_) => "*".to_string(), + }) + .collect::>(); + match error.kind() { + ValidationErrorKind::Required { property } => path.extend(property.as_str().map(str::to_string)), + ValidationErrorKind::AdditionalProperties { .. } => path.push("*".to_string()), + _ => {} + } + Err(MindRefusal::PersonaInvalid { + path: format!("/{}", path.join("/")), + message: format!("fails the published schema's {} rule", error.kind().keyword()), + }) +} + +/// A stored persona envelope's document. +pub(crate) fn decode(envelope: &CultCacheEnvelope) -> Result { + rmp_serde::from_slice::(&envelope.payload) + .map(|entry| entry.value) + .map_err(|error| MindRefusal::Unavailable { detail: format!("the stored persona does not decode: {error}") }) +} + +/// A document's `updatedAt`; the schema makes it a required string. +pub(crate) fn updated_at(value: &Value) -> Option<&str> { + value.get("updatedAt").and_then(Value::as_str) +} + +impl Mind { + /// This mind's persona envelope, if one is stored. + pub(crate) fn persona_envelope(&self) -> Option<&CultCacheEnvelope> { + self.raw_envelope(HuginnPersonaEntry::TYPE, &self.instance().0) + } + + /// The stored `updatedAt`; none when no persona is stored. + pub(crate) fn stored_updated_at(&self) -> Result, MindRefusal> { + let Some(envelope) = self.persona_envelope() else { return Ok(None) }; + let value = decode(envelope)?; + updated_at(&value) + .map(|stamp| Some(stamp.to_string())) + .ok_or_else(|| MindRefusal::Unavailable { detail: "the stored persona has no updatedAt".into() }) + } + + /// `PersonaGet`: the document, its `updatedAt` and the receipt of the put + /// that wrote exactly these bytes. + pub fn persona(&self) -> Result, MindRefusal> { + let Some(envelope) = self.persona_envelope() else { return Ok(None) }; + let value = decode(envelope)?; + let integrity = |detail: &str| MindRefusal::Unavailable { detail: detail.into() }; + let updated_at = updated_at(&value).ok_or_else(|| integrity("the stored persona has no updatedAt"))?.to_string(); + let identity = (envelope.r#type.as_str(), envelope.key.as_str()); + let receipt_id = self + .receipts()? + .into_iter() + .filter(|receipt| receipt.writes.iter().any(|write| write.identity() == identity)) + .max_by_key(|receipt| receipt.ordinal) + .ok_or_else(|| integrity("the stored persona has no receipt"))? + .receipt_id; + Ok(Some(PersonaStateView { value, updated_at, receipt_id })) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::fixtures::{INSTANCE, OTHER_INSTANCE, epoch, instance, opened, prepare, provenance, seed, slug}; + use crate::receipt::Faculty; + use crate::store::test_stores::{MemoryStore, RefusingStore, SwapCommand}; + use eureka_pipeline::PipelineKind; + use serde_json::json; + + const T1: &str = "2026-10-10T10:00:00Z"; + const T2: &str = "2026-10-10T10:00:01Z"; + const T3: &str = "2026-10-10T10:00:02Z"; + const CANARY: &str = "CANARY-7f3a91-do-not-echo"; + const NOT_LATER: &str = "must be later than the stored updatedAt"; + + /// A minimal document the published schema accepts. The test that follows + /// holds it to the schema file's own required list. + fn persona(id: &str, updated_at: &str) -> Value { + let traits = json!({ + "underlyingOrganization": {}, "stableDispositions": {}, "behavioralDimensions": {}, + "presentationStrategy": {}, "voiceStyle": {}, "situationalState": {} + }); + json!({ + "schemaVersion": "gamecult.persona_state.v0", + "provenance": { + "sourceSystem": "huginn", "sourceDocumentId": id, "sourceUpdatedAt": updated_at, + "exportedAt": updated_at, "authority": "canonical" + }, + "personaId": id, + "publicName": "Test Persona", + "presentation": { "voiceSummary": "plain" }, + "activationProfile": traits, + "thoughtMemory": { "shortTerm": [], "memories": [], "incubation": [] }, + "agencyPressure": { "pressures": [] }, + "candidateActions": { "actions": [] }, + "affect": { + "needs": [], "socialBonds": [], "statusReads": [], "moodDimensions": [], + "socialBiases": [], "doctrineStances": [] + }, + "updatedAt": updated_at + }) + } + + fn schema_file() -> Value { + let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../../schemas/cultnet/gamecult.persona_state.v0.schema.json"); + serde_json::from_slice(&std::fs::read(path).unwrap()).unwrap() + } + + fn put(mind: &mut Mind, state: Value, expected: Option<&str>) -> PersonaPutOutcome { + let instance = mind.instance().clone(); + mind.put_persona(&instance, state, expected.map(str::to_string), provenance(Faculty::Hands), crate::fixtures::now()) + } + + fn committed(outcome: PersonaPutOutcome) -> String { + match outcome { + PersonaPutOutcome::Committed { receipt_id } => receipt_id, + other => panic!("expected a commit, got {other:?}"), + } + } + + fn refused(outcome: PersonaPutOutcome) -> MindRefusal { + match outcome { + PersonaPutOutcome::Refused(refusal) => refusal, + other => panic!("expected a refusal, got {other:?}"), + } + } + + fn invalid(path: &str, rule: &str) -> MindRefusal { + MindRefusal::PersonaInvalid { path: path.into(), message: format!("fails the published schema's {rule} rule") } + } + + fn not_later() -> MindRefusal { + MindRefusal::PersonaInvalid { path: "/updatedAt".into(), message: NOT_LATER.into() } + } + + fn stale(stored: Option<&str>) -> MindRefusal { + MindRefusal::PersonaStale { stored: stored.map(str::to_string) } + } + + fn seeded_over(store: &MemoryStore) -> Mind { + let mut mind = opened(store.clone(), INSTANCE); + seed(&mut mind); + mind + } + + fn persona_in_status(mind: &Mind) -> crate::wire::PersonaStatus { + mind.status(crate::wire::IndexStatus::Current).persona + } + + #[test] + fn the_fixture_is_valid_against_the_published_file_and_covers_its_required_fields() { + let schema = schema_file(); + let validator = jsonschema::draft7::new(&schema).unwrap(); + let document = persona(INSTANCE, T1); + assert!(validator.is_valid(&document)); + for name in schema["required"].as_array().unwrap() { + assert!(document.get(name.as_str().unwrap()).is_some(), "the fixture lacks {name}"); + } + } + + #[test] + fn declared_names_are_every_property_name_at_any_depth() { + let schema = json!({ + "properties": { "a": { "properties": { "b": {} } } }, + "allOf": [{ "properties": { "c": {} } }], + "definitions": { "d": { "properties": { "e": {} } } }, + "required": ["not-a-property"] + }); + let mut names = BTreeSet::new(); + declared_names(&schema, &mut names); + assert_eq!(names, BTreeSet::from(["a", "b", "c", "e"].map(String::from))); + } + + /// `identity-write-all-visible`: a put may change any field, the identity + /// fields included, and a change the next second is no less admissible. + #[test] + fn a_put_may_rewrite_identity_fields_and_every_change_lands() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + + let mut renamed = persona(INSTANCE, T2); + renamed["publicName"] = json!("A New Name"); + renamed["publicDescription"] = json!("who she says she is"); + renamed["presentation"] = json!({ "voiceSummary": "warmer", "pronouns": "she/her" }); + renamed["values"] = json!([{ "id": "v1", "label": "candor", "priority": 0.9 }]); + committed(put(&mut mind, renamed.clone(), Some(T1))); + assert_eq!(mind.persona().unwrap().unwrap().value, renamed); + + let mut again = persona(INSTANCE, T3); + again["publicName"] = json!("Another Name"); + committed(put(&mut mind, again.clone(), Some(T2))); + assert_eq!(mind.persona().unwrap().unwrap().value, again); + } + + #[test] + fn the_view_names_the_receipt_of_the_latest_put() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let mut previous: Option = None; + for second in 0..5 { + let stamp = format!("2026-10-10T10:00:0{second}Z"); + let receipt = committed(put(&mut mind, persona(INSTANCE, &stamp), previous.as_deref())); + assert_eq!(mind.persona().unwrap().unwrap().receipt_id, receipt, "after put {second}"); + previous = Some(stamp); + } + } + + #[test] + fn a_persona_document_is_validated_at_the_door() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + + for name in schema_file()["required"].as_array().unwrap() { + let name = name.as_str().unwrap(); + let mut document = persona(INSTANCE, T1); + document.as_object_mut().unwrap().remove(name); + assert_eq!(refused(put(&mut mind, document, None)), invalid(&format!("/{name}"), "required"), "{name}"); + } + + let mut extra = persona(INSTANCE, T1); + extra["notInTheSchema"] = json!(1); + assert_eq!(refused(put(&mut mind, extra, None)), invalid("/*", "additionalProperties")); + + let mut wrong_type = persona(INSTANCE, T1); + wrong_type["publicName"] = json!(5); + assert_eq!(refused(put(&mut mind, wrong_type, None)), invalid("/publicName", "type")); + + let mut bad_stamp = persona(INSTANCE, T1); + bad_stamp["updatedAt"] = json!("yesterday"); + assert_eq!(refused(put(&mut mind, bad_stamp, None)), invalid("/updatedAt", "format")); + + let mut nested = persona(INSTANCE, T1); + nested["thoughtMemory"]["memories"] = json!([7]); + assert_eq!(refused(put(&mut mind, nested, None)), invalid("/thoughtMemory/memories/0", "type")); + + let mut free_key = persona(INSTANCE, T1); + free_key["activationProfile"]["voiceStyle"]["any-key"] = json!({}); + assert_eq!( + refused(put(&mut mind, free_key, None)), + invalid("/activationProfile/voiceStyle/*/mean", "required"), + "a key the schema does not declare is withheld from the path" + ); + + assert_eq!(store.rows(), before, "no refusal wrote anything"); + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn a_refusal_never_echoes_what_the_caller_sent() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T2), None)); + + let mut free_key = persona(INSTANCE, T3); + free_key["activationProfile"]["voiceStyle"][CANARY] = json!({}); + let mut extra_key = persona(INSTANCE, T3); + extra_key[CANARY] = json!(CANARY); + let mut bad_value = persona(INSTANCE, T3); + bad_value["updatedAt"] = json!(CANARY); + let mut bad_enum = persona(INSTANCE, T3); + bad_enum["provenance"]["authority"] = json!(CANARY); + let mut foreign = persona(CANARY, T3); + foreign["publicName"] = json!(CANARY); + let mut imported = persona(INSTANCE, T3); + imported["provenance"]["authority"] = json!("import"); + imported["provenance"]["sourceSystem"] = json!(CANARY); + let mut late = persona(INSTANCE, T1); + late["publicName"] = json!(CANARY); + + let cases: Vec<(Value, Option<&str>)> = vec![ + (free_key, Some(T2)), + (extra_key, Some(T2)), + (bad_value, Some(T2)), + (bad_enum, Some(T2)), + (foreign, Some(T2)), + (imported, Some(T2)), + (late, Some(T2)), + (persona(INSTANCE, T3), Some(CANARY)), + ]; + for (document, expected) in cases { + let refusal = refused(put(&mut mind, document, expected)); + assert!(!format!("{refusal:?}").contains(CANARY), "{refusal:?}"); + assert!(!serde_json::to_string(&refusal).unwrap().contains(CANARY)); + } + } + + #[test] + fn persona_id_must_be_the_instance() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + let refusal = refused(put(&mut mind, persona(OTHER_INSTANCE, T1), None)); + assert_eq!(refusal, MindRefusal::PersonaForeign { instance: INSTANCE.into() }); + assert_eq!(store.rows(), before); + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn only_a_canonical_document_is_the_minds_persona() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + for authority in ["projection", "import"] { + let mut document = persona(INSTANCE, T1); + document["provenance"]["authority"] = json!(authority); + assert_eq!(refused(put(&mut mind, document, None)), MindRefusal::PersonaNotCanonical, "{authority}"); + } + assert_eq!(mind.persona().unwrap(), None); + } + + #[test] + fn a_persona_waits_for_the_minds_identity() { + let mut mind = opened(MemoryStore::new(), INSTANCE); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), None)), MindRefusal::MissingIdentity); + assert!(mind.is_empty()); + } + + #[test] + fn a_put_must_name_this_mind_and_a_named_asker() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let before = store.rows(); + let other = slug(OTHER_INSTANCE); + let outcome = mind.put_persona(&other, persona(INSTANCE, T1), None, provenance(Faculty::Hands), crate::fixtures::now()); + assert!(matches!(refused(outcome), MindRefusal::ForeignInstance { .. })); + let mut unnamed = provenance(Faculty::Hands); + unnamed.agent = eureka_pipeline::Short(" ".into()); + let instance = mind.instance().clone(); + let outcome = mind.put_persona(&instance, persona(INSTANCE, T1), None, unnamed, crate::fixtures::now()); + assert!(matches!(refused(outcome), MindRefusal::Document(_))); + assert_eq!(store.rows(), before); + } + + #[test] + fn a_put_is_a_compare_and_swap_on_updated_at() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Absent); + let receipts = |mind: &Mind| mind.receipts().unwrap().len(); + let base = receipts(&mind); + + // A first put expects nothing; claiming a stored document is stale. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T1))), stale(None)); + let first = committed(put(&mut mind, persona(INSTANCE, T1), None)); + assert_eq!(receipts(&mind), base + 1); + let view = mind.persona().unwrap().unwrap(); + assert_eq!((view.updated_at.as_str(), view.receipt_id.as_str()), (T1, first.as_str())); + assert_eq!(view.value, persona(INSTANCE, T1)); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); + + // Two puts that read the same stored document: the second loses. + let second = committed(put(&mut mind, persona(INSTANCE, T2), Some(T1))); + assert_eq!(receipts(&mind), base + 2); + let rows = store.rows(); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), Some(T1))), stale(Some(T2))); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T3), None)), stale(Some(T2))); + assert_eq!(store.rows(), rows, "a stale put wrote nothing"); + + // The right expectation with an updatedAt that is not later. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T2))), not_later()); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T1), Some(T2))), not_later()); + // Instants compare, not spellings: the same instant at another offset is not later. + assert_eq!(refused(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:01+02:00"), Some(T2))), not_later()); + assert_eq!(store.rows(), rows); + assert_eq!(receipts(&mind), base + 2); + committed(put(&mut mind, persona(INSTANCE, "2026-10-10T12:00:02+02:00"), Some(T2))); + assert_eq!(receipts(&mind), base + 3); + + // The second put's receipt read the first document and wrote the second. + let receipt = mind.receipts().unwrap().into_iter().find(|receipt| receipt.receipt_id == second).unwrap(); + assert_eq!((receipt.strong_reads.len(), receipt.writes.len()), (1, 1)); + assert_eq!(receipt.strong_reads[0].document_key, INSTANCE); + assert_ne!(receipt.strong_reads[0].payload_msgpack, receipt.writes[0].payload_msgpack); + assert_eq!(receipt.provenance, provenance(Faculty::Hands)); + } + + #[test] + fn a_put_whose_swap_is_lost_is_stale_and_changes_nothing() { + let store = RefusingStore::new(); + let mut mind = opened(store.clone(), INSTANCE); + seed(&mut mind); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + let rows = store.rows(); + store.command(SwapCommand::Lose); + assert_eq!(refused(put(&mut mind, persona(INSTANCE, T2), Some(T1))), stale(Some(T1))); + assert_eq!(store.rows(), rows); + } + + #[test] + fn the_persona_is_not_a_pipeline_document_and_a_batch_cannot_carry_it() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + let documents = mind.status(crate::wire::IndexStatus::Current).documents; + committed(put(&mut mind, persona(INSTANCE, T1), None)); + assert_eq!(mind.status(crate::wire::IndexStatus::Current).documents, documents); + assert!(PipelineKind::ALL.iter().all(|kind| kind.type_id() != HuginnPersonaEntry::TYPE)); + let forged = mind.persona_envelope().unwrap().clone(); + let instance = mind.instance().clone(); + let outcome = mind.admit_prepared(&instance, provenance(Faculty::Hands), vec![forged], crate::fixtures::now()); + assert!(matches!(outcome, crate::admission::PipelineAdmissionOutcome::Refused(_)), "{outcome:?}"); + } + + #[test] + fn one_persona_per_mind_and_the_store_still_opens() { + let yggdrasil = slug(INSTANCE); + let cache = crate::mind::schema_cache().unwrap(); + let entry = |key: &str, value: Value| cache.prepare_entry_named(key, &HuginnPersonaEntry { value }).unwrap().0; + let planted = |rows: Vec| { + let store = MemoryStore::new(); + rows.into_iter().for_each(|row| store.plant(row)); + store + }; + let base = || vec![epoch(), prepare(&instance(INSTANCE))]; + + // A store written before this type existed opens unchanged. + assert!(Mind::open_with(planted(base()), &yggdrasil).is_ok()); + + // One persona opens; a planted row has no writing receipt, so the door and the status both call it unreadable. + let mut with_one = base(); + with_one.push(entry(INSTANCE, persona(INSTANCE, T1))); + let mind = Mind::open_with(planted(with_one.clone()), &yggdrasil).unwrap(); + assert_eq!(mind.envelopes().len(), 3); + assert_eq!(persona_in_status(&mind), crate::wire::PersonaStatus::Unreadable); + assert!(mind.persona().is_err()); + + // Two are no mind's. + with_one.push(entry("second", persona(INSTANCE, T2))); + assert_eq!( + Mind::open_with(planted(with_one), &yggdrasil).err(), + Some(MindRefusal::ForeignStore { r#type: HuginnPersonaEntry::TYPE.into() }) + ); + // The opener still refuses a type that is not one of the seventeen. + let mut stranger = base(); + let mut foreign = entry(INSTANCE, persona(INSTANCE, T1)); + foreign.r#type = "gamecult.persona_state.v1".into(); + stranger.push(foreign); + assert!(matches!(Mind::open_with(planted(stranger), &yggdrasil).err(), Some(MindRefusal::ForeignStore { .. }))); + } + + /// Status answers in the door's own terms: a stored persona the door + /// cannot read is `Unreadable`, not the `Absent` of a mind with none, while + /// `PersonaGet` answers `Unavailable` for the same bytes. + #[test] + fn status_says_unreadable_where_the_door_says_unavailable() { + let yggdrasil = slug(INSTANCE); + let cache = crate::mind::schema_cache().unwrap(); + let readable = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: persona(INSTANCE, T1) }).unwrap().0; + let no_stamp = cache.prepare_entry_named(INSTANCE, &HuginnPersonaEntry { value: json!({}) }).unwrap().0; + let mut undecodable = readable.clone(); + undecodable.payload = vec![0xc1]; + // Planted rows have no writing receipt: the door cannot read them, so neither may the status. + for (row, status) in [ + (readable, crate::wire::PersonaStatus::Unreadable), + (no_stamp, crate::wire::PersonaStatus::Unreadable), + (undecodable, crate::wire::PersonaStatus::Unreadable), + ] { + let store = MemoryStore::new(); + store.plant(epoch()); + store.plant(prepare(&instance(INSTANCE))); + store.plant(row); + let mind = Mind::open_with(store, &yggdrasil).unwrap(); + assert_eq!(persona_in_status(&mind), status); + assert!(matches!(mind.persona(), Err(MindRefusal::Unavailable { .. })), "the door answers what the status says"); + } + // A row a put wrote: status and door agree it is stored, with one stamp. + let store = MemoryStore::new(); + let mut written = seeded_over(&store); + committed(put(&mut written, persona(INSTANCE, T1), None)); + assert_eq!(persona_in_status(&written), crate::wire::PersonaStatus::Stored { updated_at: T1.into() }); + assert_eq!(written.persona().unwrap().unwrap().updated_at, T1); + assert_eq!(persona_in_status(&seeded_over(&MemoryStore::new())), crate::wire::PersonaStatus::Absent); + } + + #[test] + fn the_stored_bytes_are_the_one_slot_array_the_catalogue_describes() { + let store = MemoryStore::new(); + let mut mind = seeded_over(&store); + committed(put(&mut mind, persona(INSTANCE, T1), None)); + let envelope = mind.persona_envelope().unwrap(); + assert_eq!((envelope.r#type.as_str(), envelope.key.as_str()), ("gamecult.persona_state.v0", INSTANCE)); + let slots: (Value,) = rmp_serde::from_slice(&envelope.payload).unwrap(); + assert_eq!(slots.0, persona(INSTANCE, T1)); + } +} diff --git a/crates/huginn-mind/src/wire.rs b/crates/huginn-mind/src/wire.rs index ba213b3..e0c198d 100644 --- a/crates/huginn-mind/src/wire.rs +++ b/crates/huginn-mind/src/wire.rs @@ -1,343 +1,343 @@ -//! The organ's request and response vocabulary: one operation per `Mind` -//! method and `whoami`. Payloads are the admission and read types unchanged. -//! The daemon carries these in CultNet's operation envelope; the client -//! constructs them. Nothing here validates a document, derives a status or -//! names a transport. - -use cultcache_rs::DatabaseEntry; -use cultnet_rs::{CultMeshCdnArtifactManifest, Selection}; -use eureka_pipeline::{PIPELINE_SCHEMA_EPOCH, PipelineKind, PipelineRef, Slug}; -use schemars::JsonSchema; -use serde::{Deserialize, Serialize}; -use serde_json::Value; - -use crate::admission::{PipelineAdmissionBatch, PipelineAdmissionOutcome}; -use crate::mind::Mind; -use crate::persona::{PersonaPutOutcome, PersonaStateView}; -use crate::query::{PipelineDocumentView, PipelineSelectionPage, SemanticQuery}; -use crate::receipt::{HuginnCommitReceipt, PipelineProvenance}; -use crate::refusal::MindRefusal; -use crate::store::MindStore; - -/// The envelope's `service_id`: one service, one mind, whichever mind the -/// process opened. -pub const MIND_SERVICE_ID: &str = "huginn.mind"; -pub const MIND_REQUEST_SCHEMA: &str = "huginn.mind_request.v1"; -pub const MIND_RESPONSE_SCHEMA: &str = "huginn.mind_response.v1"; - -/// The largest answer that is deferred rather than refused, measured on the -/// encoded payload. The daemon refuses past it and a client caps its fetch at -/// it, so both sides read one number. -pub const MAX_DEFERRED_BODY_BYTES: u64 = 64 * 1024 * 1024; - -/// The published JSON schema of each wire type, as the catalog advertises it. -/// The files are derived from the types below and pinned byte for byte by -/// `published_wire_schemas_match_derivation`, so the catalog cannot advertise -/// a shape the crate does not speak. -pub const MIND_REQUEST_SCHEMA_JSON: &str = - include_str!("../../../schemas/cultnet/huginn.mind_request.v1.schema.json"); -pub const MIND_RESPONSE_SCHEMA_JSON: &str = - include_str!("../../../schemas/cultnet/huginn.mind_response.v1.schema.json"); - -/// The request's `selection` is CultNet's, and its published schema is -/// CultLib's: a `$ref` to the `$id` it publishes, so one owner holds the -/// selection's shape and nothing here copies it. -fn selection_ref(_: &mut schemars::SchemaGenerator) -> schemars::Schema { - schemars::json_schema!({ - "$ref": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.selection.schema.json" - }) -} - -/// The deferred answer's manifest is CultMesh's own type, a positional array -/// the C# reference defines (`CultMeshCdnArtifactManifest`, schema version -/// `gamecult.mesh.cdn_artifact_manifest.v1`). CultLib publishes no JSON schema -/// for it, so the schema says what the reference says: an array of its ten -/// fields in order, and nothing here copies their meaning. -fn manifest_array(_: &mut schemars::SchemaGenerator) -> schemars::Schema { - schemars::json_schema!({ - "description": "gamecult.mesh.cdn_artifact_manifest.v1, the C# reference's CultMeshCdnArtifactManifest as its positional array: [artifactId, kind, version, contentHash, sizeBytes, mimeType, createdAtUtc, chunks[[chunkHash, offset, sizeBytes, recordKey]], tags, metadata].", - "type": "array" - }) -} - -/// Every operation a mind answers. `Admit` carries the batch whole because the -/// batch already names the instance and the asker; a second `instance` beside -/// it would be two declarations. Every read names the instance because ruling -/// 14 refuses another mind's identity whatever the transport, and a read of -/// the wrong mind is that same collision on the read side. `Whoami` names -/// none: it is how a client learns which mind it reached. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum HuginnMindRequest { - Whoami, - Admit(PipelineAdmissionBatch), - View { instance: Slug, id: PipelineRef }, - Query { - instance: Slug, - #[schemars(schema_with = "selection_ref")] - selection: Selection, - semantic: Option, - }, - /// The mind's persona document, if one is stored. - PersonaGet { instance: Slug }, - /// Replaces the mind's persona document whole. `expected_updated_at` is - /// the stored document's `updatedAt`, none for the first put. The - /// provenance is the asker's, as for `Admit`. - PersonaPut { - instance: Slug, - provenance: PipelineProvenance, - state: Value, - expected_updated_at: Option, - }, -} - -impl HuginnMindRequest { - /// The envelope's `operation`. - pub fn operation(&self) -> &'static str { - match self { - Self::Whoami => "whoami", - Self::Admit(_) => "admit", - Self::View { .. } => "view", - Self::Query { .. } => "query", - Self::PersonaGet { .. } => "persona_get", - Self::PersonaPut { .. } => "persona_put", - } - } - - /// The instance the request declares; `Whoami` declares none. - pub fn instance(&self) -> Option<&Slug> { - match self { - Self::Whoami => None, - Self::Admit(batch) => Some(&batch.instance), - Self::View { instance, .. } - | Self::Query { instance, .. } - | Self::PersonaGet { instance } - | Self::PersonaPut { instance, .. } => Some(instance), - } - } -} - -/// Every answer a mind gives. A refusal is data in the response, never a -/// transport failure: the read side carries `Refused`, the write side carries -/// the outcome's own `Refused`. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum HuginnMindResponse { - Whoami(MindStatus), - Admit(PipelineAdmissionOutcome), - View(Option>), - Query(PipelineSelectionPage), - Refused(MindRefusal), - Persona(Option), - PersonaPut(PersonaPutOutcome), - /// The answer did not fit one send and is being held for the client to - /// fetch. Nothing in a mind produces this: the daemon's serve module does, - /// in place of an answer, and the answer it stands for is the named - /// MessagePack of the `HuginnMindResponse` the mind gave. - Deferred(DeferredAnswer), -} - -/// Where the body of an answer that did not fit one send can be fetched: the -/// reference's own manifest, whose `contentHash` is the SHA-256 of the answer's -/// encoded bytes and whose chunks are asked for, one at a time, on the session -/// this arrived on. Row-level facts come from asking again with a header -/// projection; there is no summary. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub struct DeferredAnswer { - #[schemars(schema_with = "manifest_array")] - pub manifest: CultMeshCdnArtifactManifest, -} - -impl HuginnMindResponse { - /// The envelope's `status`, in the C# reference's vocabulary: `rejected` - /// exactly for a refusal, `accepted` otherwise. `Conflict` and - /// `AlreadyAdmitted` are answers about the mind, not refusals of the - /// request. A `Deferred` is nominally `accepted`; the daemon sets the - /// envelope of a deferred answer to the status of the answer it stands for. - pub fn status(&self) -> &'static str { - match self { - Self::Refused(_) - | Self::Admit(PipelineAdmissionOutcome::Refused(_)) - | Self::PersonaPut(PersonaPutOutcome::Refused(_)) => "rejected", - _ => "accepted", - } - } -} - -/// How far the semantic index has caught up with the mind. The mind decides -/// none of it: the daemon's index worker reports it, in memory, and a restart -/// recomputes it. `pending` counts documents not yet known to be in the index. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum IndexStatus { - /// The worker has not yet compared the mind with the collection. - Reconciling { pending: u32 }, - /// Every indexable document is in the collection. - Current, - /// Reconciled, and indexing what is still pending. - Behind { pending: u32 }, - /// The last attempt failed (the embedder or the vector store is - /// unreachable, or refused); it is retried with a backoff and nothing is - /// dropped. `attempts` counts consecutive failures. - Failing { pending: u32, attempts: u32, error: String }, - /// The collection belongs to another writer. The worker never recreates - /// it; it re-reads it on the same backoff. - Refused { pending: u32, attempts: u32, reason: String }, -} - -/// What a mind says about itself: the typed state a dashboard projects. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub struct MindStatus { - pub instance: Slug, - pub schema_epoch: String, - /// Pipeline documents in the image; the epoch record and the receipts are - /// not documents and are not counted here. - pub documents: u32, - pub receipts: u32, - pub index: IndexStatus, - /// The persona door as `PersonaGet` would find it. - pub persona: PersonaStatus, -} - -/// What the persona door holds, in the one vocabulary the door itself answers -/// in: nothing yet, a document with this `updatedAt`, or a stored document the -/// door cannot read (`PersonaGet` and every put answer `Unavailable`). -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] -pub enum PersonaStatus { - Absent, - Stored { updated_at: String }, - Unreadable, -} - -impl Mind { - /// `whoami`, derived from the image every time it is asked, and from the - /// index status the caller holds: the mind stores neither. - pub fn status(&self, index: IndexStatus) -> MindStatus { - let mut documents = 0_u32; - let mut receipts = 0_u32; - for envelope in self.envelopes() { - if envelope.r#type == HuginnCommitReceipt::TYPE { - receipts += 1; - } else if PipelineKind::ALL.iter().any(|kind| kind.type_id() == envelope.r#type) { - documents += 1; - } - } - MindStatus { - instance: self.instance().clone(), - schema_epoch: PIPELINE_SCHEMA_EPOCH.to_string(), - documents, - receipts, - index, - persona: match self.persona() { - Ok(None) => PersonaStatus::Absent, - Ok(Some(view)) => PersonaStatus::Stored { updated_at: view.updated_at }, - Err(_) => PersonaStatus::Unreadable, - }, - } - } -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::query::PipelinePageItems; - use crate::fixtures::{CAMPAIGN, INSTANCE, OTHER_INSTANCE, instance, provenance, r, seeded, slug}; - use crate::receipt::Faculty; - - fn requests() -> Vec { - let batch = PipelineAdmissionBatch { - instance: slug(INSTANCE), - provenance: provenance(Faculty::Hands), - documents: vec![instance(INSTANCE)], - }; - vec![ - HuginnMindRequest::Whoami, - HuginnMindRequest::Admit(batch), - HuginnMindRequest::View { instance: slug(INSTANCE), id: r(PipelineKind::Campaign, CAMPAIGN) }, - HuginnMindRequest::Query { instance: slug(OTHER_INSTANCE), selection: Selection::default(), semantic: None }, - HuginnMindRequest::PersonaGet { instance: slug(INSTANCE) }, - HuginnMindRequest::PersonaPut { - instance: slug(INSTANCE), - provenance: provenance(Faculty::Hands), - state: serde_json::json!({ "updatedAt": "2026-10-10T10:00:00Z", "n": [1, 2.5, null, "x"] }), - expected_updated_at: Some("2026-10-10T09:00:00Z".into()), - }, - ] - } - - fn responses() -> Vec { - let refusal = MindRefusal::ForeignInstance { declared: OTHER_INSTANCE.into(), mind: INSTANCE.into() }; - vec![ - HuginnMindResponse::Whoami(seeded().status(IndexStatus::Current)), - HuginnMindResponse::Admit(PipelineAdmissionOutcome::AlreadyAdmitted { receipt_id: "r1".into() }), - HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { identities: vec![] }), - HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(refusal.clone())), - HuginnMindResponse::View(None), - HuginnMindResponse::Query(PipelineSelectionPage { - matched: 0, - as_of: 1, - next: None, - items: PipelinePageItems::Headers(vec![]), - edges: None, - }), - HuginnMindResponse::Refused(refusal), - HuginnMindResponse::Persona(None), - HuginnMindResponse::Persona(Some(PersonaStateView { - value: serde_json::json!({ "personaId": INSTANCE }), - updated_at: "2026-10-10T10:00:00Z".into(), - receipt_id: "mind-commit-1".into(), - })), - HuginnMindResponse::PersonaPut(PersonaPutOutcome::Committed { receipt_id: "mind-commit-2".into() }), - HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(MindRefusal::PersonaNotCanonical)), - HuginnMindResponse::Deferred(DeferredAnswer { - manifest: cultnet_rs::pack_content("huginn.mind_response", "package", "", "", "", b"body", 4) - .unwrap() - .0, - }), - ] - } - - /// The vocabulary is the mind's methods, the declared instance is on every - /// request that names a mind, and the envelope's status is derived from - /// the response rather than chosen by whoever sends it. - #[test] - fn the_wire_vocabulary_is_the_minds_methods_and_status_is_derived_from_the_response() { - let names: Vec<&str> = requests().iter().map(|request| request.operation()).collect(); - assert_eq!(names, ["whoami", "admit", "view", "query", "persona_get", "persona_put"]); - for request in requests() { - let declared = request.instance().is_none(); - assert_eq!(declared, matches!(request, HuginnMindRequest::Whoami), "{request:?}"); - let bytes = rmp_serde::to_vec_named(&request).unwrap(); - assert_eq!(rmp_serde::from_slice::(&bytes).unwrap(), request); - } - assert_eq!( - requests()[3].instance(), - Some(&slug(OTHER_INSTANCE)), - "the request's instance is the one it declares, not the mind's" - ); - - for response in responses() { - let rejected = matches!( - response, - HuginnMindResponse::Refused(_) - | HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(_)) - | HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(_)) - ); - assert_eq!(response.status(), if rejected { "rejected" } else { "accepted" }, "{response:?}"); - let bytes = rmp_serde::to_vec_named(&response).unwrap(); - assert_eq!(rmp_serde::from_slice::(&bytes).unwrap(), response); - } - } - - /// The two files the catalog publishes are the derivation of the two - /// types, byte for byte. - #[test] - fn published_wire_schemas_match_derivation() { - let request = serde_json::to_string_pretty(&schemars::schema_for!(HuginnMindRequest)).unwrap(); - let response = serde_json::to_string_pretty(&schemars::schema_for!(HuginnMindResponse)).unwrap(); - assert_eq!(MIND_REQUEST_SCHEMA_JSON.replace("\r\n", "\n"), request); - assert_eq!(MIND_RESPONSE_SCHEMA_JSON.replace("\r\n", "\n"), response); - // The selection is CultLib's, referenced by the `$id` it publishes and - // not copied into this schema. - let selection = "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.selection.schema.json"; - assert!(request.contains(&format!("\"$ref\": \"{selection}\""))); - assert!(!request.contains("\"cursor\""), "no second copy of the selection's shape"); - } -} +//! The organ's request and response vocabulary: one operation per `Mind` +//! method and `whoami`. Payloads are the admission and read types unchanged. +//! The daemon carries these in CultNet's operation envelope; the client +//! constructs them. Nothing here validates a document, derives a status or +//! names a transport. + +use cultcache_rs::DatabaseEntry; +use cultnet_rs::{CultMeshCdnArtifactManifest, Selection}; +use eureka_pipeline::{PIPELINE_SCHEMA_EPOCH, PipelineKind, PipelineRef, Slug}; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use crate::admission::{PipelineAdmissionBatch, PipelineAdmissionOutcome}; +use crate::mind::Mind; +use crate::persona::{PersonaPutOutcome, PersonaStateView}; +use crate::query::{PipelineDocumentView, PipelineSelectionPage, SemanticQuery}; +use crate::receipt::{HuginnCommitReceipt, PipelineProvenance}; +use crate::refusal::MindRefusal; +use crate::store::MindStore; + +/// The envelope's `service_id`: one service, one mind, whichever mind the +/// process opened. +pub const MIND_SERVICE_ID: &str = "huginn.mind"; +pub const MIND_REQUEST_SCHEMA: &str = "huginn.mind_request.v1"; +pub const MIND_RESPONSE_SCHEMA: &str = "huginn.mind_response.v1"; + +/// The largest answer that is deferred rather than refused, measured on the +/// encoded payload. The daemon refuses past it and a client caps its fetch at +/// it, so both sides read one number. +pub const MAX_DEFERRED_BODY_BYTES: u64 = 64 * 1024 * 1024; + +/// The published JSON schema of each wire type, as the catalog advertises it. +/// The files are derived from the types below and pinned byte for byte by +/// `published_wire_schemas_match_derivation`, so the catalog cannot advertise +/// a shape the crate does not speak. +pub const MIND_REQUEST_SCHEMA_JSON: &str = + include_str!("../../../schemas/cultnet/huginn.mind_request.v1.schema.json"); +pub const MIND_RESPONSE_SCHEMA_JSON: &str = + include_str!("../../../schemas/cultnet/huginn.mind_response.v1.schema.json"); + +/// The request's `selection` is CultNet's, and its published schema is +/// CultLib's: a `$ref` to the `$id` it publishes, so one owner holds the +/// selection's shape and nothing here copies it. +fn selection_ref(_: &mut schemars::SchemaGenerator) -> schemars::Schema { + schemars::json_schema!({ + "$ref": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.selection.schema.json" + }) +} + +/// The deferred answer's manifest is CultMesh's own type, a positional array +/// the C# reference defines (`CultMeshCdnArtifactManifest`, schema version +/// `gamecult.mesh.cdn_artifact_manifest.v1`). CultLib publishes no JSON schema +/// for it, so the schema says what the reference says: an array of its ten +/// fields in order, and nothing here copies their meaning. +fn manifest_array(_: &mut schemars::SchemaGenerator) -> schemars::Schema { + schemars::json_schema!({ + "description": "gamecult.mesh.cdn_artifact_manifest.v1, the C# reference's CultMeshCdnArtifactManifest as its positional array: [artifactId, kind, version, contentHash, sizeBytes, mimeType, createdAtUtc, chunks[[chunkHash, offset, sizeBytes, recordKey]], tags, metadata].", + "type": "array" + }) +} + +/// Every operation a mind answers. `Admit` carries the batch whole because the +/// batch already names the instance and the asker; a second `instance` beside +/// it would be two declarations. Every read names the instance because ruling +/// 14 refuses another mind's identity whatever the transport, and a read of +/// the wrong mind is that same collision on the read side. `Whoami` names +/// none: it is how a client learns which mind it reached. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum HuginnMindRequest { + Whoami, + Admit(PipelineAdmissionBatch), + View { instance: Slug, id: PipelineRef }, + Query { + instance: Slug, + #[schemars(schema_with = "selection_ref")] + selection: Selection, + semantic: Option, + }, + /// The mind's persona document, if one is stored. + PersonaGet { instance: Slug }, + /// Replaces the mind's persona document whole. `expected_updated_at` is + /// the stored document's `updatedAt`, none for the first put. The + /// provenance is the asker's, as for `Admit`. + PersonaPut { + instance: Slug, + provenance: PipelineProvenance, + state: Value, + expected_updated_at: Option, + }, +} + +impl HuginnMindRequest { + /// The envelope's `operation`. + pub fn operation(&self) -> &'static str { + match self { + Self::Whoami => "whoami", + Self::Admit(_) => "admit", + Self::View { .. } => "view", + Self::Query { .. } => "query", + Self::PersonaGet { .. } => "persona_get", + Self::PersonaPut { .. } => "persona_put", + } + } + + /// The instance the request declares; `Whoami` declares none. + pub fn instance(&self) -> Option<&Slug> { + match self { + Self::Whoami => None, + Self::Admit(batch) => Some(&batch.instance), + Self::View { instance, .. } + | Self::Query { instance, .. } + | Self::PersonaGet { instance } + | Self::PersonaPut { instance, .. } => Some(instance), + } + } +} + +/// Every answer a mind gives. A refusal is data in the response, never a +/// transport failure: the read side carries `Refused`, the write side carries +/// the outcome's own `Refused`. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum HuginnMindResponse { + Whoami(MindStatus), + Admit(PipelineAdmissionOutcome), + View(Option>), + Query(PipelineSelectionPage), + Refused(MindRefusal), + Persona(Option), + PersonaPut(PersonaPutOutcome), + /// The answer did not fit one send and is being held for the client to + /// fetch. Nothing in a mind produces this: the daemon's serve module does, + /// in place of an answer, and the answer it stands for is the named + /// MessagePack of the `HuginnMindResponse` the mind gave. + Deferred(DeferredAnswer), +} + +/// Where the body of an answer that did not fit one send can be fetched: the +/// reference's own manifest, whose `contentHash` is the SHA-256 of the answer's +/// encoded bytes and whose chunks are asked for, one at a time, on the session +/// this arrived on. Row-level facts come from asking again with a header +/// projection; there is no summary. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub struct DeferredAnswer { + #[schemars(schema_with = "manifest_array")] + pub manifest: CultMeshCdnArtifactManifest, +} + +impl HuginnMindResponse { + /// The envelope's `status`, in the C# reference's vocabulary: `rejected` + /// exactly for a refusal, `accepted` otherwise. `Conflict` and + /// `AlreadyAdmitted` are answers about the mind, not refusals of the + /// request. A `Deferred` is nominally `accepted`; the daemon sets the + /// envelope of a deferred answer to the status of the answer it stands for. + pub fn status(&self) -> &'static str { + match self { + Self::Refused(_) + | Self::Admit(PipelineAdmissionOutcome::Refused(_)) + | Self::PersonaPut(PersonaPutOutcome::Refused(_)) => "rejected", + _ => "accepted", + } + } +} + +/// How far the semantic index has caught up with the mind. The mind decides +/// none of it: the daemon's index worker reports it, in memory, and a restart +/// recomputes it. `pending` counts documents not yet known to be in the index. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum IndexStatus { + /// The worker has not yet compared the mind with the collection. + Reconciling { pending: u32 }, + /// Every indexable document is in the collection. + Current, + /// Reconciled, and indexing what is still pending. + Behind { pending: u32 }, + /// The last attempt failed (the embedder or the vector store is + /// unreachable, or refused); it is retried with a backoff and nothing is + /// dropped. `attempts` counts consecutive failures. + Failing { pending: u32, attempts: u32, error: String }, + /// The collection belongs to another writer. The worker never recreates + /// it; it re-reads it on the same backoff. + Refused { pending: u32, attempts: u32, reason: String }, +} + +/// What a mind says about itself: the typed state a dashboard projects. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub struct MindStatus { + pub instance: Slug, + pub schema_epoch: String, + /// Pipeline documents in the image; the epoch record and the receipts are + /// not documents and are not counted here. + pub documents: u32, + pub receipts: u32, + pub index: IndexStatus, + /// The persona door as `PersonaGet` would find it. + pub persona: PersonaStatus, +} + +/// What the persona door holds, in the one vocabulary the door itself answers +/// in: nothing yet, a document with this `updatedAt`, or a stored document the +/// door cannot read (`PersonaGet` and every put answer `Unavailable`). +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub enum PersonaStatus { + Absent, + Stored { updated_at: String }, + Unreadable, +} + +impl Mind { + /// `whoami`, derived from the image every time it is asked, and from the + /// index status the caller holds: the mind stores neither. + pub fn status(&self, index: IndexStatus) -> MindStatus { + let mut documents = 0_u32; + let mut receipts = 0_u32; + for envelope in self.envelopes() { + if envelope.r#type == HuginnCommitReceipt::TYPE { + receipts += 1; + } else if PipelineKind::ALL.iter().any(|kind| kind.type_id() == envelope.r#type) { + documents += 1; + } + } + MindStatus { + instance: self.instance().clone(), + schema_epoch: PIPELINE_SCHEMA_EPOCH.to_string(), + documents, + receipts, + index, + persona: match self.persona() { + Ok(None) => PersonaStatus::Absent, + Ok(Some(view)) => PersonaStatus::Stored { updated_at: view.updated_at }, + Err(_) => PersonaStatus::Unreadable, + }, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::query::PipelinePageItems; + use crate::fixtures::{CAMPAIGN, INSTANCE, OTHER_INSTANCE, instance, provenance, r, seeded, slug}; + use crate::receipt::Faculty; + + fn requests() -> Vec { + let batch = PipelineAdmissionBatch { + instance: slug(INSTANCE), + provenance: provenance(Faculty::Hands), + documents: vec![instance(INSTANCE)], + }; + vec![ + HuginnMindRequest::Whoami, + HuginnMindRequest::Admit(batch), + HuginnMindRequest::View { instance: slug(INSTANCE), id: r(PipelineKind::Campaign, CAMPAIGN) }, + HuginnMindRequest::Query { instance: slug(OTHER_INSTANCE), selection: Selection::default(), semantic: None }, + HuginnMindRequest::PersonaGet { instance: slug(INSTANCE) }, + HuginnMindRequest::PersonaPut { + instance: slug(INSTANCE), + provenance: provenance(Faculty::Hands), + state: serde_json::json!({ "updatedAt": "2026-10-10T10:00:00Z", "n": [1, 2.5, null, "x"] }), + expected_updated_at: Some("2026-10-10T09:00:00Z".into()), + }, + ] + } + + fn responses() -> Vec { + let refusal = MindRefusal::ForeignInstance { declared: OTHER_INSTANCE.into(), mind: INSTANCE.into() }; + vec![ + HuginnMindResponse::Whoami(seeded().status(IndexStatus::Current)), + HuginnMindResponse::Admit(PipelineAdmissionOutcome::AlreadyAdmitted { receipt_id: "r1".into() }), + HuginnMindResponse::Admit(PipelineAdmissionOutcome::Conflict { identities: vec![] }), + HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(refusal.clone())), + HuginnMindResponse::View(None), + HuginnMindResponse::Query(PipelineSelectionPage { + matched: 0, + as_of: 1, + next: None, + items: PipelinePageItems::Headers(vec![]), + edges: None, + }), + HuginnMindResponse::Refused(refusal), + HuginnMindResponse::Persona(None), + HuginnMindResponse::Persona(Some(PersonaStateView { + value: serde_json::json!({ "personaId": INSTANCE }), + updated_at: "2026-10-10T10:00:00Z".into(), + receipt_id: "mind-commit-1".into(), + })), + HuginnMindResponse::PersonaPut(PersonaPutOutcome::Committed { receipt_id: "mind-commit-2".into() }), + HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(MindRefusal::PersonaNotCanonical)), + HuginnMindResponse::Deferred(DeferredAnswer { + manifest: cultnet_rs::pack_content("huginn.mind_response", "package", "", "", "", b"body", 4) + .unwrap() + .0, + }), + ] + } + + /// The vocabulary is the mind's methods, the declared instance is on every + /// request that names a mind, and the envelope's status is derived from + /// the response rather than chosen by whoever sends it. + #[test] + fn the_wire_vocabulary_is_the_minds_methods_and_status_is_derived_from_the_response() { + let names: Vec<&str> = requests().iter().map(|request| request.operation()).collect(); + assert_eq!(names, ["whoami", "admit", "view", "query", "persona_get", "persona_put"]); + for request in requests() { + let declared = request.instance().is_none(); + assert_eq!(declared, matches!(request, HuginnMindRequest::Whoami), "{request:?}"); + let bytes = rmp_serde::to_vec_named(&request).unwrap(); + assert_eq!(rmp_serde::from_slice::(&bytes).unwrap(), request); + } + assert_eq!( + requests()[3].instance(), + Some(&slug(OTHER_INSTANCE)), + "the request's instance is the one it declares, not the mind's" + ); + + for response in responses() { + let rejected = matches!( + response, + HuginnMindResponse::Refused(_) + | HuginnMindResponse::Admit(PipelineAdmissionOutcome::Refused(_)) + | HuginnMindResponse::PersonaPut(PersonaPutOutcome::Refused(_)) + ); + assert_eq!(response.status(), if rejected { "rejected" } else { "accepted" }, "{response:?}"); + let bytes = rmp_serde::to_vec_named(&response).unwrap(); + assert_eq!(rmp_serde::from_slice::(&bytes).unwrap(), response); + } + } + + /// The two files the catalog publishes are the derivation of the two + /// types, byte for byte. + #[test] + fn published_wire_schemas_match_derivation() { + let request = serde_json::to_string_pretty(&schemars::schema_for!(HuginnMindRequest)).unwrap(); + let response = serde_json::to_string_pretty(&schemars::schema_for!(HuginnMindResponse)).unwrap(); + assert_eq!(MIND_REQUEST_SCHEMA_JSON.replace("\r\n", "\n"), request); + assert_eq!(MIND_RESPONSE_SCHEMA_JSON.replace("\r\n", "\n"), response); + // The selection is CultLib's, referenced by the `$id` it publishes and + // not copied into this schema. + let selection = "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.selection.schema.json"; + assert!(request.contains(&format!("\"$ref\": \"{selection}\""))); + assert!(!request.contains("\"cursor\""), "no second copy of the selection's shape"); + } +}