The idea
Audit Fleet is the multi-disciplinary audit scenario from the AgentSpaces use-case analysis, built as a standalone Maven project on the published 0.5.0 libraries. A release candidate, billing-service 7.4.0, carries four planted problems across three fields. A scanner for each field raises the findings of its own discipline, a panelist of each discipline then votes on every finding, and that vote is the only thing that decides whether a finding stands.
Two choices carry the design. The first is that the decision is a record. A finding becomes a Proposal entry in a shared votes space, each panelist writes one signed
Ballot entry, and the tally is a count that any member can run again over the same entries. The second is that the panelists do not vote alike.
Each weighs a finding's confidence by how far it trusts the discipline that raised it, so a privacy concern can carry on the strength of the security seat while the licensing seat dismisses it.
A third choice names the electorate: every peer carries a VOTE grant for the three panelist peers, so a ballot from any other peer is signed, replicated and counted for nothing.
| finding | raised by | severity | confidence | what the scanner reports |
|---|---|---|---|---|
SEC-1 | security | critical | 95 | hardcoded database credential in application.yml |
LIC-1 | licensing | high | 85 | GPL-3.0 dependency bundled in a proprietary artifact |
PRIV-1 | privacy | medium | 70 | customer email logged at DEBUG in the payment path |
SEC-2 | security | low | 55 | stack traces returned verbatim in 500 responses |
The panel confirms SEC-1, LIC-1 and PRIV-1 and dismisses SEC-2, so the report carries 3 confirmed findings and a HIGH risk verdict off the confirmed critical. chapter 8 shows each ballot and the arithmetic behind it.
Finding record is the contract a real
static-analysis, license or privacy scanner would fill. Nothing in the fleet calls a model or needs a key, which is why the tests run offline in about 5 seconds.The cast
Seven agents run on four peers. Each discipline peer hosts a scanner and a panelist, and the fourth peer hosts the lead, which holds no panelist and casts no ballot. Every agent is a plain object with one annotated method, bound through the AgentSpaces facade the way the Spring starter binds beans; the binder reads the annotation, subscribes to the cue, and publishes an agent card.
| agent | class and peer | annotation | reads | writes |
|---|---|---|---|---|
scanner x3 | Scanner, on each discipline peer | @SpaceNotify(space = AUDIT, lease = "2h") | the AuditTarget that cues it | Finding in audit, then a Proposal in votes for each finding of its own discipline |
panelist x3 | Panelist, on each discipline peer | @Ballot(space = VOTES, lease = "2h") | the Proposal that cues it, then the Finding with a ten-second wait | one Ballot, written by the binder; none when the finding is missing |
lead | Lead, on audit-lead | @OnDecision(space = VOTES, lease = "2h") | the Decision, then the target and the finding with ten-second waits | AdjudicatedFinding for each decision, and one AuditReport after the last |
public static AutoCloseable runScanner(Peer peer) { return peer.group().bind(new Scanner(peer)); } public static AutoCloseable runPanelist(Peer peer) { return peer.group().bind(new Panelist(peer)); } public static AutoCloseable runLead(Peer peer) { return peer.group().bind(new Lead(peer)); }
agents.add(runScanner(security)); agents.add(runScanner(licensing)); agents.add(runScanner(privacy)); agents.add(runPanelist(security)); agents.add(runPanelist(licensing)); agents.add(runPanelist(privacy)); agents.add(runLead(lead));
The three classes have no framework base class. A scanner holds its Peer so that it can write through that peer's spaces and its vote capability; a panelist holds it to read findings;
the lead holds it to write adjudications. The seven agents are the only code that runs a vote. The quorum, the tally and the signatures are the library's.
scanner, panelist and lead on each peer. The entries they write go through the peer's
audit and votes spaces, which were built with a certified agent key named for the peer, such as audit-security.
The scanner and the panelist on one peer therefore sign under the same key, and a ballot names audit-security, never panelist. chapter 9 comes back to what that does and does not prove.How the fleet forms and how the agents find each other
The group is called audit-fleet and its id is the hash of the text audit-fleet-v1, so every peer derives it locally and no document needs to travel.
The first peer starts with no seed, listens on 7681, and every other peer dials it. The demo uses ports 7681 to 7684; the test asks the operating system for free ports so two runs never collide.
Everything is code: there is no starter, no configuration file and no keystore, and every start generates fresh peer keys.
The three panelist keys come first, from Panel.generate(), because the VOTE grant that names them has to exist before the first peer starts; each peer then takes the key of its seat, and the lead takes a fresh one.
| setting | value | where |
|---|---|---|
| group name and founding | audit-fleet, founded from the text audit-fleet-v1 | group() |
| membership policy, default strategy | OPEN, LEASE_RACE; gossip fan-out 3, period 1 s | group(), the library defaults |
| seed | 127.0.0.1:7681 in the demo (the first peer); a free port in the test | main, startPeer |
| transport | plain TCP on 127.0.0.1, TcpTransport; frames signed (the default channel auth), no TLS | startPeer |
| membership | member TTL 30 s, ping timeout 2 s, 2 indirect probes, one probe per second | GroupMembership.Config |
| tick | 250 ms (node.startTicking) | startPeer |
| card refresh | every 5 minutes, from the peer tick, so cards and advertisements outlive their 15 minute lease | CardRefresh |
| security | a VOTE grant naming the three panelist peers, on every peer; no TLS and no group content key; the signatures on entries and ballots are the rest of the protection | MembershipAuthorizer |
| identity | a fresh peer key per start (the panelist keys come from Panel.generate()), and an agent key named for the peer, certified for 24 h and renewed | renewingSubordinate |
/** The audit group. */ public static GroupAdvertisement group() { GroupId groupId = GroupId.fromFounding( "audit-fleet-v1".getBytes(StandardCharsets.UTF_8)); return new GroupAdvertisement("aspace://" + groupId.value(), PeerIdentity.generate().peerId(), groupId, Instant.EPOCH, Duration.ofDays(365), "audit-fleet", GroupAdvertisement.MembershipPolicy.OPEN, ConflictStrategyType.LEASE_RACE, GroupAdvertisement.GossipParameters.defaults()); }
/** * Assembles one peer: a content-addressed {@code audit} space for the * artifact and the finding records, and a {@code votes} space carrying the * {@link VoteCapability}'s proposals and ballots. Every peer's vote capability * counts the ballots of the panel's three peers and no others. * * @param panel the panel's seats; a peer whose discipline has no seat is not a voter * @param name the agent name * @param discipline the agent's discipline (or {@code "LEAD"} for the lead) * @param port the TCP port * @param seedPort an existing member's port, or 0 for the first * @return the running peer * @throws Exception if the port cannot be bound */ public static Peer startPeer(Panel panel, String name, String discipline, int port, int seedPort) throws Exception { return startPeer(panel, name, discipline, port, seedPort, REFRESH_EVERY); } static Peer startPeer(Panel panel, String name, String discipline, int port, int seedPort, Duration refreshEvery) throws Exception { PeerIdentity identity = panel.identityFor(discipline); PeerNode node = PeerNode.builder(identity).build(); node.listen(new TcpTransport(), HOST + ":" + port); List<PeerAdvertisement.Endpoint> seeds = seedPort == 0 ? List.of() : List.of(new PeerAdvertisement.Endpoint("tcp", HOST + ":" + seedPort, 0)); GroupRuntime runtime = node.joinGroup(group(), new GroupMembership.Config(Duration.ofSeconds(30), Duration.ofSeconds(2), 2), seeds); // An audit trail is only as good as its attribution, so each peer writes // its spaces as an agent of its own, named for the peer, with a key its // peer certifies (SPEC §4.2, QA4 A4-7): findings, adjudications, and // ballots read as AGENT_ATTESTED at every replica, not merely asserted by // the host peer. The scanner and panelist on one peer share that key. AgentIdentity agent = identity.renewingSubordinate(name, Duration.ofHours(24), InstantSource.system()); ReplicatedSpace audit = ReplicatedSpace.builder(runtime, "audit", identity, name) .writer(agent) .settleWindow(Duration.ofMillis(150)) .blocks(new BlockExchange(runtime, CborCodec.defaultCodec())) .build(); ReplicatedSpace votes = ReplicatedSpace.builder(runtime, "votes", identity, name) .writer(agent) .settleWindow(Duration.ofMillis(150)) .build(); // The electorate: a VOTE grant naming the three panelist peers. A ballot // counts only when its issuer's peer is granted here and is an admitted // member, and this peer's own capability refuses to cast one that would not. Authorizer electorate = new MembershipAuthorizer(runtime.membership(), identity.peerId(), Map.of(Authorizer.Operation.VOTE, panel.voters())); VoteCapability vote = new VoteCapability(votes, identity.agent(name), identity.peerId(), InstantSource.system(), VoteCapability.ANY_AUTHENTICATED_ISSUER, electorate); // Register the capability so the fleet can discover it (QA4 A4-3): an // unregistered capability is never advertised, so SPEC §8's find-then-use // pattern cannot work against it. Registering also puts it on the peer's // clock, which is the one clock this peer runs. DiscoveryService discovery = new DiscoveryService(runtime, new AdCache(CborCodec.defaultCodec(), InstantSource.system()), CborCodec.defaultCodec(), identity.peerId()); CapabilityRuntime capabilities = new CapabilityRuntime(runtime, discovery, identity); capabilities.register(vote); // The agents are annotated POJOs bound through the facade: their cues are // @SpaceNotify subscriptions the binder deduplicates and runs off the // fabric's delivery thread; they act through the peer's spaces and vote. AgentSpaces spaces = new AgentSpaces(identity, InstantSource.system()); AgentSpaces.GroupContext group = spaces.register("audit-fleet", runtime.id(), runtime, discovery); group.capabilities(capabilities); // so refreshCards() renews the vote advertisement too group.space(AUDIT, audit); group.space(VOTES, votes); group.vote(VOTES, vote); // what @Ballot and @OnDecision on "votes" cast and watch with // Cards and advertisements are leased for 15 minutes and lapse unless // something re-publishes them; the peer's own tick does, every few minutes. runtime.onTick(new CardRefresh(spaces, InstantSource.system(), refreshEvery)); node.startTicking(Duration.ofMillis(250)); return new Peer(name, discipline, node, runtime, audit, votes, vote, discovery, capabilities, spaces, group); }
A peer that has joined finds the others' work through advertisements. Every bound agent publishes an agent card, and every peer publishes a capability advertisement for the vote it offers.
A card names the agent, what each bound method consumes and produces, and the space it watches. In the recorded run the lead's cache held 7 cards, one for each bound agent. The card id is aspace://<group>/agent/<peer>/<name> and the lifetime is 15 minutes.
Nothing in the flow reads them: the agents are cued by the spaces, and the vote's electorate does not consult cards. They are what a console, a planner or another fleet would read to learn that this one exists.
| agent card | action | kind | consumes | produces | space |
|---|---|---|---|---|---|
scanneron z2ouj8... | scan | notify | AuditTarget#v1 | nothing | audit |
paneliston z2ouj8... | judge | ballot | Proposal#v1 | Ballot#v1 | votes |
leadon z28JcZ... | adjudicate | on-decision | Decision#v1 | nothing | votes |
void and writes the finding and the proposal through the peer's spaces. A reader of the catalogue therefore sees the scanner as a watcher of AuditTarget and learns of the findings from the spaces. No card carries an agent key (keyOnCard=false in the recording),
because the facade binds the classes under the peer's identity; the key that signs belongs to the peer's named agent.Keeping cards and advertisements alive
A card and a capability advertisement are leased for 15 minutes, and the host keeps them alive: the documentation of refreshCards() asks hosts to call it on a cadence well inside the lease.
It re-publishes every bound agent's card and the advertisements of every capability runtime attached to the group. startPeer attaches its runtime with group.capabilities(capabilities) so that one call covers the vote advertisement too,
and registers a CardRefresh on the group's tick. The tick runs every 250 ms; CardRefresh compares wall time with the next due instant and calls refreshCards() once every 5 minutes, which leaves at least 10 minutes on every lease.
The flow test cuts the period to 300 ms and watches a second member's cache: the publisher's card and vote advertisement both arrive with later issue times, with nobody asking.
/** Re-publishes the bound agents' cards and the capability advertisements once per period, from the peer tick. */ private static final class CardRefresh implements Runnable { private final AgentSpaces spaces; private final InstantSource clock; private final Duration every; private Instant next; CardRefresh(AgentSpaces spaces, InstantSource clock, Duration every) { this.spaces = spaces; this.clock = clock; this.every = every; this.next = clock.instant().plus(every); } @Override public void run() { Instant now = clock.instant(); if (!now.isBefore(next)) { // the tick thread is the only caller spaces.refreshCards(); next = now.plus(every); } } }
group.capabilities(capabilities); // so refreshCards() renews the vote advertisement too group.space(AUDIT, audit); group.space(VOTES, votes); group.vote(VOTES, vote); // what @Ballot and @OnDecision on "votes" cast and watch with // Cards and advertisements are leased for 15 minutes and lapse unless // something re-publishes them; the peer's own tick does, every few minutes. runtime.onTick(new CardRefresh(spaces, InstantSource.system(), refreshEvery));
/** * Re-publishes every bound agent's card in every group and every * registered capability runtime's advertisements (leased, P2). Hosts drive * this on a cadence well inside the 15-minute TTL. */ public void refreshCards() { for (GroupContext context : groups.values()) { context.binder().refreshCards(); CapabilityRuntime capabilities = context.capabilityRuntime; if (capabilities != null) { capabilities.refreshTick(); } } }
Finding the vote capability
The vote capability is the other thing a peer advertises. capabilities.register(vote) publishes a signed CapabilityAdvertisement through the peer's discovery service, and any member lists the providers from its own cache.
In the recorded run the privacy peer listed 4 advertisements, one per peer, each with the id aspace://<group>/cap/vote/<peer>/votes, the binding space:votes and the parameters modes=QUORUM,MAJORITY_GOSSIP. The advertisement says where a provider votes (the space); it does not say who may.
The agents of this fleet never look it up: each holds its own peer's capability. The flow test does look it up, to show that a consumer could.
/** * QA4 A4-3: the fleet's vote capability is discoverable. A capability nobody * registers on a CapabilityRuntime is never advertised, so a consumer looking * for {@code aspace:cap/vote} through discovery finds nothing and the SPEC §8 * pattern — find the provider, then use it — cannot work against our own * flagship. Registering it is also what puts it on the peer's clock. */ @Test @Timeout(120) void theVoteCapabilityIsAdvertisedToTheFleet() throws Exception { Panel panel = Panel.generate(); int seedPort = freePort(); Peer lead = AuditFleet.startPeer(panel, "cap-lead", "SECURITY", seedPort, 0); Peer other = AuditFleet.startPeer(panel, "cap-other", "PRIVACY", freePort(), seedPort); try { long deadline = System.nanoTime() + java.time.Duration.ofSeconds(60).toNanos(); while (System.nanoTime() < deadline && other.capabilities().providersOf(VoteCapability.TYPE).isEmpty()) { Thread.sleep(250); } assertThat(other.capabilities().providersOf(VoteCapability.TYPE)) .as("the other peer discovers the lead's vote capability") .isNotEmpty(); assertThat(lead.capabilities().isDrivenByPeerTick()) .as("and it rides the peer clock").isTrue(); } finally { lead.close(); other.close(); } }
// Register the capability so the fleet can discover it (QA4 A4-3): an // unregistered capability is never advertised, so SPEC §8's find-then-use // pattern cannot work against it. Registering also puts it on the peer's // clock, which is the one clock this peer runs. DiscoveryService discovery = new DiscoveryService(runtime, new AdCache(CborCodec.defaultCodec(), InstantSource.system()), CborCodec.defaultCodec(), identity.peerId()); CapabilityRuntime capabilities = new CapabilityRuntime(runtime, discovery, identity); capabilities.register(vote);
The two spaces
Every peer holds a replica of two spaces, both built the same way: ReplicatedSpace.builder(...) with the peer's agent key as the writer and a 150 ms settle window. The audit space also gets a block exchange, which is what lets it carry the artifact.
Neither space declares a strategy, so both use the default lease race, and that default never runs: no agent in this fleet takes an entry. Findings, proposals, ballots and adjudications are written, read and watched, and each lives for its 2-hour lease.
| record | space | written by | read by | lease |
|---|---|---|---|---|
AuditTarget | audit | the security peer (the demo and the test do this) | the scanners, as a cue; the lead, with a timed read | 2 h |
Finding | audit | each scanner, for its own discipline | the panelists, with a timed read by finding id; the lead | 2 h |
Proposal | votes | the scanner, through vote().propose(...) | the panelists, as a cue; every tally | 2 h |
Ballot | votes | the binder, for each @Ballot | every tally | 2 h (the @Ballot lease) |
AdjudicatedFinding | audit | the lead, for each decision | the lead, to roll up the report; anyone | 2 h |
AuditReport | audit | the lead, once | the demo and the test, which poll for it | 2 h |
/** * The artifact under audit. {@code evidence} stands in for the release * bundle and is deliberately larger than the inline limit, so the space * stores the record as a block named by its CID, and that CID heads the audit * trail; {@code issues} * carries the planted problems each scanner will surface, keyed by finding * id with value {@code discipline|confidence|severity|summary}. * * @param targetId the artifact id * @param name a human label * @param issues the planted problems (findingId to encoded spec) * @param evidence the release bytes (content-addressed) */ public record AuditTarget(String targetId, String name, Map<String, String> issues, byte[] evidence) { }
public record Finding(String findingId, String targetId, String discipline, int confidence, String severity, String summary, String raisedBy) { }
public record AdjudicatedFinding(String findingId, String discipline, String severity, String verdict, int confirmVotes, int dismissVotes, String targetCid) { }
public record AuditReport(String targetId, String targetCid, int confirmed, int dismissed, String riskVerdict, List<String> confirmedFindings, long assembledAtMillis, String assembledBy) { }
The ballot is the record to read closely. It is a library type, VoteCapability.Ballot, with three fields, and it sits in a space of its own so that nothing else can disturb a recount.
A ballot carries no reasoning and no evidence reference; what makes it a vote is who signed it and the proposal it names.
The artifact travels by hash
The release bundle is stood in for by 96 KiB of evidence, a repeating fill derived from the target id and name, so every run builds the same bytes. That is more than the 64 KiB a record may carry inline,
so writing the AuditTarget takes the content-addressed path. The space stores the encoded record as a block, replicates a reference to it, and leaves the block exchange to move the bytes to the peers that want them.
The audit space is the one built with a block exchange; the votes space never carries anything that large.
/** * Builds a target whose evidence bytes exceed the inline limit (so it is * content-addressed) from a list of planted issue specs, each * {@code findingId|discipline|confidence|severity|summary}. * * @param targetId the artifact id * @param name a human label * @param specs the planted issue specs * @return the target */ public static AuditTarget target(String targetId, String name, String... specs) { Map<String, String> issues = new LinkedHashMap<>(); for (String spec : specs) { String[] parts = spec.split("\\|", 5); issues.put(parts[0], parts[1] + "|" + parts[2] + "|" + parts[3] + "|" + parts[4]); } byte[] evidence = new byte[EVIDENCE_BYTES]; byte[] seed = (targetId + name).getBytes(StandardCharsets.UTF_8); for (int i = 0; i < evidence.length; i++) { evidence[i] = seed[i % seed.length]; } return new AuditTarget(targetId, name, issues, evidence); }
ReplicatedSpace audit = ReplicatedSpace.builder(runtime, "audit", identity, name) .writer(agent) .settleWindow(Duration.ofMillis(150)) .blocks(new BlockExchange(runtime, CborCodec.defaultCodec())) .build();
// A content-addressed entry whose block has not landed: fetch it now // and fire the deferred WRITTEN when it does, so a notify subscriber // learns of large entries without anyone having to read (a poll was // the only way before; the flagships all polled for this reason). EntryRecord record = dto.record(); fetchInBackground(record, () -> decodeValue(record).ifPresent(v -> fire(SpaceEvent.Kind.WRITTEN, entryId, v, record.issuer(), record.issuer(), record)));
// The target's evidence is content-addressed; the timed read waits for // the block rather than reporting an unknown hash. AuditTarget target = peer.audit().read(Template.of(AuditTarget.class), readWait) .orElse(null); String targetCid = target == null ? null : targetCid(); /** The CID the target's audit entry carries for its block (its payload reference), or null while none is held. */ private String targetCid() { return peer.audit().readAllEntries(Template.of(AuditTarget.class), 1).stream() .findFirst() .flatMap(entry -> peer.audit().recordOf(entry.entryId())) .map(EntryRecord::payloadRef) .orElse(null); }
In the recorded run the evidence was 98,304 bytes and the encoded AuditTarget record was 98,682 bytes, 378 more for the target id, the name and the planted-issue map. The block the space stores holds the whole encoded record, so its identifier, zCpUNmrTVqo47xn5A9uSeMP8kVJEhFXk9fQ7V3b8Q3tSi, is the hash of those 98,682 bytes.
The target's entry carries that value as its payload reference. The lead reads it back with recordOf(entryId).payloadRef() and writes exactly that value, as targetCid, into every adjudication and the report, so the report and the entry name the same block.
A reader who wants to check the report fetches the block by the CID, which the block exchange verifies as the bytes arrive, and finds the evidence and the planted issues inside it. The hash of the evidence bytes alone (zGWYMsZhdrs61rH5EVJ7Zv2kXcKZvMEZkabyoz7SvvUdd in the recording) appears in none of the records.
A scanner learns of the target without polling. When a record arrives whose block has not landed, the space starts a background fetch from the writer and two random members, retries on a back-off while the entry lives,
and fires the deferred write event once the block is local. The scanner's @SpaceNotify cue then runs with the decoded target on every peer. Reads never block on the network: the lead's timed read polls its own replica for up to ten seconds and returns
the target as soon as the block lands, or null when it does not.
One audit, end to end
The flow test and the demo walk the same eight steps. Follow PRIV-1, the finding that only just survives: the privacy scanner raises it, the three panelists vote on it, and the lead records the verdict and, after the fourth finding, the report. Steps 3 to 5 run once per finding and in parallel across findings, so the panel is voting on all four at once.
- 1. The security peer writes the
AuditTargetwith a two-hour lease. The demo and the test do this in a line of code; nothing in the fleet owns intake. - 2. Every peer learns of the record and fetches the block (chapter 4). The scanner's cue fires on each peer once the evidence is local.
- 3.
scanwalks the target's planted issues, skips those of other disciplines, and writes aFindingfor each of its own. - 4. Right after each finding it opens the vote: the proposal id is the finding id, so the vote space holds one proposal per finding id and the fleet audits one target at a time; the options are
CONFIRMEDandDISMISSED, and the quorum isPANEL, the size of the panel. - 5. Each panelist's
@Ballotcue fires on the proposal.judgereads the finding by id, weighs its confidence by trust, and returns an option; the binder casts the ballot. - 6. The lead's replica tallies the ballots as they arrive. When three peers' ballots count,
adjudicateruns once for that proposal. - 7. It puts the decision in its pending map, reads the target and the finding, and writes an
AdjudicatedFindingwith the winner, both counts and the target CID. A read that times out leaves the finding pending. - 8. After the last finding it reads every adjudication, computes the risk verdict, and writes the
AuditReport, once.
/** * A discipline's scanner: its cue is an {@link AuditTarget} (delivered once the * content-addressed evidence is local); for each planted issue in its own * discipline it raises a {@link Finding} and opens the panel's vote on it. */ @AgentSpec(name = "scanner", description = "Raises findings in its discipline and opens their votes", goals = {"scan"}) public static final class Scanner { private final Peer peer; public Scanner(Peer peer) { this.peer = peer; } @SpaceNotify(space = AUDIT, lease = "2h") public void scan(AuditTarget target) { for (Map.Entry<String, String> issue : target.issues().entrySet()) { String findingId = issue.getKey(); String[] p = issue.getValue().split("\\|", 4); String discipline = p[0]; if (!discipline.equals(peer.discipline())) { continue; } int confidence = Integer.parseInt(p[1]); // raisedBy is informational; the finding's issuer is authenticated // and attested, which is what readAllIssued gives an auditor. peer.audit().write(new Finding(findingId, target.targetId(), discipline, confidence, p[2], p[3], peer.audit().writer().orElseThrow().encoded()), Lease.of(Duration.ofHours(2))); peer.vote().propose(findingId, "Confirm " + discipline + " finding: " + p[3], VERDICTS, PANEL, Lease.of(Duration.ofHours(2))); } } }
/** * A panelist: its cue is the vote's own {@link VoteCapability.Proposal}, so the * ballot can never be refused as unknown; it weighs the finding's confidence by * how far it trusts the raising discipline and returns its option. The binder * casts the ballot as this agent, once per proposal. */ @AgentSpec(name = "panelist", description = "Casts one signed ballot per finding", goals = {"adjudicate"}) public static final class Panelist { private final Peer peer; public Panelist(Peer peer) { this.peer = peer; } @Ballot(space = VOTES, lease = "2h") public String judge(VoteCapability.Proposal proposal) { Finding finding = peer.audit().read(Template.of(Finding.class) .where("findingId", eq(proposal.proposalId())), Duration.ofSeconds(10)).orElse(null); if (finding == null) { return null; // no finding on the record for this proposal: abstain } double weighted = finding.confidence() * trust(peer.discipline(), finding.discipline()); return weighted >= CONFIRM_THRESHOLD ? "CONFIRMED" : "DISMISSED"; } }
/** * The lead: its cue is a closed vote. It writes the {@link AdjudicatedFinding} * for each decision, and once every finding on the target is adjudicated it * writes the {@link AuditReport}. A decision fires once per replica, so the * lead keeps each one in {@code pending} until it has recorded it: a read that * times out leaves the finding pending, and the next call retries it. */ @AgentSpec(name = "lead", description = "Records each closed vote and assembles the report", goals = {"report"}) public static final class Lead { /** How many times one decision tries to settle before it leaves the finding pending. */ private static final int ATTEMPTS = 3; private final Peer peer; private final Duration readWait; private final Map<String, VoteCapability.Decision> pending = new ConcurrentHashMap<>(); private final Set<String> adjudicated = ConcurrentHashMap.newKeySet(); private final AtomicBoolean reported = new AtomicBoolean(); public Lead(Peer peer) { this(peer, Duration.ofSeconds(10)); } Lead(Peer peer, Duration readWait) { this.peer = peer; this.readWait = readWait; } @OnDecision(space = VOTES, lease = "2h") public void adjudicate(VoteCapability.Decision decision) { String findingId = decision.proposalId(); pending.putIfAbsent(findingId, decision); for (int attempt = 0; attempt < ATTEMPTS && pending.containsKey(findingId); attempt++) { settle(); } } /** The findings whose decisions have closed but are not yet on the record. */ public Set<String> pending() { return Set.copyOf(pending.keySet()); } /** * Records every pending decision whose target and finding it can read, and * writes the report once every finding on the target is adjudicated. A * decision it cannot record stays pending; call it again to retry. */ public synchronized void settle() { if (reported.get() || pending.isEmpty()) { return; } // The target's evidence is content-addressed; the timed read waits for // the block rather than reporting an unknown hash. AuditTarget target = peer.audit().read(Template.of(AuditTarget.class), readWait) .orElse(null); String targetCid = target == null ? null : targetCid(); if (targetCid == null) { return; } for (VoteCapability.Decision decision : List.copyOf(pending.values())) { String findingId = decision.proposalId(); Finding finding = peer.audit().read(Template.of(Finding.class) .where("findingId", eq(findingId)), readWait).orElse(null); if (finding == null) { continue; } Map<String, Integer> tally = decision.tally(); peer.audit().write(new AdjudicatedFinding(findingId, finding.discipline(), finding.severity(), decision.winner(), tally.getOrDefault("CONFIRMED", 0), tally.getOrDefault("DISMISSED", 0), targetCid), Lease.of(Duration.ofHours(2))); adjudicated.add(findingId); pending.remove(findingId); } if (adjudicated.size() >= target.issues().size() && reported.compareAndSet(false, true)) { List<AdjudicatedFinding> all = peer.audit() .readAll(Template.of(AdjudicatedFinding.class), 200); List<AdjudicatedFinding> confirmed = all.stream() .filter(a -> a.verdict().equals("CONFIRMED")).toList(); List<String> confirmedIds = confirmed.stream() .map(AdjudicatedFinding::findingId).sorted().toList(); peer.audit().write(new AuditReport(target.targetId(), targetCid, confirmed.size(), all.size() - confirmed.size(), riskVerdict(confirmed), confirmedIds, millis(), peer.audit().writer().orElseThrow().encoded()), Lease.of(Duration.ofHours(2))); } } /** The CID the target's audit entry carries for its block (its payload reference), or null while none is held. */ private String targetCid() { return peer.audit().readAllEntries(Template.of(AuditTarget.class), 1).stream() .findFirst() .flatMap(entry -> peer.audit().recordOf(entry.entryId())) .map(EntryRecord::payloadRef) .orElse(null); } }
/** * The release risk verdict from the confirmed findings: a confirmed critical * (or two confirmed highs) is a HIGH-risk release; any confirmed high or * medium is MEDIUM; a confirmed low alone is LOW; nothing confirmed passes. * * @param confirmed the confirmed findings * @return the risk verdict */ public static String riskVerdict(List<AdjudicatedFinding> confirmed) { boolean critical = confirmed.stream().anyMatch(f -> f.severity().equals("CRITICAL")); long highs = confirmed.stream().filter(f -> f.severity().equals("HIGH")).count(); boolean mediumOrHigh = confirmed.stream() .anyMatch(f -> f.severity().equals("HIGH") || f.severity().equals("MEDIUM")); if (critical || highs >= 2) { return "HIGH"; } if (mediumOrHigh) { return "MEDIUM"; } return confirmed.isEmpty() ? "PASS" : "LOW"; }
AuditTarget target = target("release-7.4.0", "billing-service 7.4.0", "SEC-1|SECURITY|95|CRITICAL|hardcoded database credential in application.yml", "LIC-1|LICENSING|85|HIGH|GPL-3.0 dependency bundled in a proprietary artifact", "PRIV-1|PRIVACY|70|MEDIUM|customer email logged at DEBUG in the payment path", "SEC-2|SECURITY|55|LOW|stack traces returned verbatim in 500 responses"); security.audit().write(target, Lease.of(Duration.ofHours(2)));
Two details of these classes carry the correctness. The finding and its proposal are separate entries in separate spaces, so a panelist can see the proposal first;
judge therefore reads the finding with a ten-second wait, and returns null, which abstains, when none arrives.
The lead faces the same gap from the other side, and a decision fires only once per replica, so it keeps what it cannot yet record. adjudicate puts the decision in a pending map first, then calls settle() up to 3 times while its own finding is still pending.
settle() is synchronized: it records every pending decision whose target and finding it can read (each read waits up to 10 seconds), removes it from the map, and writes the report exactly once, when every issue on the target has an adjudication.
A late block or a late finding therefore delays the verdict, and the lead still records it. After the attempts run out the finding stays in the map, pending() lists it, and the next decision's call, or a host calling settle(), tries it again.
The flow of the demo never reaches this path, so a test drives it directly: it hands the lead a decision with no target and no finding on the record, sees the finding pending, then writes both and calls settle(), which records the adjudication and the report.
vote().propose(...) on the peer's vote capability. The scanner has the finding in hand when it writes it, so it can open the vote with no cue entry to wait for. chapter 6 shows the annotation form of the same act, @Propose, which a lead uses
when the options and quorum are fixed and only the question varies.The vote protocol
aspace:cap/vote runs over an ordinary space. A proposal is a signed entry with an id, a question, the options, a quorum and a lease. A ballot is a signed entry naming the proposal and one option.
The decision is not stored: it is the result of counting the ballots, and any member computes it from its own replica. This fleet uses the QUORUM mode, the canonical and auditable one; the other mode, a push-sum average, is a cheap
temperature check.
public record Proposal(String proposalId, String question, List<String> options, int quorum) { } public record Ballot(String proposalId, String option, String voter) { } public record Decision(String proposalId, String winner, Map<String, Integer> tally, Authorizer.Granularity granularity) { /** A decision counted per peer, the rule every pre-phase-2 caller assumed. */ public Decision(String proposalId, String winner, Map<String, Integer> tally) { this(proposalId, winner, tally, Authorizer.Granularity.PEER); } }
public void propose(String proposalId, String question, List<String> options, int quorum, Lease lease) { if (options.size() < 2) { throw new IllegalArgumentException("a proposal needs at least two options"); } if (quorum <= 0) { throw new IllegalArgumentException("quorum must be positive: " + quorum); } voteSpace.write(new Proposal(proposalId, question, List.copyOf(options), quorum), lease); }
public void castBallot(String proposalId, String option, Lease lease) { Proposal proposal = proposal(proposalId).orElseThrow(() -> new IllegalArgumentException("unknown proposal: " + proposalId)); if (!proposal.options().contains(option)) { throw new IllegalArgumentException( "option '" + option + "' is not on the ballot for " + proposalId); } if (!authorizer.permits(self, Authorizer.Operation.VOTE, voteSpace.name())) { // Fail fast rather than write a ballot every tally discards (G2-3); // asked per agent, which is per peer unless the authorizer holds // agent-level grants (QA4 A4-7 phase 2). throw new IllegalStateException("agent " + self.encoded() + " is not permitted VOTE in space '" + voteSpace.name() + "'; its ballot would count for nothing"); } voteSpace.write(new Ballot(proposalId, option, self.encoded()), lease); }
public Optional<Decision> decision(String proposalId) { Optional<Proposal> proposal = proposal(proposalId); if (proposal.isEmpty()) { return Optional.empty(); } Map<String, Integer> tally = tally(proposalId); int voters = tally.values().stream().mapToInt(Integer::intValue).sum(); if (voters < proposal.get().quorum()) { return Optional.empty(); } String winner = tally.entrySet().stream() .max(Map.Entry.<String, Integer>comparingByValue() .thenComparing(Map.Entry.comparingByKey( java.util.Comparator.reverseOrder()))) .map(Map.Entry::getKey) .orElseThrow(); return Optional.of(new Decision(proposalId, winner, new HashMap<>(tally), granularity())); }
propose refuses fewer than two options or a non-positive quorum, and writes the proposal. castBallot refuses a proposal this replica has not seen and an option that is not on it, asks the authorizer, and writes the ballot with the caster's own encoded agent id as the voter.
decision is the whole decision rule: sum the counted ballots, return nothing while the sum is below the quorum, and otherwise return the option with the most votes, a tie going to the lowest option name so that every replica agrees.
The three annotations
The fleet uses two of the three. @Ballot is on the panelist: the method takes the proposal and returns the option, or null to abstain, and the binder casts the ballot through the group's vote capability, once per proposal id. Because the cue is the proposal entry itself,
the ballot can never be refused as an unknown proposal. @OnDecision is on the lead: the method takes the Decision and runs once per proposal, the first time this replica's tally meets the quorum, however late the ballots reach it.
@Ballot(space = VOTES, lease = "2h") public String judge(VoteCapability.Proposal proposal) { Finding finding = peer.audit().read(Template.of(Finding.class) .where("findingId", eq(proposal.proposalId())), Duration.ofSeconds(10)).orElse(null); if (finding == null) { return null; // no finding on the record for this proposal: abstain } double weighted = finding.confidence() * trust(peer.discipline(), finding.discipline()); return weighted >= CONFIRM_THRESHOLD ? "CONFIRMED" : "DISMISSED"; }
/** The {@code @Ballot} binding: one ballot per proposal, cast as the agent, off the delivery thread. */ private Subscription castBallots(Object agent, Method method, Ballot ballot, Bound handle) { String spaceName = resolveVoteSpaceName(ballot.space(), method); VoteCapability voter = voteFor(handle.identity, spaceName); Space voteSpace = spaces.get(spaceName); Lease ballotLease = Lease.of(Durations.parse(ballot.lease())); String label = handle.agentId.localName() + "." + method.getName(); Set<String> voted = java.util.Collections.newSetFromMap(new ConcurrentHashMap<>()); Subscription subscription = voteSpace.notify(Template.of(VoteCapability.Proposal.class), event -> { if (event.kind() != SpaceEvent.Kind.WRITTEN) { return; } VoteCapability.Proposal proposal = event.entry(); if (!proposal.proposalId().startsWith(ballot.prefix()) || !voted.add(proposal.proposalId())) { return; } Thread.ofVirtual().name("space-ballot-" + label).start(() -> { try { Object option = invoke(agent, method, proposal); if (option != null) { voter.castBallot(proposal.proposalId(), (String) option, ballotLease); } } catch (RuntimeException e) { voted.remove(proposal.proposalId()); // a refused ballot may be retried by redelivery LOG.log(System.Logger.Level.WARNING, label + ": ballot failed", e); } }); }, Lease.of(Duration.ofHours(1))); renewWhileBound(subscription, Duration.ofHours(1), handle, "space-ballot-renew-" + label); return subscription; }
@OnDecision(space = VOTES, lease = "2h") public void adjudicate(VoteCapability.Decision decision) { String findingId = decision.proposalId(); pending.putIfAbsent(findingId, decision); for (int attempt = 0; attempt < ATTEMPTS && pending.containsKey(findingId); attempt++) { settle(); } }
/** The {@code @OnDecision} binding: once per proposal when the quorum closes here. */ private Subscription watchDecisions(Object agent, Method method, OnDecision onDecision, Bound handle) { String spaceName = resolveVoteSpaceName(onDecision.space(), method); VoteCapability vote = votes.get(spaceName); Space resultSpace = onDecision.resultSpace().isEmpty() ? spaceFor(handle.identity, spaceName, method) : spaceFor(handle.identity, onDecision.resultSpace(), method); Lease lease = Lease.of(Durations.parse(onDecision.lease())); Lease resultLease = Lease.of(Durations.parse(onDecision.resultLease())); String label = handle.agentId.localName() + "." + method.getName(); Subscription subscription = vote.onDecision(id -> id.startsWith(onDecision.prefix()), decision -> Thread.ofVirtual().name("space-decision-" + label).start(() -> { try { Object result = invoke(agent, method, decision); dispatch(result, null, resultSpace, resultLease, null, handle, method, label); } catch (RuntimeException e) { LOG.log(System.Logger.Level.WARNING, label + ": decision reaction failed", e); } }), lease); renewWhileBound(subscription, lease.duration(), handle, "space-decision-renew-" + label); return subscription; }
The third annotation, @Propose, opens a vote for each cue entry: the method returns the question, and the annotation carries the vote space, the proposal id rule, the options, the quorum and the lease.
This fleet does not use it. Each scanner calls propose directly for the findings it writes, which works because every finding has exactly one author.
Party Bus's safety lead below is the annotation form of the same job; there, three channels assess one wave, so the binder's once-per-id rule collapses three cues into one proposal.
@Propose(space = Watchers.SIGNALS, vote = ADVISORIES, prefix = PROPOSAL_PREFIX, key = {"tripId", "location", "wave"}, options = {"GO", "CAUTION", "AVOID"}, quorum = 3, lease = "12h", subscriptionLease = "12h") public String open(DangerAssessment assessment) { waves.putIfAbsent(Safety.proposalId(assessment.tripId(), assessment.location(), assessment.wave()), assessment); return "Travel advisory for " + assessment.location() + " (" + assessment.wave() + ")"; }
The annotation's attributes and the once-per-replica rule are in the developer guide's chapter on @Propose, @Ballot and @OnDecision.
Who may vote, and how the panel forms the quorum
The quorum is a number the proposer writes into the proposal. scan passes PANEL, which is DISCIPLINES.size(), so three: the vote closes when three ballots count. Which ballots count is decided by the tally, and the tally is configured where the capability is built.
startPeer builds it with six arguments: the votes space, the peer's own agent, the peer id, the clock, an electorate predicate left at ANY_AUTHENTICATED_ISSUER, and an authorizer. The authorizer is a MembershipAuthorizer over the group's membership
with one explicit grant, VOTE for the three panelist peers.
/** * The panel's seats: one peer identity per discipline, generated before any * peer starts so that every peer can be configured with the same {@code VOTE} * grant. A deployed fleet loads these keys from files and lists the three peer * ids under {@code agentspaces.security.grants.vote}. * * @param seats the identity of each discipline's panelist peer */ public record Panel(Map<String, PeerIdentity> seats) { /** Generates one identity for each of the {@link #DISCIPLINES}. */ public static Panel generate() { Map<String, PeerIdentity> seats = new LinkedHashMap<>(); DISCIPLINES.forEach(discipline -> seats.put(discipline, PeerIdentity.generate())); return new Panel(seats); } /** The peers whose ballots count: exactly the panelist peers. */ public Set<PeerId> voters() { return seats.values().stream().map(PeerIdentity::peerId) .collect(Collectors.toUnmodifiableSet()); } /** A discipline's identity; a peer with no seat (the lead, or an outsider) gets a fresh one. */ PeerIdentity identityFor(String discipline) { PeerIdentity seat = seats.get(discipline); return seat != null ? seat : PeerIdentity.generate(); } }
// The electorate: a VOTE grant naming the three panelist peers. A ballot // counts only when its issuer's peer is granted here and is an admitted // member, and this peer's own capability refuses to cast one that would not. Authorizer electorate = new MembershipAuthorizer(runtime.membership(), identity.peerId(), Map.of(Authorizer.Operation.VOTE, panel.voters())); VoteCapability vote = new VoteCapability(votes, identity.agent(name), identity.peerId(), InstantSource.system(), VoteCapability.ANY_AUTHENTICATED_ISSUER, electorate);
public boolean permits(PeerId peer, Operation operation, String scope) { Objects.requireNonNull(peer, "peer"); Objects.requireNonNull(operation, "operation"); if (!peer.equals(self) && membership.member(peer).isEmpty()) { return false; // not admitted (or no longer): no privileges at all } Set<PeerId> granted = grants.get(operation); if (granted == null) { // KEY_ROTATE needs an explicit grant (the founder is permitted by the // key distributor itself); every other operation defaults to members. return operation != Operation.KEY_ROTATE; } if (granted.contains(peer)) { return true; } // A peer hosting a granted agent is permitted at peer level: it must be, // or castBallot's own fail-fast would stop the granted agent from voting. Set<AgentId> agents = agentGrants.get(operation); return agents != null && agents.stream().anyMatch(agent -> agent.peer().equals(peer)); }
default Granularity granularity(Operation operation, String scope) { return Granularity.PEER; }
A ballot counts when its issuer's peer is one of the three granted peers and is an admitted member of the replica doing the count; MembershipAuthorizer answers false for a peer it has no membership record of, whatever its grants say.
The grants are peer ids, so the granularity stays PEER and the counted identity is the issuer's peer: a member is one vote however many agent names it signs under.
That is why the quorum of three works here. Each panelist sits on a peer of its own, so three peers are three voters, and a fourth agent on one of those peers would add nothing.
The same grant makes this peer's own capability refuse to cast for a peer the grant does not name, as castBallot does, rather than write a ballot every tally would discard.
Counting per agent is a separate configuration with three parts: an authorizer that holds agent-level VOTE grants for the votes space (entries of the form peer/localName), a facade built with an identity factory so each bound agent signs with a key of its own, and ballots that are AGENT_ATTESTED,
because a name the peer merely asserts is exactly what per-agent counting exists to distrust. The audit fleet's ballots are attested, but its grants name peers and the scanner and the panelist on a peer share one key, so it counts per peer.
The developer guide's @Ballot section describes the per-agent setting.
private Map<String, Integer> tallyWith(String proposalId) { Map<String, Integer> tally = new TreeMap<>(); Optional<Proposal> proposal = proposal(proposalId); proposal.ifPresent(p -> p.options().forEach(o -> tally.put(o, 0))); Authorizer.Granularity granularity = granularity(); Set<String> counted = new HashSet<>(); for (Space.Issued<Ballot> issued : voteSpace.readAllIssued( Template.of(Ballot.class).where("proposalId", eq(proposalId)), 10_000)) { Ballot ballot = issued.entry(); if (!ballot.voter().equals(issued.issuer().encoded())) { continue; // declared voter is not the authenticated writer: forged } if (proposal.isPresent() && !proposal.get().options().contains(ballot.option())) { continue; // option is not on the ballot: spoiled, counts for nothing } if (!electorate.test(issued.issuer())) { continue; // outside the electorate (no fresh AgentCard): does not count } if (granularity == Authorizer.Granularity.AGENT && issued.attestation() != Space.Attestation.AGENT_ATTESTED) { continue; // per-agent counting trusts only the agent's own key } if (!authorizer.permits(issued.issuer(), Authorizer.Operation.VOTE, voteSpace.name())) { continue; // the profile's authorizer refuses this voter (G2-3) } if (revocations.revoked(issued.issuer(), null)) { // v0.1.13 (M-13): a revoked agent's ballot stops counting at the // next recount, so a decision can reopen (SPEC §8). continue; } String key = granularity == Authorizer.Granularity.AGENT ? issued.issuer().encoded() : issued.issuer().peer().value(); if (counted.add(key)) { tally.merge(ballot.option(), 1, Integer::sum); } } return tally; }
A fourth peer's ballot counts for nothing
The recorded probe tested the edge. After the audit it took the lead's peer, which holds no panelist and is the fourth peer of the group, and tried to vote on SEC-2. The peer's own capability, which startPeer built with the grant, refused (IllegalStateException: agent ... is not permitted VOTE in space 'votes'; its ballot would count for nothing).
The probe then built a capability over the same space with no authorizer, as a peer that wants its way would, and cast a real ballot: signed by the lead peer's agent, with a voter field equal to its signer, in the vote space of every replica (1 ballot from the lead peer for SEC-2 in the security peer's replica).
The tally on the lead's replica and on the security peer's replica stayed {CONFIRMED=1, DISMISSED=2}, and decision() answered DISMISSED, the verdict the lead had recorded. Without the grant the ballot would count: SEC-2 becomes a 2 to 2 tie, a tie goes to the lowest option name, and decision() would answer CONFIRMED against an adjudication that says DISMISSED.
The flow test asserts the grant holds, with an outsider peer that casts through an open capability.
The probe also wrote a ballot straight into the space with a voter field that named the privacy agent, from the lead's peer; the tally stayed at {CONFIRMED=1, DISMISSED=2}, because the voter must equal the signer.
The group's policy is OPEN, so any peer can join and write; the grant narrows who counts and leaves who may write alone.
The grant is each replica's own configuration, and the tally reads it at the moment it counts. A replica built without it counts the fourth peer's ballot, so two members that configure the list differently recount differently.
Under a real deployment the list comes from one place: the starter reads it from agentspaces.security.grants.vote, and an identity-provider profile reads the aspace:vote scope from each peer's token.
Trust, and the four verdicts
Each panelist is the same class bound on a different peer, and its discipline is the only thing that differs. Its ballot is a function of two numbers: the finding's confidence, and how far this seat trusts the discipline that raised the finding. A seat trusts its own field fully. For any other pair the weight comes from a small map in the code, with 0.8 for every pair the map leaves out. The map is asymmetric on purpose, which is what makes the cross-disciplinary part of the vote do something.
/** * How far a panelist of one discipline trusts a finding raised in another: * fully in its own field, and at a discipline-specific weight elsewhere. The * weights are deliberately asymmetric — this is where cross-disciplinary * judgment lives. * * @param panel the reviewing panelist's discipline * @param finding the finding's discipline * @return the trust weight in [0, 1] */ public static double trust(String panel, String finding) { if (panel.equals(finding)) { return 1.0; } return CROSS_TRUST.getOrDefault(panel + ">" + finding, 0.8); } private static final Map<String, Double> CROSS_TRUST = Map.of( "SECURITY>LICENSING", 0.7, "LICENSING>PRIVACY", 0.5, "PRIVACY>LICENSING", 0.6);
public String judge(VoteCapability.Proposal proposal) { Finding finding = peer.audit().read(Template.of(Finding.class) .where("findingId", eq(proposal.proposalId())), Duration.ofSeconds(10)).orElse(null); if (finding == null) { return null; // no finding on the record for this proposal: abstain } double weighted = finding.confidence() * trust(peer.discipline(), finding.discipline()); return weighted >= CONFIRM_THRESHOLD ? "CONFIRMED" : "DISMISSED"; }
Every ballot of the run follows from those two lines. The table lists each seat's arithmetic and ballot for each finding; the tallies in the last two columns are the ones the flow test asserts for SEC-1, PRIV-1 and SEC-2,
and the demo prints for LIC-1 as well.
| finding | security seat | licensing seat | privacy seat | tally | verdict |
|---|---|---|---|---|---|
SEC-1critical | 95 x 1.0 = 95CONFIRMED | 95 x 0.8 = 76CONFIRMED | 95 x 0.8 = 76CONFIRMED | confirm 3 / dismiss 0 | CONFIRMED |
LIC-1high | 85 x 0.7 = 59.5CONFIRMED | 85 x 1.0 = 85CONFIRMED | 85 x 0.6 = 51CONFIRMED | confirm 3 / dismiss 0 | CONFIRMED |
PRIV-1medium | 70 x 0.8 = 56CONFIRMED | 70 x 0.5 = 35DISMISSED | 70 x 1.0 = 70CONFIRMED | confirm 2 / dismiss 1 | CONFIRMED |
SEC-2low | 55 x 1.0 = 55CONFIRMED | 55 x 0.8 = 44DISMISSED | 55 x 0.8 = 44DISMISSED | confirm 1 / dismiss 2 | DISMISSED |
SEC-1 is the clear case: the critical finding clears the threshold at every seat, even at the default 0.8 (95 becomes 76). LIC-1 carries across fields, but the privacy seat's weight for a licensing finding is 0.6, so 85 becomes 51 and clears the line by one point; at a confidence of 83 or less the privacy seat would have dismissed it and a 3 to 0 would have been a 2 to 1.
PRIV-1 is the finding that shows what the quorum is for. Its author, the privacy seat, confirms at 70. The security seat weighs it at the default 0.8 and confirms at 56. The licensing seat trusts privacy findings at 0.5, so 70 becomes 35 and it dismisses.
The finding survives two to one, and the licensing dissent stays on the record. SEC-2 has only its own author behind it: 55 clears the line at the security seat and falls to 44 at the other two.
judge with a scanner that reports a calibrated confidence and the trust map with whatever the organisation
believes about its specialists; the quorum, the signatures and the recount stay as they are.What the signed record proves, and what it does not
A ballot is a small thing: an option, a proposal id and a voter name. What makes a vote of it is everything around the entry. The figure takes one signed ballot part by part and says what each part settles and what it leaves to the deployment; the rest of the chapter checks each claim against a recorded run.
Who signed
The probe reads the ballots back with readAllIssued, which returns each entry with its authenticated issuer and attestation, the same call the flow test uses. The twelve ballots of the recorded run follow. Each was signed by an agent of one of the three discipline peers
under that agent's own certified key, and in every one the voter field equals the issuer. Peer ids are shortened to six characters here.
| proposal | option | signed by | attestation |
|---|---|---|---|
SEC-1 | CONFIRMED | z4i5G4.../audit-licensing | AGENT_ATTESTED |
SEC-1 | CONFIRMED | z2ouj8.../audit-privacy | AGENT_ATTESTED |
SEC-1 | CONFIRMED | z3yc1u.../audit-security | AGENT_ATTESTED |
LIC-1 | CONFIRMED | z4i5G4.../audit-licensing | AGENT_ATTESTED |
LIC-1 | CONFIRMED | z2ouj8.../audit-privacy | AGENT_ATTESTED |
LIC-1 | CONFIRMED | z3yc1u.../audit-security | AGENT_ATTESTED |
PRIV-1 | DISMISSED | z4i5G4.../audit-licensing | AGENT_ATTESTED |
PRIV-1 | CONFIRMED | z2ouj8.../audit-privacy | AGENT_ATTESTED |
PRIV-1 | CONFIRMED | z3yc1u.../audit-security | AGENT_ATTESTED |
SEC-2 | DISMISSED | z4i5G4.../audit-licensing | AGENT_ATTESTED |
SEC-2 | DISMISSED | z2ouj8.../audit-privacy | AGENT_ATTESTED |
SEC-2 | CONFIRMED | z3yc1u.../audit-security | AGENT_ATTESTED |
The same recount on the privacy peer's replica returned the lead's decision for all four proposals: the same winner and the same tally, counted per peer. A member who doubts a line of the report can do this without asking the lead anything.
What the tally refuses
Two experiments from the same run show the edges. The first wrote a ballot into the space from the lead's peer with a voter field that named the privacy agent. It sits in the space like any entry, and the tally ignored it, so the SEC-2 count stayed at {CONFIRMED=1, DISMISSED=2}.
The second had the lead's peer, a fourth peer, cast a real ballot for SEC-2 through a capability with no authorizer. It sits in the space on every replica, signed and attributable, and the tally ignored it too, because the VOTE grant does not name the lead's peer (chapter 7).
The adjudication written earlier and a recount agree: SEC-2 is dismissed, one to two.
-- CIDs cidOf(evidence) = zGWYMsZhdrs61rH5EVJ7Zv2kXcKZvMEZkabyoz7SvvUdd cidOf(cbor(target)) = zCpUNmrTVqo47xn5A9uSeMP8kVJEhFXk9fQ7V3b8Q3tSi entry payloadRef = zCpUNmrTVqo47xn5A9uSeMP8kVJEhFXk9fQ7V3b8Q3tSi report.targetCid = zCpUNmrTVqo47xn5A9uSeMP8kVJEhFXk9fQ7V3b8Q3tSi evidence bytes=98304 cbor bytes=98682 -- experiment 1: forged voter field written straight to the space from the lead peer SEC-2 tally at lead after forged ballot: {CONFIRMED=1, DISMISSED=2} -- experiment 2: the lead peer is a fourth peer; its own capability, then an open one the lead's own capability refuses: IllegalStateException: agent z28JcZoFrkMZNcTRmXvWLsA4HM4RDxuwr2LS25BohXXwG/audit-lead is not permitted VOTE in space 'votes'; its ballot would count for nothing ballots signed by the lead peer in the security peer's replica for SEC-2, voter equal to signer: 1 SEC-2 tally at lead after the lead's ballot: {CONFIRMED=1, DISMISSED=2} decision=Optional[Decision[proposalId=SEC-2, winner=DISMISSED, tally={DISMISSED=2, CONFIRMED=1}, granularity=PEER]] SEC-2 tally at security: {CONFIRMED=1, DISMISSED=2} decision=Optional[Decision[proposalId=SEC-2, winner=DISMISSED, tally={DISMISSED=2, CONFIRMED=1}, granularity=PEER]] adjudication on record for SEC-2: [AdjudicatedFinding[findingId=SEC-2, discipline=SECURITY, severity=LOW, verdict=DISMISSED, confirmVotes=1, dismissVotes=2, targetCid=zCpUNmrTVqo47xn5A9uSeMP8kVJEhFXk9fQ7V3b8Q3tSi]]
What it leaves open
- Why a panelist voted. A ballot carries an option and a signature. The reasoning, which here is confidence times trust, is in the class, and a panelist that signs under a different rule signs the same entry.
- Which bytes the panelists saw. The target CID is in the lead's adjudications and report. A ballot does not carry it (chapter 4).
- Who the panel is. The three peers the
VOTEgrant names, as each replica is configured. The grant is local configuration, so a member that leaves it out counts a fourth peer's ballot (chapter 7). - That the report is honest. The lead's
AdjudicatedFindingcopies the tally from its own replica at the moment the quorum closed, and signs it. The recount above is the check, and it needs the ballots to still exist. - That it lasts. Every entry carries a 2-hour lease. After that the proposals, ballots, findings, adjudications and the report lapse from every replica, and a recount has nothing to count. An audit that must outlive the run has to copy its record out, or write with longer leases.
When something dies
The fleet has no supervisor and no failover. Nothing leases the work, because a vote has no task to claim, and the quorum is a fixed count. The consequence is visible in five recorded cases, all run against the app's own classes with the flow test's setup: a panelist left unbound, the same panelist bound late, the lead bound late, a panelist's peer closed after the audit, and the membership dropping that peer.
Wed Nov 4 03:03:07 EST 2026 == after 12 s with two of three panelists proposals=4 ballots=8 adjudications=0 findings=4 report=false SEC-1 tally={CONFIRMED=2, DISMISSED=0} decision=none LIC-1 tally={CONFIRMED=2, DISMISSED=0} decision=none PRIV-1 tally={CONFIRMED=1, DISMISSED=1} decision=none SEC-2 tally={CONFIRMED=1, DISMISSED=1} decision=none == 8 s after the third panelist binds late proposals=4 ballots=8 adjudications=0 findings=4 report=false SEC-1 tally={CONFIRMED=2, DISMISSED=0} decision=none LIC-1 tally={CONFIRMED=2, DISMISSED=0} decision=none PRIV-1 tally={CONFIRMED=1, DISMISSED=1} decision=none SEC-2 tally={CONFIRMED=1, DISMISSED=1} decision=none
Wed Nov 4 03:03:29 EST 2026 == A: lead not bound, 8 s after the target proposals=4 ballots=12 adjudications=0 report=false SEC-1 tally={CONFIRMED=3, DISMISSED=0} decision=CONFIRMED LIC-1 tally={CONFIRMED=3, DISMISSED=0} decision=CONFIRMED PRIV-1 tally={CONFIRMED=2, DISMISSED=1} decision=CONFIRMED SEC-2 tally={CONFIRMED=1, DISMISSED=2} decision=DISMISSED == A: 8 s after the lead binds late proposals=4 ballots=12 adjudications=0 report=false SEC-1 tally={CONFIRMED=3, DISMISSED=0} decision=CONFIRMED LIC-1 tally={CONFIRMED=3, DISMISSED=0} decision=CONFIRMED PRIV-1 tally={CONFIRMED=2, DISMISSED=1} decision=CONFIRMED SEC-2 tally={CONFIRMED=1, DISMISSED=2} decision=DISMISSED == B: complete audit, all peers up proposals=4 ballots=12 adjudications=4 report=true SEC-1 tally={CONFIRMED=3, DISMISSED=0} decision=CONFIRMED LIC-1 tally={CONFIRMED=3, DISMISSED=0} decision=CONFIRMED PRIV-1 tally={CONFIRMED=2, DISMISSED=1} decision=CONFIRMED SEC-2 tally={CONFIRMED=1, DISMISSED=2} decision=DISMISSED == B: 4 s after the privacy peer is closed proposals=4 ballots=12 adjudications=4 report=true SEC-1 tally={CONFIRMED=3, DISMISSED=0} decision=CONFIRMED LIC-1 tally={CONFIRMED=3, DISMISSED=0} decision=CONFIRMED PRIV-1 tally={CONFIRMED=2, DISMISSED=1} decision=CONFIRMED SEC-2 tally={CONFIRMED=1, DISMISSED=2} decision=DISMISSED == B: 44 s after the privacy peer is closed proposals=4 ballots=12 adjudications=4 report=true SEC-1 tally={CONFIRMED=2, DISMISSED=0} decision=none LIC-1 tally={CONFIRMED=2, DISMISSED=0} decision=none PRIV-1 tally={CONFIRMED=1, DISMISSED=1} decision=none SEC-2 tally={CONFIRMED=1, DISMISSED=1} decision=none
Wed Nov 4 03:06:51 EST 2026 before close: report=true member=true SEC-1 decision=CONFIRMED lead's membership dropped the privacy peer after ~19 s lead's SEC-1 decision reopened after ~19 s, tally={CONFIRMED=2, DISMISSED=0} after: report=true adjudications=4
- A missing panelist stalls every vote. With two of three seats filled, the lead's replica held eight ballots after twelve seconds and no decision. The partial tallies are honest: SEC-1 two to nothing, PRIV-1 one to one. Nothing times out; the proposals stay open until their lease lapses.
- A panelist that binds late never votes on what it missed. Eight seconds after the third panelist bound, the ballots were still eight. The
@Ballotbinding subscribes to proposals as they are written, so proposals that already exist are not delivered to it. - A lead that binds late never adjudicates what it missed. With the lead absent all twelve ballots were in and every proposal was decided when the replica recomputed it, yet eight seconds after the lead bound there were no adjudications and no report.
@OnDecisionreacts to ballot and proposal writes as they arrive, and the decisions had closed before it existed. - A voter that dies after voting changes nothing at first. Four seconds after the privacy peer closed, every tally, decision, adjudication and the report were as before: its ballots are entries in the other replicas and live for their lease.
- Then the membership drops the voter, and its ballots stop counting. The
VOTEgrant counts a ballot only while its peer is an admitted member in the counting replica's view. In the third recording the lead's membership dropped the closed privacy peer after about 19 seconds, and in the same one-second poll the lead's SEC-1 tally fell from 3 to 2 anddecision()answered nothing. The membership configuration instartPeersets a member TTL of 30 seconds. The adjudications and the report the lead had already written stayed, because they are entries with their own leases, so the record keeps the verdict while a recount no longer reproduces it. That is the electorate rule working as designed: a decision is a function of the ballots and the live electorate at the moment of counting. - Read from the code only: a scanner that never starts writes none of its findings, so no proposal opens for them and the lead, which counts adjudications against the target's issue count, never reaches its report. A block that never arrives makes the lead's ten-second reads return
null; the decision stays in the pending map and the lead retries it (three attempts per call, then on the next decision or a host'ssettle()), so the finding waits and the report waits with it. A panelist whose finding read times out abstains, and the binding's once-per-proposal set means the abstention is final.
What a deployment would add is a sweep at bind time: a panelist that lists the open proposals and votes on those it has not, and a lead that recomputes decision(id) for every open proposal and writes the adjudications it lacks. Both are a few lines over the capability's public methods, and neither needs a new mechanism.
A timeout that raises an alarm for a proposal open longer than a window would turn the silent stall of the first case into a signal.
Running and testing it
The project needs JDK 21 or newer and Maven. It depends on 8 AgentSpaces artifacts at 0.5.0, all published to Maven Central (api, common, identity, peering, discovery, space, agent, capabilities), plus JUnit and AssertJ for the test.
The pom pins the version in one property, so moving to a later release is a one-line change.
<properties> <maven.compiler.release>21</maven.compiler.release> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <agentspaces.version>0.5.0</agentspaces.version> <junit.version>5.13.4</junit.version> <assertj.version>3.27.7</assertj.version> </properties>
<artifactId>agentspaces-capabilities</artifactId> <version>${agentspaces.version}</version> </dependency>
mvn test # five tests over real TCP mvn -q exec:java # the live demo: four findings, three specialists, one verdict ./run-demo.sh # the same demo, compiling first
AuditFleetTest holds five tests. theVoteCapabilityIsAdvertisedToTheFleet asserts that the vote capability is discoverable and that it runs on the peer clock. thePanelConfirmsBackedFindingsDismissesUnbackedOnesAndScoresTheRisk asserts the audit itself.
aFourthPeersBallotIsIgnoredAndSec2StaysDismissed adds a fourth peer and has it cast through a capability with no authorizer. aDecisionTheLeadCannotYetRecordStaysPendingUntilItsRecordsArrive drives the lead directly with a decision whose records are missing. thePeerTickRepublishesCardsAndAdvertisements shortens the refresh period and watches a second member's cache.
Every test starts real peers over loopback TCP on free ports, carries a timeout, and needs neither a key nor a network beyond loopback.
void theVoteCapabilityIsAdvertisedToTheFleet() throws Exception { Panel panel = Panel.generate(); int seedPort = freePort(); Peer lead = AuditFleet.startPeer(panel, "cap-lead", "SECURITY", seedPort, 0); Peer other = AuditFleet.startPeer(panel, "cap-other", "PRIVACY", freePort(), seedPort); try { long deadline = System.nanoTime() + java.time.Duration.ofSeconds(60).toNanos(); while (System.nanoTime() < deadline && other.capabilities().providersOf(VoteCapability.TYPE).isEmpty()) { Thread.sleep(250); } assertThat(other.capabilities().providersOf(VoteCapability.TYPE)) .as("the other peer discovers the lead's vote capability") .isNotEmpty(); assertThat(lead.capabilities().isDrivenByPeerTick()) .as("and it rides the peer clock").isTrue(); } finally { lead.close(); other.close(); } }
// The risk verdict is HIGH: a confirmed CRITICAL finding. assertThat(report.riskVerdict()).isEqualTo("HIGH"); assertThat(report.confirmed()).isEqualTo(3); assertThat(report.dismissed()).isEqualTo(1); assertThat(report.confirmedFindings()) .containsExactlyInAnyOrder("SEC-1", "LIC-1", "PRIV-1"); // The provenance is the block CID the target's own entry carries: the // hash of the encoded record, evidence bytes and planted issues included. String expectedCid = security.audit() .recordOf(security.audit().readAllEntries(Template.of(AuditTarget.class), 1) .get(0).entryId()) .orElseThrow().payloadRef(); assertThat(expectedCid).isEqualTo(BlockExchange.cidOf(CborCodec.defaultCodec().toBytes(target))); assertThat(report.targetCid()).isEqualTo(expectedCid); Map<String, AdjudicatedFinding> byId = lead.audit() .readAll(Template.of(AdjudicatedFinding.class), 200).stream() .collect(Collectors.toMap(AdjudicatedFinding::findingId, Function.identity())); // The unanimous, clear findings carried the whole panel. assertThat(byId.get("SEC-1").verdict()).isEqualTo("CONFIRMED"); assertThat(byId.get("SEC-1").confirmVotes()).isEqualTo(3); // A privacy concern the licensing specialist discounted still carried, // on the strength of the security specialist backing it: 2 to 1. assertThat(byId.get("PRIV-1").verdict()).isEqualTo("CONFIRMED"); assertThat(byId.get("PRIV-1").confirmVotes()).isEqualTo(2); assertThat(byId.get("PRIV-1").dismissVotes()).isEqualTo(1); // A low-confidence finding only its own author believed was dismissed. assertThat(byId.get("SEC-2").verdict()).isEqualTo("DISMISSED"); assertThat(byId.get("SEC-2").confirmVotes()).isEqualTo(1); assertThat(byId.get("SEC-2").dismissVotes()).isEqualTo(2); // Each adjudication carried the target's block CID: the audit trail. assertThat(byId.values()).allSatisfy(a -> assertThat(a.targetCid()).isEqualTo(expectedCid));
// And the trail is attributable: every adjudication and the report are // signed by their agent's own certified key (QA4 A4-7), so the fleet can // hold the panelist, not merely its host peer, to the verdict. assertThat(lead.audit().readAllIssued(Template.of(AdjudicatedFinding.class), 200)) .hasSize(4) .allSatisfy(issued -> { assertThat(issued.issuer()).isEqualTo(lead.node().identity().agent("audit-lead")); assertThat(issued.attestation()) .isEqualTo(ai.badmonkey.agentspaces.api.space.Space.Attestation.AGENT_ATTESTED); }); // The ballots behind them came from three panelists on three peers, each // signing with its own certified key. assertThat(lead.votes().readAllIssued(Template.of(VoteCapability.Ballot.class), 200)) .isNotEmpty() .allSatisfy(issued -> assertThat(issued.attestation()) .isEqualTo(ai.badmonkey.agentspaces.api.space.Space.Attestation.AGENT_ATTESTED)) .extracting(issued -> issued.issuer().peer()) .containsOnly(security.node().peerId(), licensing.node().peerId(), privacy.node().peerId()); assertThat(lead.audit().readAllIssued(Template.of(AuditReport.class), 10)) .singleElement().satisfies(issued -> { assertThat(issued.issuer()).isEqualTo(lead.node().identity().agent("audit-lead")); assertThat(issued.attestation()) .isEqualTo(ai.badmonkey.agentspaces.api.space.Space.Attestation.AGENT_ATTESTED); }); } }
/** * The electorate is the three panelist peers. A fourth peer's ballot is authentic * and replicates to every member, and the tally still ignores it: without the * grant it would make SEC-2 a 2 to 2 tie, and a tie goes to CONFIRMED. */ @Test @Timeout(120) void aFourthPeersBallotIsIgnoredAndSec2StaysDismissed() throws Exception { try (Fleet fleet = new Fleet()) { Peer outsider = fleet.join("audit-outsider", "OUTSIDER"); Thread.sleep(1500); fleet.security.audit().write(planted(), Lease.of(Duration.ofHours(2))); assertThat(awaitReport(fleet.lead, Duration.ofSeconds(90))).isNotNull(); assertThat(fleet.lead.vote().decision("SEC-2")).hasValueSatisfying(decision -> { assertThat(decision.winner()).isEqualTo("DISMISSED"); assertThat(decision.tally()).containsEntry("CONFIRMED", 1).containsEntry("DISMISSED", 2); }); // The outsider's own capability, built by startPeer, refuses to cast. assertThat(await(Duration.ofSeconds(30), () -> outsider.vote().proposal("SEC-2").isPresent())) .as("the outsider's replica holds the proposal").isTrue(); assertThatThrownBy(() -> outsider.vote().castBallot("SEC-2", "CONFIRMED", Lease.of(Duration.ofHours(2)))) .isInstanceOf(IllegalStateException.class).hasMessageContaining("not permitted VOTE"); // A capability with no authorizer, built by a peer that wants its way, // signs a real ballot as the outsider's agent; it reaches every replica. VoteCapability open = new VoteCapability(outsider.votes(), outsider.votes().writer().orElseThrow(), outsider.node().peerId(), InstantSource.system()); open.castBallot("SEC-2", "CONFIRMED", Lease.of(Duration.ofHours(2))); for (Peer replica : List.of(fleet.security, fleet.licensing, fleet.privacy, fleet.lead)) { assertThat(await(Duration.ofSeconds(30), () -> replica.votes() .readAllIssued(Template.of(VoteCapability.Ballot.class), 200).stream() .anyMatch(issued -> issued.issuer().peer().equals(outsider.node().peerId())))) .as(replica.name() + " holds the outsider's ballot").isTrue(); } // Every replica still counts three peers' ballots for SEC-2, and the decision // is the one the lead recorded. for (Peer replica : List.of(fleet.security, fleet.licensing, fleet.privacy, fleet.lead)) { assertThat(replica.vote().tally("SEC-2")).as(replica.name()) .containsEntry("CONFIRMED", 1).containsEntry("DISMISSED", 2); assertThat(replica.vote().decision("SEC-2").orElseThrow().winner()) .as(replica.name()).isEqualTo("DISMISSED"); } assertThat(fleet.lead.audit().readAll(Template.of(AdjudicatedFinding.class), 200).stream() .filter(a -> a.findingId().equals("SEC-2"))) .singleElement().satisfies(a -> assertThat(a.verdict()).isEqualTo("DISMISSED")); } }
/** * A decision fires once per replica, so a lead whose reads time out must keep the * finding rather than forget it: it stays pending, and the next call records it. */ @Test @Timeout(60) void aDecisionTheLeadCannotYetRecordStaysPendingUntilItsRecordsArrive() throws Exception { Peer peer = AuditFleet.startPeer(Panel.generate(), "audit-lead", "LEAD", freePort(), 0); try { AuditFleet.Lead lead = new AuditFleet.Lead(peer, Duration.ofMillis(200)); lead.adjudicate(new VoteCapability.Decision("SEC-1", "CONFIRMED", Map.of("CONFIRMED", 3, "DISMISSED", 0))); // Neither the target nor the finding is here: every read timed out. assertThat(lead.pending()).containsExactly("SEC-1"); assertThat(peer.audit().readAll(Template.of(AdjudicatedFinding.class), 10)).isEmpty(); AuditTarget target = AuditFleet.target("release-1", "one finding", "SEC-1|SECURITY|95|CRITICAL|hardcoded database credential"); peer.audit().write(target, Lease.of(Duration.ofHours(2))); peer.audit().write(new Finding("SEC-1", "release-1", "SECURITY", 95, "CRITICAL", "hardcoded database credential", "audit-security"), Lease.of(Duration.ofHours(2))); lead.settle(); assertThat(lead.pending()).isEmpty(); assertThat(peer.audit().readAll(Template.of(AdjudicatedFinding.class), 10)) .singleElement().satisfies(a -> { assertThat(a.findingId()).isEqualTo("SEC-1"); assertThat(a.verdict()).isEqualTo("CONFIRMED"); }); // One finding on the target, so the last adjudication also wrote the report. assertThat(peer.audit().read(Template.of(AuditReport.class))) .hasValueSatisfying(report -> assertThat(report.confirmedFindings()).containsExactly("SEC-1")); } finally { peer.close(); } }
/** * Cards and capability advertisements are leased for 15 minutes. The peer's tick * re-publishes them, so a fleet that runs for hours keeps them; with the refresh * period cut to 300 ms, a member sees both issue times move. */ @Test @Timeout(120) void thePeerTickRepublishesCardsAndAdvertisements() throws Exception { Panel panel = Panel.generate(); int seedPort = freePort(); Duration refresh = Duration.ofMillis(300); Peer publisher = AuditFleet.startPeer(panel, "audit-security", "SECURITY", seedPort, 0, refresh); Peer member = AuditFleet.startPeer(panel, "audit-privacy", "PRIVACY", freePort(), seedPort, refresh); try (AutoCloseable scanner = AuditFleet.runScanner(publisher)) { assertThat(await(Duration.ofSeconds(30), () -> issuedCard(member, publisher).isPresent() && issuedAdvertisement(member, publisher).isPresent())) .as("the member sees the publisher's card and vote advertisement").isTrue(); Instant firstCard = issuedCard(member, publisher).orElseThrow(); Instant firstAdvertisement = issuedAdvertisement(member, publisher).orElseThrow(); assertThat(await(Duration.ofSeconds(30), () -> issuedCard(member, publisher).orElseThrow().isAfter(firstCard) && issuedAdvertisement(member, publisher).orElseThrow().isAfter(firstAdvertisement))) .as("both were re-published without anyone asking").isTrue(); } finally { publisher.close(); member.close(); } }
- The risk verdict is HIGH, with three confirmed findings (
SEC-1,LIC-1,PRIV-1) and one dismissed. - The tallies are asserted for
SEC-1(3 to 0),PRIV-1(2 to 1) andSEC-2(1 to 2).LIC-1is asserted as confirmed through the report's list, and its 3 to 0 is not asserted on its own. - The target CID in the report and in all four adjudications equals the CID the target's entry carries, read back with
recordOf(entryId).payloadRef(), and equalsBlockExchange.cidOfof the encoded record, recomputed in the test. - The attribution is that all four adjudications and the report are issued by the
audit-leadagent and readAGENT_ATTESTED, and that every ballot is attested and comes from one of the three discipline peers. - The capability is listed by
providersOf(VoteCapability.TYPE)on another peer within a minute, andisDrivenByPeerTick()is true. - The electorate holds against a fourth peer: its own capability refuses to cast, a ballot from an open capability reaches all four replicas, and every replica still tallies SEC-2 at one to two and decides DISMISSED.
- The lead keeps a decision it cannot record: the finding is pending after the reads time out, and
settle()writes the adjudication and the report once the target and the finding exist. - The refresh moves a publisher's card and vote advertisement to later issue times in a second member's cache, with a 300 ms period standing in for the 5 minutes.
The tests do not cover the stall paths: no test leaves a panelist unbound, binds an agent late, closes a voter, or forges a ballot, and the number of ballots (twelve) is not asserted. chapter 10 describes what those cases do, from recorded runs of the app's own classes.
One recorded run
This is the demo as it ran on 2026-11-04, verbatim, with JDK 25 (the compiler targets release 21) on macOS. The target CID is fixed by the encoded record, so it repeats from run to run; the agent in the last line carries a peer id that changes on every start.
mvn -q exec:java took 3.5 s of wall time in each of three runs, and in the probe run of chapter 9 the report was on the lead's replica 237 ms after the target was written. The demo adds a fixed 1.5 s pause after binding the agents, before it writes the target, and a 0.5 s pause after closing the peers.
audit-fleet: a panel adjudicates a release, no central reviewer under audit: billing-service 7.4.0 (4 planted findings) == adjudicated findings (signed quorum votes) == LIC-1 LICENSING HIGH -> CONFIRMED (confirm 3 / dismiss 0) PRIV-1 PRIVACY MEDIUM -> CONFIRMED (confirm 2 / dismiss 1) SEC-1 SECURITY CRITICAL -> CONFIRMED (confirm 3 / dismiss 0) SEC-2 SECURITY LOW -> DISMISSED (confirm 1 / dismiss 2) == audit report == artifact : release-7.4.0 target (CID) : zCpUNmrTVqo47xn5A9uSeMP8kVJEhFXk9fQ7V3b8Q3tSi confirmed : 3 [LIC-1, PRIV-1, SEC-1] dismissed : 1 risk verdict : HIGH (assembled by z694NfbNxtXukLgu2j4xNjxHq669ZWH9B8YmLHBMbyQ3e/audit-lead) Every verdict is a majority of signed ballots against the artifact's content hash. LIC-1 carried on cross-discipline backing; PRIV-1 survived a licensing dissent; SEC-2 was dismissed when only its author stood behind it. No reviewer was in charge; the trust-weighted panel decided.
NoClassDefFoundError for RelayPaths$Graph on stderr, thrown from a TCP delivery thread after the last line above; the output was complete and the exit status was 0.
The stack runs through a gossip forward that found no direct link and fell back to a relay path, which loads that class for the first time during shutdown, after exec:java had dropped the demo's class loader with the peers' delivery threads still running.
Peer.close() now closes each peer's agents, capability and facade before its node, and main pauses 0.5 s after the last peer closes so that late deliveries finish while the loader is open.
The error did not reproduce on a quiet machine, so the fix rests on the stack: 8 runs of the demo and 12 of a harness that closes the class loader the moment main returns ran clean before the change, and 3 runs of mvn -q exec:java and 12 of the harness ran clean after it.Where to go next
The vote is the one coordination type this app teaches; the developer guide covers the rest of the stack it stands on.
- The developer guide's Decide and sense chapter for the annotations (@Ballot, @OnDecision, @Propose), and the vote capability for the two modes and the electorate rules.
- Keys and where they live for agent keys and certificates, and leases for why every record here expires.
- Cards in the developer guide and cards in the architecture guide for what a card says and who reads it.
- The workflow guide's decide chapter for votes as a workflow step, and data artifacts for content addressing.
- The Party Bus guide for a safety panel that opens its votes with
@Proposeand says when per-agent counting applies, and the Superfriends guide for three vendors voting on one trade.
Taking it further
- Real scanners. Replace the planted issue list with a SAST tool, a license scanner and a PII classifier behind the same
Findingrecord, and read their evidence through an asset provider so the content-addressed artifact is the real bundle. - A livelier electorate. The grant names the panel once, when the fleet is built (chapter 7). The vote capability also accepts an electorate predicate:
VoteCapability.freshAgentCards(discovery)counts a ballot only while its issuer has an unexpired agent card, so the electorate tracks who is alive. It needs panelists bound with agent keys of their own, so that a card names the ballot's issuer. - More seats on fewer peers. Counting per agent needs a facade built with an identity factory so each bound agent has a key of its own, an authorizer that names agents, and ballots that are
AGENT_ATTESTED. - A record that outlives two hours. Copy each adjudication and the report to storage before their leases lapse, or write them with a longer lease.