Crate waggle_core

Expand description

§waggle-core — the sans-I/O domain

The core performs no I/O, owns no clock, and generates no entropy (design doc 03 §1). Every effect is a parameter:

randomness arrives through Entropy (blanket-implemented for closures — function passing, not global state),
time arrives as a Timestamp value in every signature that needs one,
storage never appears here at all (see waggle-store).

This is what lets the identical code run in the native daemon, in Cloudflare Workers wasm, and under deterministic tests.

CP-0 shipped the foundation trio: Token, Timestamp, Entropy. CP-1 adds the domain model: slugs (Sharer, Channel, Stage), targets (CanonicalUrl, TargetMeta, MediaRef), the three-zone AttributionManifest with variants, and mint — a pure function of (spec, options, entropy, now). The sealed variant matcher and folds land in CP-2/CP-3 (design docs 02–04).

use waggle_core::{Entropy, Token};

// A deterministic entropy source: fine for tests, never for production.
let mut counter = 0u8;
let mut entropy = |buf: &mut [u8]| {
    for b in buf.iter_mut() {
        counter = counter.wrapping_add(41);
        *b = counter;
    }
    Ok(())
};
let token = Token::generate(8, &mut entropy).expect("entropy never fails here");
assert_eq!(token.as_str().len(), 8);

Modules§

trust: Trust (design doc 14 CP-11): Ed25519 signatures over the manifest’s immutable core — the three-zone design’s payoff: lifecycle and cosmetic mutations never invalidate a signature, because they never touch what was signed.

Structs§

ActorClass: The actor dimensions an event may carry — three coarse classes, packed into one byte in the analytical log.
AttributionManifest: The stored, retrievable record behind a token (doc 02 §2).
CanonicalUrl: The permanent identity of an artifact — a file path, workspace URI, or URL. Never mutated by sharing; tokens point at it (02 §1).
Channel: Where a share lives: x-twitter, slack, qr-event, subagent/researcher, … One token per channel is the design’s rule; the API enforces it by taking exactly one.
Contract: The consumption contract: which regions must be reached, and what fraction of them (permille) satisfies the author.
Coverage: The verdict Contract::evaluate returns: how much of the contract was reached, whether that satisfies the author, and — the honest half — exactly which regions nobody touched.
EntropyError: Failure of an entropy source.
Event: One thing that happened to a token. No payload field exists — the type system, not policy, keeps recipient data out of analytics (I-1).
EventLog: The seven-column SoA log. Fixed-width rows — a consequence of I-1 (events carry no payload), and the load-bearing fact behind lock-free tail reads in stores (doc 15 §2). The regions column packs the contract touch bitmask; 0 doubles as “none” because an empty mask carries no information (unlike variant, where index 0 is real).
FunnelFold: Counts stages per token. Commutative across tokens by construction — counts don’t care about cross-token order (doc 04 §2).
InternTables: Append-only intern tables. Extension is committer-owned in stores (G-1); in-process users own their instance, so &mut is the guard.
LineageFold: The delegation forest: parent → children, from Minted records (doc 06 §4 — coordination trace, attribution roll-up, cascade path).
ManifestFold: Materializes manifests: Minted inserts; mutations apply in arrival order (reconstruct orders per-token by seq, so arrival order is commit order — doc 04 §2). Lifecycle changes bump version (the CAS baseline C-9); cosmetic changes don’t.
MatchExpr: Which resolver contexts a variant serves. A conjunction over four dimensions; specificity = number of constrained dimensions.
MediaRef: Bytes by reference: where they live, what they are, and the integrity hash a resolver verifies after fetching (rev 2.3). Bytes never ride the log or a tool response — delivery is out-of-band.
MintOptions: Tuning for mint. Defaults are the product decisions from the design docs; override only with a reason.
MintSpec: Everything a mint needs, gathered with a builder. The one-call form is MintSpec::new(target, sharer, channel) — variants, meta, lineage, and ttl are escalations, never prerequisites (doc 17 §1 rule 3).
ModalitySet: A set of consumer modalities, as a small bitset.
Region: One required region: a 1-based inclusive line range with an optional human label (the section heading it came from, typically) so misses can be named, not just numbered.
RegionTouchFold: Accumulates contract region touches per token: the OR of every event’s regions bitmask (doc 19 §4.2). Commutative and duplicate-tolerant by construction — OR is both — so R-1/R-3 hold without ceremony. coverage evaluates this against the manifest’s declared crate::Contract.
Resolution: What a consumer holds after resolving (doc 02 §2, rev 2.1 G-3).
ResolverContext: The neutral resolver-context schema — waggle’s lingua franca. External schemas (harness metadata, A2A cards) reach it through extractors.
Selected: The outcome of selection: which variant, and where it sat. The index is what Event.variant records (doc 02 — manifest-referencing, so I-1-compatible) and what the authoring feedback loop keys on (06 §6).
Seq: Per-token monotonic sequence number, assigned by the store at append (contract C-3). Identity of a record is (token, seq) — the dedup key (C-4).
Sha256Error: Why a digest string was rejected.
Sha256Hex: A lowercase-hex SHA-256 digest (64 chars), validated on construction.
Sharer: Who performed a distribution act. Deliberately not an authenticated identity in the core — hosts bind sharers to their own auth (02 §2).
SignatureBlock: A detached signature over the manifest’s IMMUTABLE core (doc 14 CP-11): mutations never touch what was signed, so lifecycle churn never invalidates it. Set by the host at mint; verified by anyone.
Stage: A funnel stage. Well-known constructors below; custom stages are any valid slug — the open vocabulary is what extends the funnel past the click into the consuming product’s own lifecycle.
StageId: Dense stage identifier (interned).
TargetMeta: Mint-time snapshot of what the target is — supplied by the minter, never scraped (I-3). This is what unfurls render and what agents read before resolving.
Timestamp: Milliseconds since the Unix epoch, as a value.
Token: A waggle token: inline, Copy, 24 bytes total.
TokenId: Dense token identifier (interned, per-store).
Variant: One projection of the artifact for a class of consumers.
WorldState: The world at a log prefix: manifests, funnels, lineage. Serialization is deterministic (BTreeMap everywhere) — R-1’s “byte-identical” is checked against the serialized form.

Enums§

Change: A change to a manifest’s mutable sections. Lifecycle changes are CAS (C-9, checked at the store’s commit point); cosmetic changes are LWW by commit order.
Constraint: One dimension’s constraint in a MatchExpr: unconstrained, or an allow-set. Kept as data — expressiveness grows by adding dimensions, never by adding cleverness (doc 06 §2).
ConsumerHint: What a consumer presented at the door.
ConsumerKind: The coarse consumer class — the maximum actor granularity the event log may ever hold (invariant I-7).
ContractError: Why a contract was rejected at construction.
Disposition: A token’s lifecycle disposition at a point in time.
FamilyClass: Coarse model-family class — the maximum granularity events may hold (I-7). Families, never versions or instance identifiers.
HarnessClass: Coarse harness class (same discipline as FamilyClass).
LogRecord: One record in the append-only log. A closed enum: new kinds are additive; folds ignore kinds they don’t know (doc 13 §4), which is what keeps the replay promise compatible across schema growth.
MintError: Why a mint was rejected.
Outcome: A token’s judged outcome, derived from the accepted/rejected stage counts (doc 19 §4.1): the verdict IS the stage, so the log stays payload-free (I-1) and this derivation is a pure function of counts — order-free, replay-stable (R-1).
Posture: The consumer’s execution posture.
SlugError: Why a slug was rejected.
TargetError: Why a target URI was rejected.
TokenError: Why a token could not be parsed or generated.
VariantBody: A variant’s body: small content inline, larger content by reference (rev 2.3 — the threshold is automatic at mint, doc 02).

Constants§

DEFAULT_REVALIDATE_MS: Default advisory freshness window when a variant declares none: 15 minutes. A resolution is knowledge, not a lease (G-3) — this is the “re-resolve before acting” hint, not an enforcement mechanism.
FULL_COVERAGE_PERMILLE: The threshold meaning “every declared region must be touched”.
INLINE_THRESHOLD_BYTES: Bodies at or under this many bytes may inline in a manifest; above it they become a MediaRef into the content-addressed store. Chosen at the range where SQLite’s small-blob reads beat the filesystem (02).
MANIFEST_SCHEMA_VERSION: Schema version of the manifest envelope — versioned independently of crate semver; additive changes only (doc 09 §6).
MANIFEST_SIZE_CAP_BYTES: Total manifest size cap — mint rejects manifests that exceed it (02).
MAX_CONTRACT_REGIONS: The most regions one contract may declare — the width of the region-touch bitmask on events.
TOKEN_ALPHABET: The Bitcoin base58 alphabet: 58 symbols, no 0, O, I, or l.

Traits§

Entropy: A source of cryptographically secure random bytes.
Fold: A pure accumulator over log records. apply performs no I/O and asks no clock; unknown record kinds must be ignored (additive schema growth — doc 13 §4).

Functions§

apply_change: Apply one mutable-section change to a manifest — THE mutation semantic, shared by ManifestFold, every backend, and reconstruct so they can never disagree (R-4’s precondition). Lifecycle changes bump version (the C-9 CAS baseline); cosmetic changes don’t. CAS checking is the store’s job at its commit point; this function only applies.
apply_suffix: Continue a snapshot with later records (R-2’s replay half). The suffix must already be per-token seq-ordered relative to the snapshot — stores guarantee this by construction (C-3).
mint: Mint an attribution manifest. Pure: same inputs (including the entropy stream) ⇒ same manifest.
negotiate: Turn a hint into a context. Pure and total: unknown user agents are humans (the safe default — disclosure, not projection).
outcome_of: Derive the Outcome from a token’s stage counts (the shape FunnelFold and every store’s funnel view produce).
reconstruct: Rebuild the world from records, in any arrival order, with duplicates.
replay: Run records through fold (one pass) and hand the fold back.
resolve: Resolve manifest for ctx at now. Pure, total, deterministic — the sealed matcher does the selection; disposition gates what is served.
select_variant: Select the variant for ctx from variants (declaration order).