Expand description
colloquy-core — the cq shared-agent-learning standard, in pure Rust.
Agents that work alone rediscover the same failures independently. cq is an open standard for stopping that: agents query a shared store before acting, propose what they learned, confirm what held, flag what rotted, and graduate durable knowledge upward through a human gate. This crate is a clean-room implementation of the standard’s data model and rules.
It is deliberately pure: no clock, no I/O, no network, no store. Every
time-dependent function takes now as an argument, which is what lets the
same crate drive an agent runtime natively and a wasm32 edge worker, with
both computing byte-identical confidence for the same evidence.
§The shape of it
| Module | Owns |
|---|---|
unit | The knowledge unit: cq’s wire schema. |
kind | The ladder — pitfall, workaround, tool recommendation, gap signal. |
id | Content-addressed ku_… identifiers. |
principal | Authorising principals, and the collapse that makes counts honest. |
confidence | Attestations in, diversity-weighted evidence out. |
decay | Per-kind staleness. |
graduation | Tier promotion and the human gate. |
validate | Limits, including the embedding window. |
cluster | Level-2 workarounds aggregated into level-4 gap signals. |
time | RFC 3339 timestamps without a date library. |
§The two rules worth knowing before reading the code
Confidence follows principals, not confirmations. cq’s trust model says
three confirmations from three independent parties outrank eight hundred from
two. Implemented over accounts that rule is defeated by anyone who can create
accounts — and in an agent estate, creating an account is a command. So every
attestation is folded onto its authorising principal before it is weighed:
an operator’s fifty agents count once. See principal::collapse.
A flag suppresses nothing. Flagging lowers a unit’s standing and marks it
unit::UnitStatus::Disputed, which is still served. Only a signed decision
retires a unit, so no single member can remove knowledge from the store by
objecting to it. See confidence::Ledger::apply.
§A unit’s life, end to end
use colloquy_core::{
confidence::Ledger, graduation::{graduate, Approval, GraduationPolicy},
kind::UnitKind, principal::Attestation, time::Timestamp,
unit::{Insight, KnowledgeUnit, Tier, UnitStatus}, validate::{validate, Limits},
};
let t0 = Timestamp::parse_rfc3339("2026-01-01T00:00:00Z").unwrap();
// An agent proposes what it learned. Proposing is not confirming.
let mut unit = KnowledgeUnit::propose(
"did:nostr:scribe",
UnitKind::Workaround,
["http", "retry-semantics"],
Insight::new(
"A regenerated idempotency key turns one retry into two charges",
"The client mints a fresh key per attempt, so the provider sees distinct requests.",
"Derive the key from the order id, never from the attempt counter.",
),
t0,
);
validate(&unit, &Limits::default()).unwrap();
assert_eq!(unit.lifecycle.status, UnitStatus::Draft);
// Two independent principals confirm it — one of them a person.
let mut ledger = Ledger::default();
ledger.confirm(Attestation::agent("auditor", "did:nostr:bob", t0.plus_secs(3_600)));
ledger.confirm(Attestation::human("did:nostr:alice", 0.9, t0.plus_secs(7_200)));
let assessment = ledger.apply(&mut unit, &Default::default(), &Default::default(), t0.plus_secs(7_200));
assert_eq!(unit.lifecycle.status, UnitStatus::Active);
assert_eq!(assessment.distinct_principals, 2);
assert!(unit.evidence.confidence > 0.5);
// A person approves promotion to the shared tier.
graduate(
&mut unit, &ledger, Tier::Shared,
&Approval { approved_by: "did:nostr:alice".into(), at: t0.plus_secs(9_000), authorising_event: None },
&GraduationPolicy::for_tier(Tier::Shared),
&Default::default(), &Default::default(), t0.plus_secs(9_000),
).unwrap();
assert_eq!(unit.tier(), Tier::Shared);§Relationship to cq
The wire schema is cq’s, so units round-trip between implementations. Two
fields are ours and both are additive, which is what keeps that true:
unit::Graduation::authorising_event makes a human approval checkable
rather than merely asserted, and unit::UnitStatus::Disputed separates
“contested” from “withdrawn”.
cq is published by Mozilla AI under the Apache-2.0 licence; this crate is an independent implementation of the documented standard and carries the same licence.
Re-exports§
pub use confidence::Assessment;pub use confidence::Ledger;pub use decay::StalenessPolicy;pub use graduation::Approval;pub use graduation::GraduationPolicy;pub use id::UnitId;pub use kind::UnitKind;pub use principal::Attestation;pub use principal::ConfirmationPolicy;pub use principal::MemberClass;pub use principal::PrincipalId;pub use time::Timestamp;pub use unit::Evidence;pub use unit::Insight;pub use unit::KnowledgeUnit;pub use unit::Severity;pub use unit::Tier;pub use unit::UnitStatus;pub use validate::validate;pub use validate::Limits;
Modules§
- cluster
- Level 2 to level 4: turning recurring workarounds into a build signal.
- confidence
- Turning attestations into evidence.
- decay
- Per-kind staleness: knowledge that is not re-confirmed goes quiet.
- graduation
- Promotion between tiers, and the structural reason no one graduates alone.
- id
- Content-addressed unit identifiers.
- kind
- The ladder: what kind of knowledge a unit is, and what that implies.
- principal
- Principals, members, and the collapse that makes confirmation counts honest.
- time
- UTC timestamps with RFC 3339 wire form, and no dependency on a clock.
- unit
- The knowledge unit: cq’s interoperable record, in Rust.
- validate
- Validation, and the one limit that is not a matter of taste.