Skip to main content

Crate colloquy_core

Crate colloquy_core 

Source
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

ModuleOwns
unitThe knowledge unit: cq’s wire schema.
kindThe ladder — pitfall, workaround, tool recommendation, gap signal.
idContent-addressed ku_… identifiers.
principalAuthorising principals, and the collapse that makes counts honest.
confidenceAttestations in, diversity-weighted evidence out.
decayPer-kind staleness.
graduationTier promotion and the human gate.
validateLimits, including the embedding window.
clusterLevel-2 workarounds aggregated into level-4 gap signals.
timeRFC 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.