aspace://guide/audit-fleet

Audit Fleet

A release is audited by a panel of discipline specialists, and every finding they raise goes to a signed quorum vote of the whole panel. A finding survives only when a cross-disciplinary majority confirms it, and the decision is a set of signed ballots that any member can recount. This is the showcase for aspace:cap/vote in QUORUM mode, on four peers and seven agents.

AgentSpaces 0.5.04 peers, loopback TCP7 agents2 spacesaspace:cap/vote, QUORUMno keys, no model calls
The ideaThe vote protocolThe four verdictsRun it
aspace://guide/audit-fleet/idea

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-1securitycritical95hardcoded database credential in application.yml
LIC-1licensinghigh85GPL-3.0 dependency bundled in a proprietary artifact
PRIV-1privacymedium70customer email logged at DEBUG in the payment path
SEC-2securitylow55stack 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.

What is a stand-inThe scanners are stand-ins. Each reads a planted issue list out of the artifact record and raises the findings of its own discipline; the 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.
aspace://guide/audit-fleet/cast · chapter 1

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.

ONE GROUP audit-fleet: 4 PEERS, 7 AGENTS, 2 SPACES REPLICATED ON EVERY PEERaudit-securitysecurity, :7681scanner@SpaceNotify on AuditTargetpanelist@Ballot on every Proposalone votersigns as audit-securityaudit-licensinglicensing, :7682scanner@SpaceNotify on AuditTargetpanelist@Ballot on every Proposalone votersigns as audit-licensingaudit-privacyprivacy, :7683scanner@SpaceNotify on AuditTargetpanelist@Ballot on every Proposalone votersigns as audit-privacyaudit-leadlead, :7684lead@OnDecision on every voteholds no panelist, casts no ballotsigns as audit-leadaudit: AuditTarget, Finding, AdjudicatedFinding, AuditReportvotes: Proposal, Ballot (aspace:cap/vote, QUORUM)shaded boxes are the voters: the quorum of 3 is the three panelists, one on each discipline peer
The cast. Seven agents on four peers. Each discipline peer hosts a scanner and a panelist; the lead peer hosts the lead. Every peer holds a replica of both spaces and signs its writes as the agent named for the peer, so the three ballots come from three different peers.
agent class and peer annotation reads writes
scanner x3Scanner, on each discipline peer@SpaceNotify(space = AUDIT, lease = "2h")the AuditTarget that cues itFinding in audit, then a Proposal in votes for each finding of its own discipline
panelist x3Panelist, on each discipline peer@Ballot(space = VOTES, lease = "2h")the Proposal that cues it, then the Finding with a ten-second waitone Ballot, written by the binder; none when the finding is missing
leadLead, on audit-lead@OnDecision(space = VOTES, lease = "2h")the Decision, then the target and the finding with ten-second waitsAdjudicatedFinding for each decision, and one AuditReport after the last
AuditFleet.java: binding the seven agents
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));
}
✓ group.bind(agent) reads the annotation, subscribes the cue, publishes the card

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.

Two names for an agentThe facade binds the classes under the peer's own identity, so their cards name 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.
aspace://guide/audit-fleet/forming · chapter 2

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.

HOW A PEER JOINS: group audit-fleet, founding text audit-fleet-v1audit-licensingdials the seed, :7682audit-security:7681, the first peerthe other peersaudit-privacy, audit-lead1 dial the seedthe seed address 127.0.0.1:7681 over tcp2 introducesigned peer ad, group id checked3 membershipthe newcomer is introduced to the members4 cards and adsagents, spaces, capabilities on one gossip stream5 spaces catch updigests, then rumorsthe group id is the hash of the text audit-fleet-v1, so every peer derives it locally;membership is OPEN, frames are signed, there is no TLS; the only authorizer is the VOTE grant on the vote space
How a peer joins. A new peer needs only a seed to dial. It proves a key, learns the members, hears every card, and its spaces fill from the replicas already there. No peer in the middle admits it and no registry holds it: the group id is the hash of the founding, and membership is what the members agree on.
setting value where
group name and foundingaudit-fleet, founded from the text audit-fleet-v1group()
membership policy, default strategyOPEN, LEASE_RACE; gossip fan-out 3, period 1 sgroup(), the library defaults
seed127.0.0.1:7681 in the demo (the first peer); a free port in the testmain, startPeer
transportplain TCP on 127.0.0.1, TcpTransport; frames signed (the default channel auth), no TLSstartPeer
membershipmember TTL 30 s, ping timeout 2 s, 2 indirect probes, one probe per secondGroupMembership.Config
tick250 ms (node.startTicking)startPeer
card refreshevery 5 minutes, from the peer tick, so cards and advertisements outlive their 15 minute leaseCardRefresh
securitya 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 protectionMembershipAuthorizer
identitya 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 renewedrenewingSubordinate
AuditFleet.java: the group and one peer
/** 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());
}
✓ four calls to startPeer make the fleet; the first has seedPort 0

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.

AGENT CARDS (one per bound agent, 15 min TTL, refreshed)scanneraudit-securityscanneraudit-licensingscanneraudit-privacypanelistaudit-securitypanelistaudit-licensingpanelistaudit-privacyleadaudit-leadany memberreads the cataloguea carda hint, never a rosterthe vote does not read cards:its electorate is the threepeers a VOTE grant names
Cards and the catalogue. Every discoverable thing is a signed, typed, time-limited card on one gossip stream. A planner or a console reads the catalogue to learn what exists. The design rule that follows is to route by entry type: a space and a record type deliver the work, and a discovered name only tells a reader where to look.

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
scanner
on z2ouj8...
scannotifyAuditTarget#v1nothingaudit
panelist
on z2ouj8...
judgeballotProposal#v1Ballot#v1votes
lead
on z28JcZ...
adjudicateon-decisionDecision#v1nothingvotes
What the cards leave outThe scanner's card says it produces nothing, because its method returns 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.

A 15 MINUTE LEASE: WHAT RE-PUBLISHING EVERY 5 MINUTES CHANGES0 min5 min10 min15 min20 min25 min30 minnothing re-publishesrefreshCards() never calledcard and advertisement: one issue, one leasegone from every ad cachethe tick re-publishesevery 5 minutesissue 1issue 2issue 3issue 4issue 5issue 6each issue restarts a lease,so at least 10 minutes of itare always left
The refresh clock. Agent cards and the vote advertisement carry a 15 minute lease and lapse from every ad cache unless something re-publishes them. The peer's own tick calls refreshCards() every 5 minutes, so a fleet that runs for hours keeps both.
keeping the leases alive
/** 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);
        }
    }
}
✓ the peer tick drives it; refreshCards() renews the cards and the attached capability advertisements

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.

HOW THE VOTE CAPABILITY IS FOUND: capabilities.register(vote), then providersOf(aspace:cap/vote)audit-securityregister(vote)audit-licensingregister(vote)audit-privacyregister(vote)audit-leadregister(vote)a signed CapabilityAdvertisement from each peergossiped on the stream the agent cards use, TTL 15 minutesAdCache on every peerfour unexpired ads of aspace:cap/votecapabilities().providersOf(VoteCapability.TYPE)the flow test waits for a non-empty listCapabilityAdvertisementid aspace://<group>/cap/vote/<peer>/votescapabilityType aspace:cap/voteversion 0.1binding space:votesparameters modes = QUORUM,MAJORITY_GOSSIPttl 15 minutesthe ad names the space to vote in; the tally decides who counts.a consumer that finds it still needs that space replica andits own signing key to cast a ballot.the agents in this fleet never call providersOf: each holdsits peer's own VoteCapability, and register() also puts thatcapability on the peer tick.
Finding the vote capability. Registering a capability on the peer's CapabilityRuntime signs and publishes its advertisement; any peer then lists the providers from its own ad cache. Each peer offers the vote over its own replica of the votes space, so a four-peer group shows four advertisements.
AuditFleetTest.java: the capability is found
/**
 * 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();
    }
}
✓ the other peer waits up to 60 s for a provider; the test asserts one is found and that the runtime rides the peer tick
aspace://guide/audit-fleet/spaces · chapter 3

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.

audit (LEASE_RACE, 150 ms settle, block exchange, every lease 2 h)AuditTargetaudittargetId, nameissues: findingId -> specevidence: 96 KiB, by hashwritten by the security peerFindingauditfindingId, targetId, disciplineconfidence, severitysummary, raisedBywritten by each scannerAdjudicatedFindingauditfindingId, discipline, severityverdict, confirmVotes,dismissVotes, targetCidwritten by the lead, per decisionAuditReportaudittargetId, targetCidconfirmed, dismissedriskVerdict, confirmedFindingsassembledAtMillis, assembledBywritten by the lead, onceno entry in either space is ever taken: nothing here is work to claim,so the lease race never runs. Entries are written, read, and watched.votes (LEASE_RACE, 150 ms)ProposalvotesproposalId = the findingIdquestionoptions: twoquorum: 3written by the scannerBallotvotesproposalIdoptionvoter: the agent, encodedwritten by the binder for @Ballotno block exchange: all inline
The two spaces. The audit space holds the artifact and everything the auditors conclude. The votes space holds only what the vote capability needs, which is what lets any member recount it. Both use the default strategy and the same two-hour lease.
record space written by read by lease
AuditTargetauditthe security peer (the demo and the test do this)the scanners, as a cue; the lead, with a timed read2 h
Findingauditeach scanner, for its own disciplinethe panelists, with a timed read by finding id; the lead2 h
Proposalvotesthe scanner, through vote().propose(...)the panelists, as a cue; every tally2 h
Ballotvotesthe binder, for each @Ballotevery tally2 h (the @Ballot lease)
AdjudicatedFindingauditthe lead, for each decisionthe lead, to roll up the report; anyone2 h
AuditReportauditthe lead, oncethe demo and the test, which poll for it2 h
AuditFleet.java: the records
/**
 * 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) {
}
✓ plain records; the codec turns them into CBOR, the space signs them

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.

ONE ENTRY IN THE SPACE votesVoteCapability.BallotproposalId "PRIV-1"option "CONFIRMED"voter the agent, encodedspace strategyLEASE_RACE, nothing is takenlease2 h, the @Ballot leasesigned byaudit-security key, AGENT_ATTESTED
An entry. Every shared fact in an AgentSpaces app is a typed record in a space. The space's strategy says how a take is decided, the lease says how long the entry lives, tags make it findable, and the signature says which agent wrote it and lets any member check that.
aspace://guide/audit-fleet/artifact · chapter 4

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.

THE ARTIFACT TRAVELS BY HASH: 96 KiB OF EVIDENCE, A 64 KiB INLINE LIMITwrite AuditTargetsecurity peer1over the limitblocks.put: a CID2record replicatespayloadRef, no payload3block fetchedfrom the writer4cue firestarget decoded5steps 1 and 2 on the writer; steps 3 to 5 on every other peer, where each scanner is cued once the evidence is locallead: read(AuditTarget, 10 s)a timed read waits for the blockrecordOf(entryId).payloadRef()the CID the target's entry carriestargetCidin each AdjudicatedFinding and the report6one hash names the target everywhere. The space stores the whole encoded AuditTarget as one block, and the entry carries thatblock's CID as its payload reference. The lead copies exactly that value into every adjudication and the report. A reader canfetch the block by that CID, which checks the hash as the bytes arrive, and find the evidence and the planted issues inside.the ballots do not carry the CID: only the lead's adjudications and the report do
The artifact by hash. The release bundle is larger than the 64 KiB a record may carry inline, so the space replicates a reference and the block exchange moves the bytes. A scanner's cue fires only after the evidence is local, which is why no scanner has to poll for it.
the content-addressed path
/**
 * 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);
}
✓ the write puts a block; the cue fires when the block lands; the lead reads the CID the entry carries

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.

What the hash bindsThe target CID appears in the lead's records, under the lead's key. The ballots do not carry it, and neither does the proposal, so the vote itself does not bind a panelist to the bytes the CID names; chapter 9 returns to this. A deployment that needs the ballots to name the target can put the CID into the proposal id or the question, since a ballot names its proposal.
aspace://guide/audit-fleet/run · chapter 5

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.

ONE AUDIT: 1 TARGET, 4 FINDINGS, 3 PANELISTSAuditTargetthe security peer writes it1scanners cued3 peers, evidence local2Finding x4each scanner, its discipline3Proposal x4vote.propose, quorum 34AuditReportlast: risk HIGH8AdjudicatedFinding x4the lead: verdict, CID7Decision x4@OnDecision at the lead6Ballot x123 panelists x 4 findings5gossip to the three panelistsshaded boxes are entries in a space; dashed boxes are things that happen: a cue, a decisionentries written: audit 10 (1 target, 4 findings, 4 adjudications, 1 report), votes 16 (4 proposals, 12 ballots)
One audit. The flow test and the demo walk the same eight steps. The top row runs left to right and the bottom row right to left. Steps 3 to 5 happen once per finding, in parallel across findings, and the report waits for the fourth adjudication.
  • 1. The security peer writes the AuditTarget with 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. scan walks the target's planted issues, skips those of other disciplines, and writes a Finding for 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 CONFIRMED and DISMISSED, and the quorum is PANEL, the size of the panel.
  • 5. Each panelist's @Ballot cue fires on the proposal. judge reads 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, adjudicate runs once for that proposal.
  • 7. It puts the decision in its pending map, reads the target and the finding, and writes an AdjudicatedFinding with 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.
AuditFleet.java: the three agent classes
/**
 * 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)));
        }
    }
}
✓ one annotated method per class; every write is a two-hour lease

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.

THE LEAD KEEPS A DECISION UNTIL IT HAS RECORDED ITdecision closes@OnDecision, once per replicapending mapput(id, decision): its only memorysettle()timed reads: the target, then each pending finding (10 s each)stays pendinga read timed outAdjudicatedFindingwritten, then removedAuditReportonce, after the lasta decision fires once per replica, so a lead that dropped oneon a timed-out read would never see it again.the retry comes from: the same call, up to 3 attempts in all;any later decision; or the host calling settle().pending() lists what still waits.the report waits for one adjudication per issue on the target
Pending decisions. The lead writes an adjudication as soon as it can read both the target and the finding. A decision it cannot yet record stays in the pending map, and every later call to settle tries it again. A late block or a late finding delays the verdict, and the lead still records it.

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.

Who proposesThe scanner opens each vote itself, with a call to 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.
aspace://guide/audit-fleet/vote · chapter 6

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.

THE VOTE ON ONE FINDING, AS THIS APP RUNS ITscannerthe finding's discipline peervotes spacea replica on every peerpanelist x3one on each discipline peerleadaudit-lead peer1Proposal(id, question,options, quorum 3), 2 h lease2gossip: the @Ballot cuefires once per proposal id3read the Finding (10 s wait)confidence x trust >= 504Ballot(id, option, voter)signed by the peer's agent key5gossip: ballots reach the leadthe tally counts peers63 counted: Decision@OnDecision, once7AdjudicatedFinding to auditwinner, tally, targetCid8any member: tally(id)recounted from its own replica
The vote protocol. Opening is an ordinary write. Voting is one signed entry per panelist. The decision is a computation: each replica's tally closes it the moment three peers' ballots are in, and the lead turns that into a record. Step 8 can run on any peer at any time.
VoteCapability.java: what is written and what is computed
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);
    }
}
✓ agentspaces-capabilities 0.5.0: the library code this fleet calls

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.

ONE PROPOSAL, AS A REPLICA SEES ITno proposalballots may arrive firstopen0 of 3 countedProposal1 of 3one peer counteda ballot counts2 of 3two peers counteda ballot countsdecided3 counted: winner, tally3rd ballot counts@OnDecision firesonce per replica, as the tally meets 3NEVER COUNTED, AT ANY TALLYa ballot whose voter field is not its signer (forged)a ballot for an option the proposal does not list (spoiled)a second ballot from a peer already counteda ballot from a peer the VOTE grant does not namea ballot from an issuer the group has revokeda recount reads the ballots in the space and themembership at the moment it runs: a fourth peer'sballot never counts, and a granted peer that hasleft the membership stops counting, so a decisionthe lead already recorded can recount as open.
A proposal's life. Ballots and proposals travel as separate entries with no order between them, so a replica can hold ballots before the Proposal. The tally reads whatever is there; the quorum is a count of peers the tally accepts, and the callback fires on the first read that reaches it.

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.

what the binder does for the two annotations
@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";
}
✓ one virtual thread per ballot and per decision; the deduplication sets live in the binding

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.

agentspaces-partybus: SafetyPanel.Lead.open, the annotation form
@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() + ")";
}
✓ not used by the audit fleet; see the developer guide for the attributes

The annotation's attributes and the once-per-replica rule are in the developer guide's chapter on @Propose, @Ballot and @OnDecision.

aspace://guide/audit-fleet/quorum · chapter 7

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.

where the electorate comes from
/**
 * 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();
    }
}
✓ a VOTE grant names the three panelist peers: only their ballots count, once each

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.

WHO COUNTS: THE VOTE GRANT FIRST, THEN ONE BALLOT PER PEERballot, by its signerVOTE grant names its peer?the tallyaudit-securityAGENT_ATTESTED, a panelistyes, grantedcounted: peer securityaudit-licensingAGENT_ATTESTED, a panelistyes, grantedcounted: peer licensingaudit-privacyAGENT_ATTESTED, a panelistyes, grantedcounted: peer privacyaudit-security/secondhypothetical: a second agent on that peeryes, grantedalready counted: one per peera fourth peerfor example audit-lead: authentic, replicatedno, not grantedignored at every tally3 counted: the quorum of 3 closesthe grant is the electorate: three peer ids on every peer's authorizer. Under it the counted identity is the peer, so one member is one ballot.Counting per agent is a different setting: an authorizer with agent-level VOTE grants, and ballots that are AGENT_ATTESTED.
Who counts. A ballot has to pass the grant before it is counted, and the tally then counts one per peer. The fourth peer's ballot is signed and replicated like any other and counts for nothing. The hypothetical second agent is a case the fleet does not run; it shows why a peer with ten agents still casts one ballot.

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.

THE RECOUNT: WHAT tally(proposalId) DOES TO EVERY BALLOT, IN ORDERstepwhat it dropsin this fleetread every Ballot for the proposal1issuer and attestation of eachall of themvoter field equals the issuer?2else forged, droppedevery ballot passesoption is on the Proposal?3else spoiled, droppedCONFIRMED or DISMISSEDissuer in the electorate predicate?4default: every authenticated issuerno card checkAGENT granularity: record attested?5only under AGENT countingskipped, PEERauthorizer permits VOTE here?6the grant's peers, who are members3 peers grantedissuer revoked in the group?7a revoked agent stops countingnone revokedfirst ballot per counted key8key = the issuer's peer under PEERone per peerdecision: counted >= quorumwinner = most votes; a tie goes to the lowest option nametwo options and three voters: no tie is possible
The recount. Any member runs this on its own replica and reaches the same answer for the same ballots. The checks come from the library's tally, in its order. The right column says what each check does in this fleet: the VOTE grant is the one check that narrows the electorate beyond the signature rules.
VoteCapability.java: the recount
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;
}
✓ agentspaces-capabilities 0.5.0; the same code runs on every replica

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.

aspace://guide/audit-fleet/verdicts · chapter 8

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 EACH SEAT TRUSTS EACH DISCIPLINE (trust(panel, finding))finding raised insecuritylicensingprivacyseat ofsecurity1.0own field0.7set in code0.8defaultlicensing0.8default1.0own field0.5set in codeprivacy0.8default0.6set in code1.0own fieldweighted = confidence x trust(seat, finding)ballot = CONFIRMED when weighted >= 50, else DISMISSEDa seat trusts its own field fully; elsewhere theweight is the cross-trust map or the default 0.8.the weights are asymmetric on purpose: privacytrusts a licensing finding at 0.6, licensing trustsa privacy finding at 0.5.a heavier border marks a weight set in CROSS_TRUST; the rest fall through to the defaultLIC-1 (85) clears the privacy seat at 51, one point over the linePRIV-1 (70) falls to 35 at the licensing seat and is dismissed there
The trust matrix. Each panelist is the same class with a different discipline. Its ballot is a deterministic function of the finding's confidence and this matrix, which is what makes the demo repeatable and the tallies assertable.
AuditFleet.java: trust, and the ballot it produces
/**
 * 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);
✓ weighted = confidence x trust; CONFIRMED at 50 or more

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-1
critical
95 x 1.0 = 95
CONFIRMED
95 x 0.8 = 76
CONFIRMED
95 x 0.8 = 76
CONFIRMED
confirm 3 / dismiss 0CONFIRMED
LIC-1
high
85 x 0.7 = 59.5
CONFIRMED
85 x 1.0 = 85
CONFIRMED
85 x 0.6 = 51
CONFIRMED
confirm 3 / dismiss 0CONFIRMED
PRIV-1
medium
70 x 0.8 = 56
CONFIRMED
70 x 0.5 = 35
DISMISSED
70 x 1.0 = 70
CONFIRMED
confirm 2 / dismiss 1CONFIRMED
SEC-2
low
55 x 1.0 = 55
CONFIRMED
55 x 0.8 = 44
DISMISSED
55 x 0.8 = 44
DISMISSED
confirm 1 / dismiss 2DISMISSED
PRIV-1 privacy medium confidence 70customer email logged at DEBUG in the payment pathaudit-security70 x 0.8= 56CONFIRMEDaudit-licensing70 x 0.5= 35DISMISSEDaudit-privacy70 x 1.0= 70CONFIRMEDconfirm 2 / dismiss 1survivesSEC-2 security low confidence 55stack traces returned verbatim in 500 responsesaudit-security55 x 1.0= 55CONFIRMEDaudit-licensing55 x 0.8= 44DISMISSEDaudit-privacy55 x 0.8= 44DISMISSEDconfirm 1 / dismiss 2does not surviveSEC-1 critical: 95, 76, 76 confirm 3 / dismiss 0LIC-1 high: 59.5, 85, 51 confirm 3 / dismiss 0
A finding that survives and one that does not. PRIV-1 loses the licensing seat at 0.5 trust but carries two to one; SEC-2 has only its own author behind it and is dismissed one to two. The tallies are the ones the flow test asserts. Each arrow carries the seat's weighted confidence; the line below the panels lists the two findings every seat confirmed.

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.

Deterministic on purposeNothing in the vote is random or model-driven, so a run is repeatable and a test can assert tallies. A real deployment would replace 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.
aspace://guide/audit-fleet/proof · chapter 9

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.

ONE SIGNED BALLOT, PART BY PART: WHAT EACH PART PROVES AND WHAT IT LEAVES OPENthe entrywhat it proveswhat it leaves openpayloadBallot(proposalId, option, voter)which option the signer chose on whichproposalwhy it chose it: no reasoning and notarget CID travel in the ballotissuer<peer>/audit-securityan agent of a peer the VOTE grant nameswrote it, and the peer is counted oncethat the grant is the right list: eachreplica checks its own configurationsignaturethe agent's own key + certificatethe peer certified that key for this agentname, so agents holding other keys cannotsign as itthat the key is safe: a stolen key signsuntil the group revokes itleaseexpires 2 h after the writethe ballots stand for as long as the leaserunsa lasting archive: after 2 h nobodycan recount unless it was copied outthe tallya count over every ballotany member repeats it and gets the sameanswerthat the lead's AdjudicatedFindingis honest: only a recount shows that
What the record proves. The signatures settle who voted and what, and the counting rules settle that the tally can be repeated. Whether the vote deserved trust depends on things outside the record, which a deployment has to add.

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-1CONFIRMEDz4i5G4.../audit-licensingAGENT_ATTESTED
SEC-1CONFIRMEDz2ouj8.../audit-privacyAGENT_ATTESTED
SEC-1CONFIRMEDz3yc1u.../audit-securityAGENT_ATTESTED
LIC-1CONFIRMEDz4i5G4.../audit-licensingAGENT_ATTESTED
LIC-1CONFIRMEDz2ouj8.../audit-privacyAGENT_ATTESTED
LIC-1CONFIRMEDz3yc1u.../audit-securityAGENT_ATTESTED
PRIV-1DISMISSEDz4i5G4.../audit-licensingAGENT_ATTESTED
PRIV-1CONFIRMEDz2ouj8.../audit-privacyAGENT_ATTESTED
PRIV-1CONFIRMEDz3yc1u.../audit-securityAGENT_ATTESTED
SEC-2DISMISSEDz4i5G4.../audit-licensingAGENT_ATTESTED
SEC-2DISMISSEDz2ouj8.../audit-privacyAGENT_ATTESTED
SEC-2CONFIRMEDz3yc1u.../audit-securityAGENT_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.

the probe: what it printed about the evidence and the two experiments
-- 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]]
✓ recorded 2026-11-04 with a scratch program that calls only the app's public classes

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 VOTE grant 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 AdjudicatedFinding copies 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.
aspace://guide/audit-fleet/died · chapter 10

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.

WHEN A SEAT IS MISSING: FIVE RECORDED CASES, AS THE LEAD'S REPLICA HOLDS THEM1 two of three panelists are boundtarget writtenthe audit starts herewait 12 safter8 ballots, 0 of 4 decided0 adjudications, no report2 the third panelist binds latebefore8 ballots, 0 of 4 decided0 adjudications, no reportbind it, wait 8 safter8 ballots, 0 of 4 decided0 adjudications, no report3 the lead binds late, after every ballotbefore12 ballots, 4 of 4 decided0 adjudications, no reportbind the lead, wait 8 safter12 ballots, 4 of 4 decided0 adjudications, no report4 a panelist's peer closes after the auditbefore12 ballots, 4 of 4 decided4 adjudications, report writtenclose audit-privacy, wait 4 safter12 ballots, 4 of 4 decided4 adjudications, report written5 the membership drops the closed peerbefore12 ballots, 4 of 4 decided4 adjudications, report writtenwait 40 s moreafter12 ballots, 0 of 4 decided4 adjudications, report written
When a seat is missing. The quorum is a fixed count, so a missing panelist leaves every proposal open, and a panelist that binds after the proposals were written never votes on them, because its cue is a notification of new entries. A lead that binds late misses every decision that closed before it, for the same reason. A panelist whose peer closes after voting changes nothing at first, because its ballots stay in the other replicas for their lease; once the lead's membership drops the closed peer, the grant stops counting its ballots, every decision recounts as open, and the adjudications and report already written stay.
recorded: what the lead's replica held
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
✓ recorded 2026-11-04; the first line of each block is the machine's date
  • 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 @Ballot binding 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. @OnDecision reacts 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 VOTE grant 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 and decision() answered nothing. The membership configuration in startPeer sets 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's settle()), 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.

aspace://guide/audit-fleet/running · chapter 11

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.

pom.xml: the version and the libraries
<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>
✓ compiler release 21; every AgentSpaces coordinate is 0.5.0
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.

AuditFleetTest.java: what the tests assert
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();
    }
}
✓ 5 tests, 5.2 s of test time, recorded 2026-11-04
  • 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) and SEC-2 (1 to 2). LIC-1 is 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 equals BlockExchange.cidOf of the encoded record, recomputed in the test.
  • The attribution is that all four adjudications and the report are issued by the audit-lead agent and read AGENT_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, and isDrivenByPeerTick() 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: mvn -q exec:java, recorded 2026-11-04
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.
✓ four findings · three specialists · one verdict
A shutdown race, and what the demo does about itOne demo run in three on this machine, before the change below, ended with a 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.
aspace://guide/audit-fleet/next

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 FIVE LAYERS, AND WHAT THE AUDIT FLEET STANDS ONagents and the binder@SpaceNotify scanners, @Ballot panelists, an @OnDecision lead; bound by the AgentSpaces facadeLayer 4 capabilitiesvote, ordered log, aggregate, content, remote actionsthe audit fleetaspace:cap/vote in QUORUM mode: proposals, ballots, decisionsLayer 3 spacesreplicated tuple spaces, leases, strategiesthe audit fleettwo replicated spaces: audit (with blocks) and votesLayer 2 discoverycards, advertisements, locatorsthe audit fleetagent cards and one vote advertisement per peer, re-published every 5 minutesLayer 1 peeringmembership, gossip, transportsthe audit fleetmembership and gossip over TcpTransport; the block exchange for the artifactLayer 0 identityEd25519 keys, signed documents, groupsthe audit fleetpeer keys; one certified agent key per peer (renewingSubordinate), 24 h
The layers under the app. Each layer rests on the one below. A highlighted layer is one the app uses directly; the rest still run beneath it and need no configuration here.

Taking it further

  • Real scanners. Replace the planted issue list with a SAST tool, a license scanner and a PII classifier behind the same Finding record, 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.