colloquy_core/lib.rs
1//! `colloquy-core` — the cq shared-agent-learning standard, in pure Rust.
2//!
3//! Agents that work alone rediscover the same failures independently. cq is an
4//! open standard for stopping that: agents **query** a shared store before
5//! acting, **propose** what they learned, **confirm** what held, **flag** what
6//! rotted, and graduate durable knowledge upward through a human gate. This
7//! crate is a clean-room implementation of the standard's data model and rules.
8//!
9//! It is deliberately *pure*: no clock, no I/O, no network, no store. Every
10//! time-dependent function takes `now` as an argument, which is what lets the
11//! same crate drive an agent runtime natively and a `wasm32` edge worker, with
12//! both computing byte-identical confidence for the same evidence.
13//!
14//! # The shape of it
15//!
16//! | Module | Owns |
17//! |---|---|
18//! | [`mod@unit`] | The knowledge unit: cq's wire schema. |
19//! | [`kind`] | The ladder — pitfall, workaround, tool recommendation, gap signal. |
20//! | [`id`] | Content-addressed `ku_…` identifiers. |
21//! | [`principal`] | Authorising principals, and the collapse that makes counts honest. |
22//! | [`confidence`] | Attestations in, diversity-weighted evidence out. |
23//! | [`decay`] | Per-kind staleness. |
24//! | [`graduation`] | Tier promotion and the human gate. |
25//! | [`mod@validate`] | Limits, including the embedding window. |
26//! | [`cluster`] | Level-2 workarounds aggregated into level-4 gap signals. |
27//! | [`time`] | RFC 3339 timestamps without a date library. |
28//!
29//! # The two rules worth knowing before reading the code
30//!
31//! **Confidence follows principals, not confirmations.** cq's trust model says
32//! three confirmations from three independent parties outrank eight hundred from
33//! two. Implemented over accounts that rule is defeated by anyone who can create
34//! accounts — and in an agent estate, creating an account is a command. So every
35//! attestation is folded onto its *authorising principal* before it is weighed:
36//! an operator's fifty agents count once. See [`principal::collapse`].
37//!
38//! **A flag suppresses nothing.** Flagging lowers a unit's standing and marks it
39//! [`unit::UnitStatus::Disputed`], which is still served. Only a signed decision
40//! retires a unit, so no single member can remove knowledge from the store by
41//! objecting to it. See [`confidence::Ledger::apply`].
42//!
43//! # A unit's life, end to end
44//!
45//! ```
46//! use colloquy_core::{
47//! confidence::Ledger, graduation::{graduate, Approval, GraduationPolicy},
48//! kind::UnitKind, principal::Attestation, time::Timestamp,
49//! unit::{Insight, KnowledgeUnit, Tier, UnitStatus}, validate::{validate, Limits},
50//! };
51//!
52//! let t0 = Timestamp::parse_rfc3339("2026-01-01T00:00:00Z").unwrap();
53//!
54//! // An agent proposes what it learned. Proposing is not confirming.
55//! let mut unit = KnowledgeUnit::propose(
56//! "did:nostr:scribe",
57//! UnitKind::Workaround,
58//! ["http", "retry-semantics"],
59//! Insight::new(
60//! "A regenerated idempotency key turns one retry into two charges",
61//! "The client mints a fresh key per attempt, so the provider sees distinct requests.",
62//! "Derive the key from the order id, never from the attempt counter.",
63//! ),
64//! t0,
65//! );
66//! validate(&unit, &Limits::default()).unwrap();
67//! assert_eq!(unit.lifecycle.status, UnitStatus::Draft);
68//!
69//! // Two independent principals confirm it — one of them a person.
70//! let mut ledger = Ledger::default();
71//! ledger.confirm(Attestation::agent("auditor", "did:nostr:bob", t0.plus_secs(3_600)));
72//! ledger.confirm(Attestation::human("did:nostr:alice", 0.9, t0.plus_secs(7_200)));
73//! let assessment = ledger.apply(&mut unit, &Default::default(), &Default::default(), t0.plus_secs(7_200));
74//!
75//! assert_eq!(unit.lifecycle.status, UnitStatus::Active);
76//! assert_eq!(assessment.distinct_principals, 2);
77//! assert!(unit.evidence.confidence > 0.5);
78//!
79//! // A person approves promotion to the shared tier.
80//! graduate(
81//! &mut unit, &ledger, Tier::Shared,
82//! &Approval { approved_by: "did:nostr:alice".into(), at: t0.plus_secs(9_000), authorising_event: None },
83//! &GraduationPolicy::for_tier(Tier::Shared),
84//! &Default::default(), &Default::default(), t0.plus_secs(9_000),
85//! ).unwrap();
86//! assert_eq!(unit.tier(), Tier::Shared);
87//! ```
88//!
89//! # Relationship to cq
90//!
91//! The wire schema is cq's, so units round-trip between implementations. Two
92//! fields are ours and both are additive, which is what keeps that true:
93//! [`unit::Graduation::authorising_event`] makes a human approval checkable
94//! rather than merely asserted, and [`unit::UnitStatus::Disputed`] separates
95//! "contested" from "withdrawn".
96//!
97//! cq is published by Mozilla AI under the Apache-2.0 licence; this crate is an
98//! independent implementation of the documented standard and carries the same
99//! licence.
100
101#![forbid(unsafe_code)]
102#![deny(
103 missing_docs,
104 missing_debug_implementations,
105 rustdoc::broken_intra_doc_links
106)]
107
108pub mod cluster;
109pub mod confidence;
110pub mod decay;
111pub mod graduation;
112pub mod id;
113pub mod kind;
114pub mod principal;
115pub mod time;
116pub mod unit;
117pub mod validate;
118
119pub use confidence::{Assessment, Ledger};
120pub use decay::StalenessPolicy;
121pub use graduation::{Approval, GraduationPolicy};
122pub use id::UnitId;
123pub use kind::UnitKind;
124pub use principal::{Attestation, ConfirmationPolicy, MemberClass, PrincipalId};
125pub use time::Timestamp;
126pub use unit::{Evidence, Insight, KnowledgeUnit, Severity, Tier, UnitStatus};
127pub use validate::{validate, Limits};
128
129/// The README's examples, compiled and run as doctests.
130///
131/// A README that has drifted from the API is worse than no README, and the only
132/// reliable guard is to make it fail the build.
133#[cfg(doctest)]
134#[doc = include_str!("../README.md")]
135pub struct Readme;