Two plain classes become a two-peer fleet: a kill-tolerant worker and an auditor that reacts to every result. Nothing here deploys a broker, a registry, or a scheduler; the coordination fabric is a library inside your application.

1. Add the starter

2. Describe the fleet, once

The starter reads one YAML block: an identity keystore, a group every member derives the same self-certifying id from, and the spaces the group shares. Start a second JVM with the same block and a seed address, and you have a fleet.

3. Write the agents

The worker takes orders under a lease and returns shipments; the auditor reacts to every shipment and returns a receipt. Both are complete as shown.

4. Put work in

What you now have: the order replicates to every peer, one fulfiller wins the take fleet-wide, the shipment and receipt appear as signed entries, and if you kill the working JVM mid-task the lease lapses and the order reappears for another. Run examples/example-11-quickstart to watch exactly this over two TCP peers.

The annotation model is the top of the stack and the whole API most applications need. Six annotations cover identity, work, choreography, economics, access, and capability services; each maps to protocol behavior the layers below carry for you.

They go on ordinary objects. There is no base class to extend, no interface to implement, and no container of ours to run in: the binder reflects over an instance you hand it, wires whatever it finds, and leaves the rest of the class alone. Constructors, other Spring beans, JPA repositories, your own fields — all untouched. That matters for how you organize a fleet, so each annotation below says plainly where it belongs and what else is allowed to sit beside it.

@AgentSpec declares an agent's identity on any class, framework or not. Under Spring, prefer the @SpaceAgent stereotype: it is both a @Component and an @AgentSpec, so component scanning and fleet enrollment are one drop. Binding publishes an AgentCard built from the identity plus the bound method signatures, so other peers can discover what this agent consumes and produces with no extra code.

Turns a method into a leased take loop. The parameter type is the template; a normal return completes the take and writes the result atomically; a thrown exception skips completion so the lease lapses and the task reappears for another worker. The failure path is the happy path with nothing added.

Reach for @SpaceTake whenever work is a queue of units that exactly one worker should do: research requests, document conversions, booking orders, anything you would otherwise put on a job queue. Scale is horizontal and needs no configuration — start a second process with the same class and the same queue drains twice as fast, because both are racing for the same entries. The lease is the whole failure story: kill a scout mid-search and its TAKE lease lapses, the request reappears, and a sibling picks it up.

Invoked for every matching entry written to the space, without consuming it, and a non-void return value is written back as the next entry in the flow. React to X, produce Y; Y is some other agent's cue. The binder carries the discipline so the method body never has to: delivery is deduplicated per entry (at-least-once becomes effectively once per bound agent), the reaction runs on its own virtual thread so slow work never holds the fabric's delivery thread, and a null return writes nothing.

Reach for @SpaceNotify when the trigger is "something appeared" rather than "there is work to claim". Nothing is consumed, so every interested agent sees the same entry — which is exactly what you want for fan-out, for derived records, and for side effects like audit and notification. Returning a value is the compact form of a pipeline: an agent that returns Y from an X has declared one edge of a flow, and the next agent's @SpaceNotify on Y is the next edge. Nobody wires the graph; it exists because of what each agent consumes and produces.

The example above shows both halves of the common shape: react with @SpaceNotify, then write through @SpaceRef handles when one reaction needs to produce many entries, or entries in other spaces, rather than the single entry a return value can express.

On an AUCTION space, every take carries a bid and the lowest bid wins the entry. The bid is a plain method over the entry, so cost models are ordinary code: denominate in dollars, tokens, or queue depth, and let FinOps tune it.

This is the shape worth studying, because it answers the organizing question directly: the bid function, the worker, and the space handle live in the same object. That is deliberate. A bid is a statement about what this particular agent would charge, so it needs the same state the work needs — the model it would call, the queue it is already sitting on, the region it runs in. Splitting them apart would mean keeping two things in sync for no gain.

Reach for AUCTION when workers are not interchangeable and you want the fleet to sort that out without a router. Several planners bid on every day of a trip; the one whose day it should be bids lowest and wins, and nothing anywhere contains a rule saying who plans what. Change a bid function and you have re-tuned the whole allocation. The same shape does cost-aware model routing (cheap capacity sweeps easy work, the expensive model wins the hard entries), locality routing, and load shedding by bidding your own queue depth.

Injects a Space into a field at bind time, for mid-method writes such as progress markers and side outputs. Under Spring, @Scheduled plus a @SpaceRef field is the idiomatic periodic agent; AgentSpaces ships no scheduler of its own. What arrives is the registered space itself — or, when the fleet runs with agentspaces.identity.agent-keys=subordinate, this agent's view of it, so everything the agent writes, takes, or completes through the field is signed with the agent's own certified key and attributed to the agent, not merely to its host peer (chapter 6). The field's type and your code do not change either way.

Use it whenever one invocation has to produce more than the single entry a return value can express: progress markers mid-task, fan-out like the dispatcher's, side outputs into a different space, or reads that inform the work (the dining planner reads what the scouts found before it writes a schedule). The field is a fully-featured Space — every verb of chapter 4, not a write-only sink.

It is also the answer to "how do I get a space into code that is not a bound method". A @Scheduled method, an HTTP controller method, a message-listener callback: annotate the field, and as long as the enclosing bean is enrolled, the handle is there. AgentSpaces ships no scheduler, no HTTP layer, and no inbox of its own precisely because your framework already has them.

The first of the Layer 4 annotations, and the shape the others follow: the method's parameter is the cue and its return value is what the binder does with it. Here the cue is the vote's own Proposal entry and the return is the option this agent backs; the binder casts the ballot through the group's vote capability, as this agent, exactly once per proposal, and a null return abstains. Because the cue is the proposal record, the ballot can never be refused as "unknown proposal" — the two-entry race every hand-written panelist had to defend against does not exist.

Attributes: space (the vote space; empty resolves to the sole registered vote), prefix (only proposals whose id starts with it — one vote space usually carries several decisions, the Party Bus keys them advisory: and next:), lease for the ballot, and group. Under agent-keys=subordinate the ballot is the agent's own attested record, so several agents on one peer are several voters wherever the authorizer counts per agent (chapter 6).

The pair of @Ballot. The method takes the Decision and runs exactly once per proposal, the first time this replica's tally meets the quorum; a non-null return is written as the next entry in the flow, like @SpaceNotify. Underneath, the binder watches ballots and proposals in the vote space and recomputes the decision on each, so a replica that learns of a vote late still fires once, on its first qualifying ballot. This replaces the decision() poll loop that every consumer of the vote used to write.

@SpaceTake's contract — take, act, complete-or-lapse — with the take routed through the space's ordered-log coordinator instead of the space's own claim race, so the log's commit order decides every take identically on every member and each entry is completed at most once, fleet-wide. The binder owns the loop the coordinator asks of a caller: a take lost to a leader election is simply resubmitted on the next poll. This closes what the space chapter used to call "the one place the annotations cannot reach".

The sibling of @SpaceRef for Layer 4: a field of a typed client type — VoteClient, AggregateClient, SemanticClient, or anything registered with binder.client(type, instance) — is injected at bind time from the group's typed clients. Constructor injection still works and is still fine; this is for when the agent should not have to be handed its capabilities by whoever constructs it.

Marks a CapabilityProvider implementation as a service the fleet should advertise. Bound through the facade, it is registered on the group's CapabilityRuntime, which starts it, signs and publishes its CapabilityAdvertisement, and keeps that advertisement fresh on every card refresh — the same TTL-leased freshness every other card gets. Consumers reach it through a typed client (chapter 5).

You need this only when your peer is the one serving a capability. Most peers consume capabilities instead, which needs no annotation at all — see chapter 5. And with the starter you rarely write this either: agentspaces.capabilities.* already registers the aggregate, vote, semantic-discovery and key-wrap providers for you. Write the bean when you want a capability the starter leaves off (the ordered log, which needs a member set the starter cannot guess), when you want to configure one differently (a gossip learner with a real training step), or when you are publishing a capability of your own.

• Space inference. Every space attribute is optional. Empty resolves to the group's sole registered space; several spaces without a name fail fast at bind time, listing the candidates.
• Group selection. Every binding annotation takes an optional group, by application-facing name or GroupId value. A binder for a different group treats the member as not its own and skips it, so one bean can bind methods into several groups at once; the facade's bind(...) routes the bean to every group its annotations name.
• Durations. Every duration accepts Spring-style simple strings ("10m", "500ms", "30s", "2h", "1d") and ISO-8601 ("PT10M").
• Method shape. Bound methods take exactly one parameter: the entry, or for the vote annotations the Proposal (@Ballot) and the Decision (@OnDecision). @BidFunction returns double, @Ballot the option as a String (null abstains); the others return the next entry, a Contribution to an aggregate epoch, or void.
• Names. An agent's name comes from @AgentSpec (or the class); bind(agent, name) overrides it, so several instances of one class can be several agents — a council of seats, one class.
• Cards for free. Consumed and produced types are collected from the signatures and published on the agent's card, TTL-leased and auto-refreshed.
• Nothing is reserved. The binder reads the annotations and ignores everything else on the class. Other frameworks' annotations, other interfaces, other methods and fields all keep working, which is why an Embabel @Action becomes a fleet worker by adding one annotation rather than by being rewritten.

Choosing between them

Three questions settle almost every case. Should exactly one agent handle this entry? If yes, @SpaceTake; if every interested agent should see it, @SpaceNotify. Are the candidate workers interchangeable? If not, put the space on AUCTION and add a @BidFunction, and let the cheapest one take it. Does one trigger produce more than one entry, or entries elsewhere? Then add @SpaceRef and write them yourself rather than contorting a return value.

The two failure models are the thing to hold on to, because they decide where risky work belongs. @SpaceTake retries forever by default: a crash, a kill, or a thrown exception all lapse the lease and the entry comes back. @SpaceNotify does not retry at all: a reaction that throws is logged and gone. Put work that must eventually happen behind a take; put reactions that are nice to have behind a notify.

The starter (agentspaces-spring-boot-starter) wires the peer from properties and enrolls annotated beans through an ordinary bean post-processor. It deliberately declares no Spring dependency of its own; it compiles against a provided-scope stub surface and binds to the Spring your application already runs.

One property sets the whole posture. agentspaces.security.profile picks the transports and channel mode a fleet forms over — the default, mtls, means a fleet comes up over TLS with attested channels and no further configuration — and it also picks who answers the one question every privileged operation asks: authorizer.permits(peer, operation, scope).

Under dev-local and mtls the answerer is membership-rooted, one authorizer per group over the group's admitted members, narrowed by the optional grants lists; a grant never outlives admission. Under mtls-oidc and zero-trust it is your identity provider: each peer carries its JWT inside its own signed self-advertisement, the token's agentspaces_peer claim binds it to one PeerID, and scopes of the form aspace:<operation>[:<scope>] decide. Incomplete OIDC configuration fails at startup rather than at the first refusal.

The starter threads the authorizer into the key-wrap provider, spaces admitted by authorizer, the vote tally, and the DirectiveGates bean workers use to obey the console. Pass the Authorizer bean, or Authorizers.forGroup(name), to a RaftLog, DataQueryClient, or ConnectorRuntime you wire yourself.

After initialization, any bean declaring an agent identity or carrying bound methods enrolls automatically: bid functions wire first, worker loops start, subscriptions register, @SpaceRef fields inject, and the card publishes into every joined group. Group selection is by space coverage, narrowed by any group attribute the annotations carry: a bean binds into each configured group whose spaces cover the spaces it names, and a bean naming a space no group registers fails at startup, which is when a configuration mistake should surface. A @ProvidesCapability bean registers on the group's capability runtime the same way. Plain beans pass through untouched.

The facade bean is there when you outgrow the annotations: AgentSpaces navigates groups and spaces Embabel-style, with the typed verbs of chapter 4 as terminal operations.

The embabel-agentspaces extension activates only when Embabel is on the classpath, and it works in both directions: your Embabel agents become discoverable to the fleet, and the fleet's discovered skills become actions for your planner.

Every Embabel @Agent bean's metadata, its description, its @AchievesGoal statements, and its @Action input and output types, becomes a published AgentCard automatically. Worker loops still come from @SpaceTake on the action, so an Embabel action joins the fleet with one added annotation:

The remote-actions bridge turns every foreign AgentCard in the group into a typed, invocable action. Invoking one is choreography, never RPC: the bridge writes the input entry where the remote workers take that type from, then awaits a result entry that correlates with the request (by default, equal values on every record component name the input and result share, the convention a Finding carrying its ResearchTask's topic already follows). A remote worker that crashes mid-step lets its lease lapse; whoever finishes, the awaited result still arrives. An invocation nobody serves times out empty with the entry still leased in the space.

For the GOAP planner, EmbabelRemoteActions generates a class annotated @Agent with one real typed @Action method per remote action (card goals surface as @AchievesGoal), because the planner conditions on method signatures. The proven consequence: an agent whose local actions cannot chain to a goal type finds no plan alone, and finds and executes the multi-hop plan through remote specialists the moment the fleet's cards are bridged in. Cards are TTL-leased, so the planner's action space tracks the live fleet.

Deployment keeps itself current. With agentspaces.embabel.auto-deploy on (the default) a deployer watches the bridge's registry on a virtual thread and redeploys a freshly generated agent whenever the set of actions changes — the first time cards arrive, when a new card brings a new capability, and when an expired card takes one away. A card refresh that changes nothing but the issue time does not redeploy. Embabel's platform exposes no undeploy in the surface this module reaches, so an action that disappears is absent from the next generated agent while the previous generation stays registered until the platform restarts; invoking one of its vanished actions times out and throws, which the planner treats as the action failing.

One layer down from the annotations sits the interface they compile to: a typed, leased tuple space. Entries are plain records; every entry is signed by its writer and expires unless renewed; every peer holds a replica that keeps answering through partitions.

Before the verbs, the practical question: where does a Space come from? There are three sources, and they return the same object — a space is a space however you reached it.

take is destructive and exclusive under the space's conflict strategy; the taker holds a TAKE lease and must complete before it lapses, or the entry reappears. complete with a result validates and prepares the result record before committing the completion, so a task can never end up completed but resultless. Reads run against the local replica and never block on the network.

readAllIssued returns each match as an Issued<T>(T entry, AgentId issuer, Attestation attestation), where the issuer is authenticated by the entry record's signature and the attestation says how: PEER_ASSERTED when the hosting peer's key signed and vouched for the name, AGENT_ATTESTED when the agent's own peer-certified key signed (chapter 6). Any reader that makes a trust decision per entry — a vote tally, an audit reader, a result consumer — uses this rather than a field the entry declares about itself. SpaceEvent carries the same authenticated issuer.

notify events arrive at least once with entry deduplication available to you via the event's entry id; listeners must return promptly (the @SpaceNotify binder does both disciplines for you, which is why it is the recommended surface). Event kinds are WRITTEN, TAKEN, COMPLETED, EXPIRED (a write lease lapsed and the entry vanished) and REAPPEARED (a TAKE lease lapsed and the entry came back).

ReplicatedSpace adds a consistency hint on read and readAll. The default, ConsistencyHint.LOCAL, matches the replica as it stands; FRESH triggers exactly one anti-entropy pull toward one random member before matching locally — the cheap "make sure I am current" a late joiner or an operator console wants, without changing the local-first default for everyone else.

Matching is by type plus field predicates. The matchers (ai.badmonkey.agentspaces.api.space.Matchers): eq, ne, gt, gte, lt, lte, in(values...), contains(fragment) for character sequences, isNull, notNull, and predicate(fn) as the escape hatch. Fields resolve through record components; on a non-record type the usual getX/isX accessors are read instead. An unknown field name throws at where(...) time, listing the fields the type does have.

Lease.of(Duration) is the only constructor you need. A write returns an EntryHandle with renew(extension) and cancel(); cancellation is issuer-signed, so nobody else can withdraw your entry. Everything shares the one failure idiom: state you stop renewing goes away, and nothing needs a cleanup job.

The first two are strategies the space itself decides in its claim lattice, chosen when the space is built. The third is not a space setting at all — see the note below the table.

A space fixes one strategy for all its entries; use several spaces the way you would use several queues (tasks-bulk, tasks-auction, commits).

Taking through the ordered log

Exactly-once is one annotation now: @OrderedTake (chapter 1) is @SpaceTake with the take routed through the space's ordered-log coordinator, so the loop, the resubmit after a leader election, and the complete-or-lapse are the binder's. What stays yours is the quorum: a fixed member set, one coordinator per space, built with OrderedTakes.over(...) and registered on the group. The exactly-once desk and the Party Bus booking clerks are the worked examples.

Reach for this only where a duplicate is genuinely unacceptable and you would otherwise reach for a distributed lock: charging a card, filing a return, allocating a serial number, sending a message a customer will see once. Everywhere else LEASE_RACE is cheaper and more available, and the duplicate work it can produce across a partition is the price of continuing to run at all.

A space advertises how it admits writers, independently of how the group admits members. Reads stay open to the group in every mode.

• GROUP (the default) admits every admitted member of the group.
• ALLOWLIST admits a fixed set of agents. A local caller outside the list gets a SpaceAdmissionException; an inbound record or claim from an unlisted agent is dropped and reported as misbehavior.
• CREDENTIAL admits whoever holds a live credential from the issuer. A credential is an ordinary leased SpaceCredential entry the issuer writes into the space itself, so nothing new appears on the wire: the issuer's node grants with space.grant(agent, scopes, validity) and revokes with space.revoke(agent), which is just a signed cancellation. A transition whose credential has not merged yet is dropped without a strike, because the evidence can legitimately arrive after the write it authorizes.
• AUTHORIZER hands the decision to the profile's Authorizer, scoped by the space name, which is how an identity provider's scopes (aspace:space-write:tasks) end up deciding.

Each transition is judged once as it arrives, after its signature verifies. A refused local call throws; a refused remote delta is dropped, and strikes its sender only when the rule says the refusal cannot be a late credential. The judged identity is the acting agent, never the peer: when several agents of one peer share a replica through views (space.as(identity), chapter 6), each view is admitted or refused on its own agent's standing, so an ALLOWLIST or CREDENTIAL space can admit one agent of a peer and refuse its sibling. A record whose spaceId names another space is dropped before any of this, however validly signed.

The starter builds spaces from YAML; plain Java builds them directly. LocalSpace is the single-process form (same API, ideal for tests); ReplicatedSpace attaches to a joined group's runtime.

A space publishes its own advertisement the moment it is created, carrying its strategy, admission, replication mode, and schema hints, and refreshes it on the group's tick. When its founders' lease lapses the space turns read-only rather than silently accepting writes nobody will keep.

Below the space sit the layers that answer "who can do what" and "what does the fleet think": signed, TTL-leased advertisements, and capability services built over the same fabric.

Finding agents, assets, and services

Everything discoverable is a typed, signed card in a per-group cache that gossip keeps fresh; a card whose issuer stops republishing simply ages out. The advertisement families are peers, groups, spaces (with their admission and replication modes), capabilities, AgentCards (with their space bindings), AssetCards, and revocations. The cache verifies every signature, bounds its own occupancy, and evicts by TTL; a peer volunteering as RENDEZVOUS holds four times as much. Query structurally, or by meaning through the semantic-discovery capability (its reference embedder needs no model at all):

Most fleets never call this. Work finds its worker because the worker is sitting on the space taking that type, not because anybody looked anything up — the routing is the entry's type. Discovery earns its keep when you need to know who is out there rather than get one task done: a console drawing the room, a planner deciding whether a capability exists before committing to a plan (chapter 3 builds on exactly this), an operator asking which peers can still do a thing, or a dispatcher that wants to fail loudly when nobody is listening instead of writing an entry into a space where it will sit until its lease lapses.

How a capability is used

Layer 4 is the part of the system people most often wire wrongly, because a capability is not one thing but three, and a given peer may play any subset of the roles.

• The provider is the object that implements CapabilityProvider and serves the capability on this peer. Under the starter, the shipped ones are registered for you from agentspaces.capabilities.*. Otherwise it is a @ProvidesCapability bean (chapter 1).
• The consumer is whatever calls it. Typed clients resolve off the group context — spaces.group("g").capability(VoteClient.class) — and need no annotation at all. Most application code is only ever this.
• The clock is what advances a continuous capability's own protocol — a push-sum exchange, a gossip-learning offer, a Raft election step. You do not supply it. A capability runtime registers its protocol tick with the group's peer tick when it is constructed, so a provider is driven because it is registered, the same way a replicated space converges because constructing it joins that same clock. Nothing to schedule, nothing to remember.

That last point is the one worth internalising, because it is what makes the annotations of chapter 1 enough on their own. One clock runs the whole stack: membership probing, gossip, space anti-entropy, and capability protocols all advance on the peer's tick, at agentspaces.tick-millis (250 ms by default). Set that one property and you have set the convergence rate of the entire fabric.

// There is no driver to write. Registering the capability is the whole of it:
// under the starter this already happened, and under plain Java it happens
// the moment the runtime exists.
AgentSpaces.GroupContext group = spaces.group("orders-fleet");
group.capabilities().isDrivenByPeerTick();     // true

// A test that wants each round to be an exact, countable step takes the clock
// back and drives it by hand -- the same escape hatch a TestClock is for.
group.capabilities()
        .detachFromPeerTick()
        .cadence(Duration.ofMillis(300));      // what you will really tick at

group.capabilities().protocolTick();           // one round, deterministically

Convergence takes a few dozen rounds, so the peer tick period is what turns "converges in O(log N) rounds" into a wall-clock number: at the default 250 ms a fleet settles in a few seconds. Vote, semantic discovery and key wrap are request/response and need no clock at all, which they declare through requiresTick(); the runtime drives them anyway, because the default tick() is a no-op and costs nothing.

Two clocks exist at this layer and they are deliberately different rates. The protocol clock above runs at the peer tick. The advertisement clock, refreshTick(), republishes leased capability advertisements and runs with the card refresh, on the order of minutes. A method named for one will not do the other.

The six capability services

• Vote (aspace:cap/vote): proposals and ballots as signed entries; the decision closes at quorum and any member recomputes the tally from the space. QUORUM mode is the canonical, auditable form, counting one ballot per eligible voter against an electorate of fresh AgentCards narrowed by the authorizer; MAJORITY_GOSSIP is a cheap approximate temperature check by push-sum. The voter is derived from the entry's authenticated issuer, never from a field the ballot declares.
• Aggregate (aspace:cap/aggregate): push-sum gossip; every member converges on a fleet-wide figure with no collector. Six operators — SUM, AVG, COUNT, MIN, MAX, QUANTILE — over a supplied value or over a template's matching entries. aggregate.start("backlog", localValue), then estimate("backlog").
• Ordered log (aspace:cap/ordered-log): a small Raft among volunteers, with the leader lease published as an advertisement; backs the ORDERED strategy and any workflow needing a total order. Off by default, since it needs a fixed member set.
• Gossip learning (aspace:cap/gossip-learn): mergeable models exchanged pairwise converge to the fleet mean with no parameter server; content-addressed, with a mass-conserving offer-and-accept exchange. Suits learned bid policies. Off by default; enabling it wires the default weight-averaging learner.
• Semantic discovery (aspace:cap/semantic-discovery): an embedding index over the group's advertisements behind a pluggable Embedder. query(text, limit) searches locally, remoteQuery(text, limit, timeout) escalates; the shipped hashing embedder needs no model at all.
• Key wrap (aspace:cap/key-wrap): distributes group content keys sealed per member (X25519 + HKDF + AES-256-GCM), so encrypted spaces onboard members without any shared secret in transit.

Typed capability clients

Consumers do not speak the capability's entries directly. A client type resolves off the group context, and the client finds the providers, speaks the protocol, and hands back ordinary values:

Register your own with spaces.clientFactory(new MyClient.Factory()), and serve your own capability with a @ProvidesCapability bean (chapter 1).

Reaching a capability from inside an agent

// agentspaces-partybus -- Party.TravelerAgent: contributes to the aggregate and votes, with no vote code
@AgentSpec(name = "traveler", description = "Reports energy each day and votes on the party's choices")
public static final class TravelerAgent {
    private final PushSumAggregate aggregate;      // constructor-injected, or @CapabilityRef AggregateClient
    @SpaceRef(TRIP) Space trip;

    @SpaceNotify(space = TRIP, lease = "12h")
    public EnergyReport feel(TripDay day) {
        int energy = energyOn(day, ...);
        aggregate.start(Itinerary.energyEpoch(day.tripId(), day.date()), energy);
        return new EnergyReport(day.tripId(), day.date(), name(), energy);
    }

    @Ballot(space = DECISIONS, prefix = "next:", lease = "12h")
    public String decide(VoteCapability.Proposal proposal) {
        return preference(proposal.options());       // the cue is the proposal itself: no wait, no voted set
    }
}

Worked example: sensing the fleet with aggregate

// Every member contributes its own number to a named epoch...
aggregate.start("backlog", myQueueDepth());

// ...the peer tick exchanges them, and after a few dozen rounds every member
// reads the same fleet-wide figure. Empty until the first round completes:
// a capability that has not run yet will not pass its own seed off as a
// fleet answer.
OptionalDouble sensed = aggregate.estimate("backlog");

// A supervisor can then act on what the whole fleet feels, not on its own view:
if (sensed.orElse(0) > BACKLOG_THRESHOLD) {
    vote.propose("scale-up-1", "Average backlog is " + sensed.getAsDouble()
            + "; add two workers?", List.of("approve", "reject"),
            4, Lease.of(Duration.ofMinutes(10)));
}

Worked example: gossip learning

// 1. Build the learner. The starter's gossip-learn toggle gives you a pure
//    averaging learner; to train, construct your own and publish it as a bean.
@Component
@ProvidesCapability(GossipLearning.TYPE)          // "aspace:cap/gossip-learn"
public class BidPolicyLearner implements CapabilityProvider {

    private final GossipLearning learning;

    public BidPolicyLearner(AgentSpaces spaces, CborCodec codec) {
        AgentSpaces.GroupContext group = spaces.group("orders-fleet");
        // The builder is the configurable form: a training step, and a metrics
        // space so endEpoch below has somewhere to write.
        this.learning = new GossipLearning(GossipLearner.builder(
                        group.pipes(), group.runtime().sampler(),
                        group.identity().peerId(), codec, group.clock(),
                        WeightAveraging.INSTANCE)
                .localUpdate(params -> sgdStep(params, batch()))  // the training step
                .metrics(group.space("metrics"), Lease.of(Duration.ofDays(7)))
                .build());
    }

    @Override public String capabilityType() { return learning.capabilityType(); }
    @Override public CapabilityAdvertisement describe(GroupId g) {
        return learning.describe(g);
    }

    // 2. Join the model. Every peer must use the same id and the same length.
    @EventListener(ApplicationReadyEvent.class)
    public void join() {
        learning.start("bid-policy", new double[]{1.0, 0.0, 0.5});
    }

    // 3. Advance the protocol. Inherited from CapabilityProvider and called by
    //    the peer tick because this bean is registered -- you write no driver.
    @Override
    public void tick() {
        learning.tick();
    }

    // 4. Read the current parameters wherever you need them -- e.g. from a
    //    @BidFunction, which is what makes the fleet's bid policy learned.
    public double[] parameters() {
        return learning.model("bid-policy").orElse(DEFAULTS);
    }
}

// And at the end of a training epoch, write one evaluation per model into the
// metrics space, so the fleet's loss curve is itself replicated state:
List<GossipLearner.Evaluation> written =
        learning.endEpoch(epoch, params -> lossOn(params, holdoutSet()));

// Any member can then read everyone's, attributed to its authenticated author:
List<Space.Issued<GossipLearner.Evaluation>> all = metrics.readAllIssued(
        Template.of(GossipLearner.Evaluation.class).where("epoch", eq(epoch)), 100);

Semantic discovery and key wrap

// Semantic: find an asset by meaning rather than by name (examples/example-10)
var matches = semantic.remoteQuery("who holds customer order history?", 3,
        Duration.ofSeconds(2));
AssetCard card = (AssetCard) matches.get(0).advertisement();

// Key wrap: the holder serves the key under the profile's authorizer...
keys.serve(contentKey, authorizer, groupId);

// ...and a joining member asks the holder for it, sealed to its own X25519 key.
Optional<GroupKey> key = keys.request(holderPeerId, Duration.ofSeconds(2));

The floor of the stack. Most applications configure it through the starter and never touch it; this is the API when you wire by hand or embed without Spring.

• Identity. An Ed25519 keypair; the PeerId is the hash of the public key, so identity survives every address and transport change, and every frame, card, entry, and state transition the peer emits is signed with it.
• Groups. A group is self-certifying too: its GroupId is the hash of a founder-signed founding document, so every member derives the same id from the same founding string, and a newcomer who knows only the id can ask a seed for the document and verify the answer against the id before joining. That is the founding and join pair of chapter 2, and joinGroup has an overload for each.
• Membership. SWIM-style probing with leased membership: a silent member drops from the view on its own. Groups admit by policy: OPEN, INVITE (founder-signed credential presented at join), or POLICY (your validator SPI). Two gossip channels carry state, rumor for speed and anti-entropy for completeness, the latter paced by the group's own gossip period.
• Topology. Any member may volunteer as RENDEZVOUS (a bigger discovery cache newcomers ask first) or RELAY (forwards signed frames verbatim for NAT-restricted peers). Correctness never depends on either. On a LAN, the opt-in multicast beacon replaces seeds entirely.
• Transports. An in-JVM loopback for tests, TCP, TLS 1.3, and QUIC (RFC 9000) ship; a peer advertises (transport, addr, priority) endpoints and dialers try them in ascending priority, skipping schemes no configured transport serves. Peer identity stays with the signed envelopes on every transport.
• Channel authentication. The envelope signature authenticates one hop, so when the transport has already authenticated the channel it is repeated work at roughly a thousand times the cost of serializing the frame. TLS and QUIC present a channel certificate the peer identity endorses, and a node that announces itself willing accepts unsigned frames from the peer that channel attests — the attested mode of chapter 2. Signed and attested nodes mix freely; forcing signed mode is the only downgrade an attacker can cause, and it costs nothing but speed.
• Enterprise CA mode. Point the TLS binding at a trust store and peers attest only when their chain validates to your anchors, with revocation checked against cached CRLs or fetched live. Under require-attestation every inbound frame must arrive on a channel attested for its sender, which is what makes the CA's revocation an authoritative fleet-wide eject rather than advice.
• Revocation and rotation. A signed RevocationAdvertisement gossips like any other advertisement, with anti-entropy so late joiners converge, and a revoked identity is refused at dispatch ahead of every other check, evicted from membership, and its connection closed. Because a self-certifying identity cannot rotate its key in place, rotation is a revocation that names a successor; the successor joins and is authorized like any new peer. GroupRuntime.revoke(...) and rotate(...) issue, and the founder-rooted RevocationValidator is the seam an enterprise deployment replaces.
• One clock. startTicking(period) is the whole scheduler. Membership probing, rumour and anti-entropy gossip, replicated-space convergence, and capability protocols all advance on that one tick, because each layer registers with it rather than bringing a timer: a space through gossip().reconcile(...), a capability runtime through GroupRuntime.onTick(...), which is also where you hang periodic work of your own. Work registered there runs on the tick thread, so it must be quick; work that throws is logged and cannot stop the tick or its siblings.
• Containment. Per-issuer rate limits and bounded strike counters, fed only by witnessed violations on fresh authenticated frames, quarantine a misbehaving peer. Replayed frames and unadmitted peers deliberately never strike, which is what keeps quarantine unweaponizable.

An AgentId is <peerId>/<localName>, and by default the name is the peer's word: the peer key signs every record and a reader trusts that the peer labelled its agents honestly. When per-agent non-repudiation matters — an audit trail that must hold this agent, not its host, to a finding — give the agent a key of its own. The peer certifies it once, for a validity window, and from then on the records that agent writes are signed by the agent key and travel with the certificate. Readers see the difference: every Space.Issued carries an attestation, PEER_ASSERTED for the default and AGENT_ATTESTED when the agent's own key signed.

• What the certificate is. AgentCertificate(agent, agentPublicKey, issued, ttl, peerSignature): the peer's Ed25519 signature over the other four fields in canonical CBOR. Only the peer an AgentId names can issue one, and it is valid until issued + ttl on the receiver's clock. PeerIdentity.subordinate(name) mints a fresh keypair and certifies it for an hour; the overloads take your own KeyPair (for persistence or an HSM) and your own validity window.
• What a replica checks. The peer key still travels beside the record and must hash to the issuing peer, as it always has. With a certificate present, the replica verifies the certificate under that peer key, requires it to name exactly the record's issuer and to be unexpired, and then verifies the record under the certificate's agent key. A record that arrives with a certificate but a peer-key signature is refused, and so is one under a lapsed certificate — example-13's second flow test shows a stale agent's findings landing locally and nowhere else.
• Several agents, one peer. space.as(identity) is a view of the same replica seen as another agent of the same peer: its writes are signed and attributed as that agent, its takes name that agent as holder, and admission is judged for that agent, so two views of one replica can be admitted differently. One replica, one gossip registration, one clock per node stay the rule. Under the annotations you never call it: with agentspaces.identity.agent-keys=subordinate (or new AgentSpaces(identity, clock, identity::subordinate)) every bound agent gets a certified key and every @SpaceRef arrives as its view.
• What it does not do. A certificate proves who signed, never what they may do: admission and authorization are still the space's and the profile's decision. Take claims and completions still carry the peer's proof (the holder is named by AgentId), and subordinate keys take no part in key wrap.
• Wire compatibility. The certificate rides in an appended field of the state delta that is omitted when absent, so a fleet that never opts in is byte-identical to before, and older peers ignore the field. Python and TypeScript peers verify certified records; the golden vectors pin the certificate, the agent-key record signature, and five hostile deltas all three implementations refuse identically.

A read-only peer that serves the whole room: a single-file web UI at /, a HAL+JSON API under /api/v1 walkable from the root by any hypermedia client, and an SSE activity stream at /api/v1/events, all derived from the replicated coordination state, with zero instrumentation in any agent. It binds to loopback by default, as the A2A gateway does. Two properties turn it on (chapter 2); two more add command-and-control: dispatch tasks, cancel what the console dispatched, and pause, resume, or drain workers, every command executed under the console peer's signed identity, attributed to the named operator, and recorded in a durable audit space.

Operators authenticate one of two ways. A static command.token gates the HTTP command routes and always wins when set; leave it blank with security.oidc.* configured and each request's bearer JWT is validated against your identity provider instead, required to carry aspace:console:operate, and audited under the token's own subject rather than a name the request declares. Directives travel through the fleet-control space and the audit trail lands in c2-audit; both names are properties, and both spaces belong in the group's spaces list.

Extend the read side two ways: a ConsoleViewCustomizer bean tells the default generic view what the application's entries mean (worker attribution above all), and every ConsolePanel bean becomes one more section on the page and one more document under /api/v1/panels. Extend the command side with ConsoleCommand beans, whose typed fields render as forms. Workers honor directives through a DirectiveGate — under the starter, gates.attach(space, worker) off the DirectiveGates bean — consulting gate.paused() and gate.draining() in the work loop. A gate obeys only the configured console peer, narrowed further by the directive-issuer grant, and rejects future-stamped directives.

Turn it on for any fleet somebody has to operate. It is a peer like any other, reading the same replicated state every agent reads, which is why it needs no instrumentation, no agent, no sidecar and no export: there is nothing to wire up because the coordination state is the telemetry.

See the fleet room for the operator's tour, and run examples/example-09-fleet-console to drive a live fleet: pause a worker mid-run and watch its queue hold.

A2A. The gateway (agentspaces-a2a) serves every discovered AgentCard on the standard A2A discovery surface and speaks the task protocol as JSON-RPC over HTTP, with SSE streaming and push notifications: message/send becomes a leased task entry, tasks/get reads state from space semantics, message/stream and tasks/resubscribe stream over Server-Sent Events, and a lapsed lease honestly reports the task as submitted again. One gateway peer opens the door for the whole fleet, so individual agents never expose an inbound endpoint. It binds to loopback by default; discovery GETs stay open, the task surface takes a constant-time static bearer token or an identity-provider JWT carrying aspace:a2a:client, and push-notification webhooks validate against a private-address denial with an explicit allowlist override. Task results carry the authenticated issuer alongside whatever the worker declares about itself.

The connector SDK. agentspaces-connect-core is how a data source becomes a peer. An AssetProvider describes what it holds and answers queries for it; ConnectorRuntime publishes leased AssetCards and serves aspace:cap/data-query through the space, with DataQueryClient giving pull-once semantics keyed on a recomputed canonical query hash. MaterializingAssetProvider goes the other way, pushing source changes into a space as leased entries, and DataSpaces wires the block exchange so bulk results travel content-addressed. The SPI and the protocol are Apache 2; the module is marked EXPERIMENTAL.

Python and TypeScript. The wire protocol is CBOR plus Ed25519 (wire version 2, enforced) with nothing Java-specific, and the project ships wire-compatible Python and TypeScript peers proven byte-identical against shared golden vectors that cover every wire structure, refusing the same hostile inputs as the Java implementation. Both join by seed or by GroupId with the founding document verified, write signed entries, take under the claim lattice, and read through anti-entropy. Both also speak the agent-identity model of chapter 6: they verify agent certificates, apply the two-key rule to records and take-claim proofs, can sign as a subordinate agent themselves (Identity.subordinate), carry agentPublicKey on the cards they build, and tally QUORUM ballots at either granularity (agentspaces.vote, vote.ts); their Peer takes an injectable clock so time-bound material is testable against a fixed instant, as Java's TestClock is. run-trilingual-demo.sh races workers in all three languages on one space.

Clojure. agentspaces-clj gives idiomatic bindings outside the Maven reactor, consuming the published artifacts by coordinates: maps in and out over record entry types, a keyword :where DSL, and fleet/start from a config map that mirrors the Spring starter's properties key for key. For the exact formats and algorithms per layer, continue to TECH-SPEC.md.