Unstructured documents become compliance filings on a fleet with no orchestrator and no broker. A scan is named by its content hash, three extractor agents read it in parallel, a quorum counts their signed extractions as ballots, fields the readers cannot settle go to a person (after a bounded wait when a reader is down), and the signed filing carries a provenance a regulator can walk from the scan's hash to the paperwork.
AgentSpaces 0.5.06 peers, 5 agents1 space, 5 record typesplain TCP on 127.0.0.1, every frame signedno model, no keys6 flow tests
Intake Fleet turns a scanned document into a compliance filing and keeps the evidence for every step. A coordinator writes scans into one replicated space. Three extractor agents of differing skill read every scan independently and write a confidence-scored Extraction for each field. An adjudicator counts those extractions as ballots: a value that a quorum of readers agree on, at enough confidence, becomes an ApprovedField, and a field the readers cannot settle becomes a ReviewItem for a person. An auditor writes the Filing once every field of a scan is approved.
Every one of those is a signed, leased entry in the same space, written by an agent under a key of its own. No orchestrator calls the stages and no broker carries messages between them: each agent subscribes to the entry type that cues it and writes the entry that cues the next. A crashed extractor removes one ballot, and a scan its remaining readers cannot settle goes to a person after a wait of 10 s.
The fleet's product is its audit trail. The figure follows one filing backward. The filing names the content hash of the scan, which rests on the approvals, which rest on the extractions those approvals counted, and each link names the agent key that signed it.
One filing, four signed links. The scan's content hash is the anchor: the auditor hashes the image it reads and writes the result into the filing. Each link names its predecessor by scanId (and field), and each is signed by an agent key its peer certified, so a regulator can check every signature, recount every tally and rehash the scan without trusting any agent's own account of itself.
The extractors are simulated. Each has a skill number and reads a field correctly when the scan's difficulty is at or below it. The coordination, the signatures and the hashes are the working parts; a real OCR or vision model would sit behind the same Extraction record, which is the seam the README names for taking the app further.
The numbers in this guideThe demo's three scans have difficulties 30, 60 and 95, and the three extractors have skills 90, 70 and 40. Every figure and table reads its numbers from the app's source, and the transcripts are runs of the 0.5.0 app recorded on 2026-11-04.
aspace://guide/intake-fleet/cast · chapter 2
The cast: five agents on five peers
Five agents run on five of the six peers; the sixth, the coordinator, hosts none. Each agent class carries @AgentSpec, which names the agent (extractor, adjudicator, auditor), and a @SpaceNotify method for each cue it reacts to: one for the extractor and the auditor, two for the adjudicator. The binder gives every bound agent a key of its own, so the agent id an entry carries reads <peerId>/extractor, <peerId>/adjudicator or <peerId>/auditor.
Each class also holds a Space intake field, injected by @SpaceRef(INTAKE). That field is the agent's own view of the one replica, so what the agent writes carries the agent's key.
Agent
Class and peer
Annotations
Reads
Writes
Coordinator
no class; the peer coordinator on :7561
none; it writes through the space handle
-
Scan, 2 h lease in the demo and the test
Extractor x 3
Extractor on extract-careful (skill 90), extract-fast (70), extract-cheap (40)
@SpaceNotify on extract(Scan), subscription lease 1h
@SpaceNotify on onScan(Scan) and on onExtraction(Extraction), lease 1d
every Extraction of the scan, with its issuer; each Scan, only to start the scan's review clock
an ApprovedField or a ReviewItem, 6 h lease
Auditor
Auditor on auditor, bound with the adjudicator's agent id
@SpaceNotify on onApproval(ApprovedField), lease 1d
the approvals the adjudicator issued, the issuers of the extractions that agreed, and the scan
a Filing, 7 d lease
The peers and the agents inside them. Five of the six peers host one agent. The adjudicator has two cues, the Scan (to start a review clock) and the Extraction (to tally). The coordinator hosts none: it writes the scans through its own space handle, signed as <peerId>/coordinator. The demo and the test start all six in one JVM, each with its own key and listener, so the wire between them is real TCP.
@AgentSpec(name = ADJUDICATOR, description = "Approves fields a quorum of extractors agree on",
goals = {"adjudicate"})
publicstaticfinalclassAdjudicatorimplementsAutoCloseable {
privatefinalint quorum;
privatefinalint confidenceThreshold;
privatefinalint expectedExtractors;
privatefinalDuration reviewWait;
privatefinalSet<String> decided = ConcurrentHashMap.newKeySet();
/** One sleeping review clock per scan, started when the scan is first heard of. */privatefinalMap<String, Thread> clocks = newConcurrentHashMap<>();
@SpaceRef(INTAKE)
Space intake;
publicAdjudicator(int quorum, int confidenceThreshold, int expectedExtractors,
Duration reviewWait) {
this.quorum = quorum;
this.confidenceThreshold = confidenceThreshold;
this.expectedExtractors = expectedExtractors;
this.reviewWait = Objects.requireNonNull(reviewWait, "reviewWait");
}
/** Starts the scan's review clock when the scan itself reaches this peer. */@SpaceNotify(space = INTAKE, lease = "1d")
publicvoidonScan(Scan doc) {
startClock(doc.scanId());
}
@SpaceNotify(space = INTAKE, lease = "1d")
publicvoidonExtraction(Extraction cue) {
startClock(cue.scanId());
settle(cue.scanId(), cue.field(), false);
}
/** Stops the review clocks; the bound agent itself is closed through its binding. */@Overridepublicvoidclose() {
clocks.values().forEach(Thread::interrupt);
}
privatevoidstartClock(String scanId) {
clocks.computeIfAbsent(scanId, id -> Thread.ofVirtual().name("review-clock-" + id).start(() -> {
try {
Thread.sleep(reviewWait);
} catch (InterruptedException closed) {
return;
}
// The wait is over: whatever is still open goes to a person.try {
for (String field : FIELDS) {
settle(id, field, true);
}
} catch (RuntimeException e) {
System.getLogger(IntakeFleet.class.getName()).log(System.Logger.Level.WARNING,
"review clock for " + id + " failed", e);
}
}));
}
/**
* Counts the ballots for one field of a scan and writes the outcome, once
* per field ({@code decided}): an approval when a quorum agrees at enough
* confidence, a review item when the field is not approvable and either
* every expected extractor has answered or {@code waitOver} says no more are
* coming.
*/privatevoidsettle(String scanId, String field, boolean waitOver) {
String key = scanId + "/" + field;
if (decided.contains(key)) {
return;
}
Map<String, Space.Issued<Extraction>> ballots = ballots(intake, scanId, field);
Map<String, List<Space.Issued<Extraction>>> byValue = newLinkedHashMap<>();
for (Space.Issued<Extraction> e : ballots.values()) {
byValue.computeIfAbsent(e.entry().value(), v -> newArrayList<>()).add(e);
}
Map.Entry<String, List<Space.Issued<Extraction>>> best = byValue.entrySet().stream()
.max(Comparator.comparingInt(en -> en.getValue().size()))
.orElse(null);
int votes = best == null ? 0 : best.getValue().size();
int meanConfidence = best == null ? 0 : (int) best.getValue().stream()
.mapToInt(e -> e.entry().confidence()).average().orElse(0);
String guess = best == null ? "" : best.getKey();
int answered = ballots.size();
if (votes >= quorum && meanConfidence >= confidenceThreshold) {
if (decided.add(key)) {
intake.write(newApprovedField(scanId, field, guess,
votes, meanConfidence, intake.writer().orElseThrow().encoded()),
Lease.of(Duration.ofHours(6)));
}
} elseif (answered >= expectedExtractors || waitOver) {
// Every extractor has weighed in and none reached quorum agreement// (or agreement is too weak), or the wait for the rest is over: a// human decides.if (decided.add(key)) {
String reason = votes + "/" + answered + " agreed, confidence " + meanConfidence;
if (answered < expectedExtractors) {
reason += ", " + answered + " of " + expectedExtractors
+ " extractors answered within " + seconds(reviewWait);
}
intake.write(newReviewItem(scanId, field, reason, guess, meanConfidence),
Lease.of(Duration.ofHours(6)));
}
}
}
}
@AgentSpec(name = "auditor", description = "Files a compliance record with its provenance",
goals = {"file"})
publicstaticfinalclassAuditor {
privatefinalAgentId adjudicator;
privatefinalSet<String> filed = ConcurrentHashMap.newKeySet();
@SpaceRef(INTAKE)
Space intake;
/**
* @param adjudicator the one agent whose approvals the auditor files from
*/publicAuditor(AgentId adjudicator) {
this.adjudicator = Objects.requireNonNull(adjudicator, "adjudicator");
}
@SpaceNotify(space = INTAKE, lease = "1d")
publicvoidonApproval(ApprovedField cue) {
String scanId = cue.scanId();
if (filed.contains(scanId)) {
return;
}
// An approval counts only when the adjudicator issued it, and issued it// under its own certified key: the issuer is read from the entry's// signature (readAllIssued), never from decidedBy, a field the entry// declares about itself. Any other member's ApprovedField is ignored,// including the one that cued this method.Map<String, ApprovedField> approved = newTreeMap<>();
for (Space.Issued<ApprovedField> a : intake.readAllIssued(
Template.of(ApprovedField.class).where("scanId", eq(scanId)), 100)) {
if (a.issuer().equals(adjudicator)
&& a.attestation() == Space.Attestation.AGENT_ATTESTED) {
approved.putIfAbsent(a.entry().field(), a.entry());
}
}
if (!approved.keySet().containsAll(FIELDS)) {
return; // not every field is approved yet
}
Map<String, String> fields = newTreeMap<>();
approved.values().forEach(f -> fields.put(f.field(), f.value()));
// The contributing extractors for the provenance record: the// authenticated issuers whose extraction agrees with a filed value, not// the names they declared, and not the dissenters. The approval says how// many extractors agreed (votes); the extractions travel separately from// the approval, so wait, up to READ_WAIT, until this replica shows that// many for every field, and then list the agreeing issuers it sees.Set<String> extractors = newTreeSet<>();
long giveUp = System.nanoTime() + READ_WAIT.toNanos();
while (true) {
extractors.clear();
boolean complete = true;
for (ApprovedField field : approved.values()) {
int agreeing = 0;
for (Space.Issued<Extraction> e : ballots(intake, scanId, field.field()).values()) {
if (e.entry().value().equals(field.value())) {
extractors.add(e.issuer().encoded());
agreeing++;
}
}
complete &= agreeing >= field.votes();
}
if (complete || System.nanoTime() >= giveUp) {
break;
}
if (!pause(100)) {
return; // the binding closed while the auditor waited
}
}
// A scan's image is over the inline limit, so the entry travels// content-addressed; the timed read waits for the block if it has not// landed here yet, rather than degrading the provenance to "unknown".// The hash is of the image alone: the Scan entry's payloadRef names the// encoded record, a different block, so the filing carries the one hash// anyone holding the scan can recompute.String contentHash = intake.read(
Template.of(Scan.class).where("scanId", eq(scanId)),
READ_WAIT)
.map(s -> BlockExchange.cidOf(s.image()))
.orElse("unknown");
if (filed.add(scanId)) {
intake.write(newFiling(scanId, fields, contentHash,
newArrayList<>(extractors), System.currentTimeMillis()),
Lease.of(Duration.ofDays(7)));
}
}
}
A peer binds an agent with peer.group().bind(agent), the one-line enrollment the developer guide describes. The bindings in main give the demo its cast: the extractors differ only by the number passed to runExtractor, and the adjudicator takes its quorum, its confidence threshold, the number of extractors it expects and how long to wait for them (REVIEW_WAIT, 10 s, unless a caller passes another). The auditor takes the agent id of the adjudicator, which adjudicatorId derives from the adjudicator's peer. The adjudicator also owns a review clock per scan, so runAdjudicator returns a closeable that stops the clocks and then unbinds the agent.
aspace://guide/intake-fleet/fleet · chapter 3
How the fleet forms and how the agents find each other
All six peers join one group, intake-fleet, whose id is the hash of the founding text intake-fleet-v1. The coordinator starts first, with no seed, and listens on 127.0.0.1:7561. Each later peer listens on its own port (7562 to 7566) and dials the coordinator. The demo and the test start all six in one JVM; the demo uses these fixed ports and the test asks the operating system for free ones.
Setting
Value
Where it comes from
Group name, founding
intake-fleet, literal intake-fleet-v1
IntakeFleet.group()
Group id
sha-256 of the founding text, base58btc
GroupId.fromFounding
Membership policy
OPEN
the group advertisement
Default strategy
LEASE_RACE
the group advertisement
Seed
127.0.0.1:7561, the coordinator
startPeer(name, port, seedPort)
Transport
TcpTransport on 127.0.0.1, one port per peer
node.listen
Security
every frame carries the peer's signature (ChannelAuth.SIGNED); no TLS
the PeerNode default
Membership
member TTL 10 s, ping timeout 2 s, 2 indirect probes, one probe per second
GroupMembership.Config
Gossip
fanout 3, period 1 s
GossipParameters.defaults()
Tick
250 ms
node.startTicking
Space settle window
150 ms
ReplicatedSpace.builder(...).settleWindow
Agent key certificates
24 h, renewing
renewingSubordinate
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. Every later peer dials the coordinator, then learns the rest from it.
A literal-id group is never served to a newcomer who asks by group id, so every peer here dials the seed's address; the demo needs no beacon, no DNS and no invitation. Each call to group() builds the group advertisement with a fresh throwaway issuer key, which the group id does not depend on, since the id comes from the founding text alone. In step 4 of the figure the gossip stream carries no agent cards, because the app publishes none.
Forming the group_□×
/**
* Assembles one peer with a content-addressed intake space.
*
* @param name the agent name
* @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
*/publicstaticPeerstartPeer(String name, int port, int seedPort) throwsException {
PeerIdentity identity = PeerIdentity.generate();
PeerNode node = PeerNode.builder(identity).build();
node.listen(newTcpTransport(), HOST + ":" + port);
List<PeerAdvertisement.Endpoint> seeds = seedPort == 0 ? List.of()
: List.of(newPeerAdvertisement.Endpoint("tcp", HOST + ":" + seedPort, 0));
GroupRuntime runtime = node.joinGroup(group(),
newGroupMembership.Config(MEMBER_TTL, Duration.ofSeconds(2), 2),
seeds);
// The provenance chain is only as good as its attribution: every agent// here signs with a key of its own that its peer certifies (SPEC §4.2), so// extractions, approvals, and filings read as AGENT_ATTESTED everywhere.ReplicatedSpace intake = ReplicatedSpace.builder(runtime, "intake", identity, name)
.writer(identity.renewingSubordinate(name, java.time.Duration.ofHours(24), java.time.InstantSource.system()))
.settleWindow(Duration.ofMillis(150))
// The default block store is in memory (512 MiB quota): a scan's block// lives as long as the process and the quota allow, whatever the// entry's lease says.
.blocks(newBlockExchange(runtime, CborCodec.defaultCodec()))
.build();
// The agents are annotated POJOs bound through the facade; with the// subordinate identity factory each one signs with a certified key of its// own and its @SpaceRef is a per-agent view of the one replica. The last// argument, the discovery service, is null on purpose: this fleet publishes// no agent cards, because its agents are cued by entry type and never look// each other up. Pass a DiscoveryService here to publish cards.AgentSpaces spaces = newAgentSpaces(identity, InstantSource.system(),
agentName -> identity.renewingSubordinate(agentName, java.time.Duration.ofHours(24), java.time.InstantSource.system()));
AgentSpaces.GroupContext group = spaces.register("intake-fleet", runtime.id(), runtime, null);
group.space(INTAKE, intake);
node.startTicking(Duration.ofMillis(250));
returnnewPeer(name, node, runtime, intake, spaces, group);
}
The app passes null as the discovery service to register, and the binder publishes an agent card only when it has one. So the fleet has no catalogue of agents and needs none. The adjudicator is cued by any Extraction that replicates to its peer, whoever wrote it, and by any Scan, which starts that scan's review clock. The auditor is cued by any ApprovedField. No agent looks another up, and a fourth extractor on a seventh peer would add its ballots by binding the same class. The auditor holds a single name, the adjudicator's agent id, which its caller passes at bind time, and it uses the id to decide whose approvals to believe. The coordinator, which hosts no agent, takes part the same way: it writes a Scan and later reads the Filing.
How the agents find each other. They do not need to. The app publishes no agent cards, so the routing is by entry type: a replica that holds a Scan cues the extractors and starts the adjudicator's review clock, one that holds an Extraction cues the adjudicator, one that holds an ApprovedField cues the auditor. The auditor holds one name, the adjudicator's agent id, to decide whose approvals to believe. A card catalogue would help a planner or a console find the agents, and the discovery argument of register is where an app would turn one on.
A catalogue earns its place when a planner or an operator console has to find agents by what they do. The developer guide's cards section covers how a DiscoveryService turns the @AgentSpec annotations into signed cards, and the last argument of register is where an app like this one would pass it.
aspace://guide/intake-fleet/spaces · chapter 4
The space: one replica, five record types
The fleet has one space, intake, built on every peer with the same call: a ReplicatedSpace with the peer's identity, a writer identity named after the peer, a 150 ms settle window and a BlockExchange so records above the inline limit travel by hash. Its strategy is the default, LEASE_RACE. A strategy decides who wins a take, and this app never takes an entry, so the strategy never arbitrates anything. Every agent only reads and writes, which is what lets any number of extractors work the same scan.
Record
Fields
Written by
Lease
Cue for
Scan
scanId, truth, difficulty, image
the coordinator
2 h
the extractors, and the adjudicator's review clock
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.
The five records_□×
/**
* A scanned document. {@code image} stands in for the page bitmap and is
* deliberately larger than the inline payload limit, so the space
* content-addresses it; {@code difficulty} models how smudged the scan is.
*
* <p>Two names for the same scan exist, and they differ. The space names the
* block it stores by the hash of the <em>encoded record</em> (the image plus
* {@code scanId}, {@code truth} and {@code difficulty}) and carries that name
* in the entry's {@code payloadRef}. The {@link Filing} carries the hash of the
* <em>image alone</em>, which anyone holding the scan can recompute.
*
* @param scanId the document id
* @param truth the correct field values (what a perfect read yields)
* @param difficulty 0 (clean) to 100 (barely legible)
* @param image the page image bytes (content-addressed)
*/publicrecordScan(String scanId, Map<String, String> truth, int difficulty,
byte[] image) {
}
/** One extractor's read of one field of a scan, with its confidence. */publicrecordExtraction(String scanId, String field, String value,
String extractor, int confidence) {
}
/** A field the fleet agreed on: a quorum of extractors read the same value. */publicrecordApprovedField(String scanId, String field, String value,
int votes, int confidence, String decidedBy) {
}
/** A field that could not be agreed: routed to a human review queue. */publicrecordReviewItem(String scanId, String field, String reason,
String bestGuess, int confidence) {
}
/**
* The compliance filing, with the provenance chain that backs it:
* {@code scanContentHash} is the CID of the scan's image alone (not the
* {@code payloadRef} of the Scan entry, which names the encoded record), and
* {@code contributingExtractors} lists the authenticated agent ids of the
* extractors whose extraction agreed with a filed value.
*/publicrecordFiling(String scanId, Map<String, String> fields, String scanContentHash,
List<String> contributingExtractors, long filedAtMillis) {
}
✓ sliced from IntakeFleet.java
Every record carries scanId, which is the correlation key of the whole pipeline: the adjudicator selects the extractions of one scan with Template.of(Extraction.class).where("scanId", eq(scanId)), and the auditor does the same for approvals and for the scan itself. The records of different scans interleave freely in the one space.
Retention is a lease. The coordinator picks the scan's lease and each agent picks the lease of what it writes. A subscription's lease is renewed at half-lease for as long as the agent stays bound. The filing outlives its scan by a wide margin, which is why it carries the scan's hash: once the scan's lease lapses, the hash is what a copy gets checked against.
The leases carry the retention policy. The coordinator picks the scan's lease (2 h here), so how long the personal data of a document stays visible in the fleet is a decision one line makes at intake. An extraction lives 1 h, an approval or a review item 6 h, and a filing 7 d. The subscription leases on the @SpaceNotify annotations only bound how long a crashed agent's subscription can linger: the binder renews them at half-lease while the agent stays bound.
aspace://guide/intake-fleet/run · chapter 5
One run, end to end
This chapter follows scan-1040-b, the demo's middle scan (difficulty 60), from the coordinator to the filing. The seven steps of the figure each map to a few lines of the app. The adjudicator's replica also receives the scan, which starts the review clock that a later chapter explains; on this scan the clock never matters, because the extractors answer first.
One run. Seven steps carry a scan to a filing. Every arrow is the replication of an entry; no agent calls another. Steps 2, 4 and 6 are local work on one peer's replica, and the step-7 filing reaches the coordinator and everyone else the same way the scan reached the extractors.
Step 1: the coordinator writes the scans
The demo writes three scans through the coordinator's space handle, each with a 2 h lease. scan(...) builds an image of 80 KiB, which is above the 64 KiB inline limit, so the space stores it as a block and the record carries its hash. The next chapter follows that hash.
Each extractor's replica receives the scan record, fetches the image block, and then the binder calls extract(Scan) once for the entry. The method writes one Extraction per field with a confidence. The reading is simulated by the skill rule that the fan-out chapter lays out.
Every Extraction that replicates to the adjudicator's peer cues onExtraction, which passes the scan and the field to settle. Each cue rereads every extraction of that scan, so the outcome follows the evidence present when the cue runs. When a field reaches the quorum at enough confidence it writes an ApprovedField with the vote count, the mean confidence and its own agent id.
The adjudicator_□×
/** Starts the scan's review clock when the scan itself reaches this peer. */@SpaceNotify(space = INTAKE, lease = "1d")
publicvoidonScan(Scan doc) {
startClock(doc.scanId());
}
@SpaceNotify(space = INTAKE, lease = "1d")
publicvoidonExtraction(Extraction cue) {
startClock(cue.scanId());
settle(cue.scanId(), cue.field(), false);
}
privatevoidstartClock(String scanId) {
clocks.computeIfAbsent(scanId, id -> Thread.ofVirtual().name("review-clock-" + id).start(() -> {
try {
Thread.sleep(reviewWait);
} catch (InterruptedException closed) {
return;
}
// The wait is over: whatever is still open goes to a person.try {
for (String field : FIELDS) {
settle(id, field, true);
}
} catch (RuntimeException e) {
System.getLogger(IntakeFleet.class.getName()).log(System.Logger.Level.WARNING,
"review clock for " + id + " failed", e);
}
}));
}
/**
* Counts the ballots for one field of a scan and writes the outcome, once
* per field ({@code decided}): an approval when a quorum agrees at enough
* confidence, a review item when the field is not approvable and either
* every expected extractor has answered or {@code waitOver} says no more are
* coming.
*/privatevoidsettle(String scanId, String field, boolean waitOver) {
String key = scanId + "/" + field;
if (decided.contains(key)) {
return;
}
Map<String, Space.Issued<Extraction>> ballots = ballots(intake, scanId, field);
Map<String, List<Space.Issued<Extraction>>> byValue = newLinkedHashMap<>();
for (Space.Issued<Extraction> e : ballots.values()) {
byValue.computeIfAbsent(e.entry().value(), v -> newArrayList<>()).add(e);
}
Map.Entry<String, List<Space.Issued<Extraction>>> best = byValue.entrySet().stream()
.max(Comparator.comparingInt(en -> en.getValue().size()))
.orElse(null);
int votes = best == null ? 0 : best.getValue().size();
int meanConfidence = best == null ? 0 : (int) best.getValue().stream()
.mapToInt(e -> e.entry().confidence()).average().orElse(0);
String guess = best == null ? "" : best.getKey();
int answered = ballots.size();
if (votes >= quorum && meanConfidence >= confidenceThreshold) {
if (decided.add(key)) {
intake.write(newApprovedField(scanId, field, guess,
votes, meanConfidence, intake.writer().orElseThrow().encoded()),
Lease.of(Duration.ofHours(6)));
}
} elseif (answered >= expectedExtractors || waitOver) {
// Every extractor has weighed in and none reached quorum agreement// (or agreement is too weak), or the wait for the rest is over: a// human decides.if (decided.add(key)) {
String reason = votes + "/" + answered + " agreed, confidence " + meanConfidence;
if (answered < expectedExtractors) {
reason += ", " + answered + " of " + expectedExtractors
+ " extractors answered within " + seconds(reviewWait);
}
intake.write(newReviewItem(scanId, field, reason, guess, meanConfidence),
Lease.of(Duration.ofHours(6)));
}
}
}
✓ sliced from IntakeFleet.java
Steps 6 and 7: the auditor files
Each ApprovedField cues onApproval. The auditor rereads the approvals of the scan and keeps those the adjudicator issued. When every field in FIELDS is among them, it lists the issuers of the extractions that agreed with the filed values, hashes the image and writes the Filing. The timed read of the scan keeps the filing from degrading its provenance to "unknown" when the image block has not reached the auditor's peer yet.
The auditor_□×
@SpaceNotify(space = INTAKE, lease = "1d")
publicvoidonApproval(ApprovedField cue) {
String scanId = cue.scanId();
if (filed.contains(scanId)) {
return;
}
// An approval counts only when the adjudicator issued it, and issued it// under its own certified key: the issuer is read from the entry's// signature (readAllIssued), never from decidedBy, a field the entry// declares about itself. Any other member's ApprovedField is ignored,// including the one that cued this method.Map<String, ApprovedField> approved = newTreeMap<>();
for (Space.Issued<ApprovedField> a : intake.readAllIssued(
Template.of(ApprovedField.class).where("scanId", eq(scanId)), 100)) {
if (a.issuer().equals(adjudicator)
&& a.attestation() == Space.Attestation.AGENT_ATTESTED) {
approved.putIfAbsent(a.entry().field(), a.entry());
}
}
if (!approved.keySet().containsAll(FIELDS)) {
return; // not every field is approved yet
}
Map<String, String> fields = newTreeMap<>();
approved.values().forEach(f -> fields.put(f.field(), f.value()));
// The contributing extractors for the provenance record: the// authenticated issuers whose extraction agrees with a filed value, not// the names they declared, and not the dissenters. The approval says how// many extractors agreed (votes); the extractions travel separately from// the approval, so wait, up to READ_WAIT, until this replica shows that// many for every field, and then list the agreeing issuers it sees.Set<String> extractors = newTreeSet<>();
long giveUp = System.nanoTime() + READ_WAIT.toNanos();
while (true) {
extractors.clear();
boolean complete = true;
for (ApprovedField field : approved.values()) {
int agreeing = 0;
for (Space.Issued<Extraction> e : ballots(intake, scanId, field.field()).values()) {
if (e.entry().value().equals(field.value())) {
extractors.add(e.issuer().encoded());
agreeing++;
}
}
complete &= agreeing >= field.votes();
}
if (complete || System.nanoTime() >= giveUp) {
break;
}
if (!pause(100)) {
return; // the binding closed while the auditor waited
}
}
// A scan's image is over the inline limit, so the entry travels// content-addressed; the timed read waits for the block if it has not// landed here yet, rather than degrading the provenance to "unknown".// The hash is of the image alone: the Scan entry's payloadRef names the// encoded record, a different block, so the filing carries the one hash// anyone holding the scan can recompute.String contentHash = intake.read(
Template.of(Scan.class).where("scanId", eq(scanId)),
READ_WAIT)
.map(s -> BlockExchange.cidOf(s.image()))
.orElse("unknown");
if (filed.add(scanId)) {
intake.write(newFiling(scanId, fields, contentHash,
newArrayList<>(extractors), System.currentTimeMillis()),
Lease.of(Duration.ofDays(7)));
}
}
✓ sliced from IntakeFleet.java
aspace://guide/intake-fleet/content · chapter 6
Content addressing: the hash names the scan
A scan's image is 80 KiB. A record carries at most 64 KiB inline, so the space encodes the Scan, stores the encoding as a block named by its sha-256, and writes a record whose payloadRef holds that name. The record gossips to every replica without the image. A replica that holds the record and not the block fetches it from a peer that does.
From a Scan to a signed reference. The space encodes the entry, sees that it exceeds the 64 KiB inline limit, and stores the payload as a block named by its sha-256. The record that gossips carries only that name, so every replica holds the signed reference and fetches the bytes from a peer that has them.
Where the space decides_□×
String payloadRef = null;
if (bulk == null && maxPayload > 0 && payload.length > maxPayload) {
thrownewIllegalArgumentException("payload of " + payload.length + " bytes exceeds " + maxPayload
+ " bytes and this space has no content swarm to carry it; turn on agentspaces.content.enabled"
+ " (escalate-above) or write it through Content.publish");
}
if (bulk != null && escalateAbove > 0 && payload.length > escalateAbove) {
// LB-E-02: above the threshold the payload becomes an artifact of the content// swarm and the record carries its root; the space replicates the reference only.
payloadRef = bulk.publish(payload, lease);
payload = null;
} elseif (payload.length > EntryRecord.INLINE_PAYLOAD_LIMIT) {
if (blocks == null) {
thrownewIllegalStateException("payload of " + payload.length
+ " bytes exceeds the inline limit; configure builder.blocks(...)");
}
payloadRef = blocks.put(payload);
blocks.retain(payloadRef); // LB-B-04: a live entry pins its block
payload = null;
}
/**
* Computes the CID of some bytes.
*
* @param bytes the bytes
* @return the CID
*/publicstaticStringcidOf(byte[] bytes) {
returnMultibase.base58btc(Digests.sha256(bytes));
}
/**
* Stores bytes locally and returns their CID.
*
* @param bytes the payload
* @return the CID
* @throws IllegalArgumentException when the block exceeds {@link #maxBlockBytes()},
* since no binding could ever deliver it (LB-B-06)
*/publicStringput(byte[] bytes) {
Objects.requireNonNull(bytes, "bytes");
if (bytes.length > maxBlockBytes) {
refusedOversize.incrementAndGet();
thrownewIllegalArgumentException("block of " + bytes.length
+ " bytes exceeds the largest block a frame carries (" + maxBlockBytes
+ " bytes); a payload this large needs the content swarm"
+ " (agentspaces.content.escalate-above)");
}
String cid = cidOf(bytes);
storeBlock(cid, bytes.clone());
return cid;
}
✓ AgentSpaces 0.5.0 library sources
This app takes the last branch of prepareWrite: no swarm is attached (bulk is null) and maxPayload is 0, so a payload above the inline limit goes to blocks.put. The name is a function of the bytes: BlockExchange.cidOf is z followed by the base58btc of the sha-256. Every member that computes it over the same bytes gets the same string, and a member that receives a block recomputes the hash before it stores anything. The demo's scans also have stable hashes: scan() fills the image deterministically from the scan id, the taxpayer id and the amount, so scan-1040-a is the same 81920 bytes and carries the same hash on every run.
The hash is checked on arrival_□×
if (block == null || block.cid() == null || block.bytes() == null
|| !cidOf(block.bytes()).equals(block.cid())) {
return; // corrupt or forged: the CID is the integrity check
}
/** Builds a scan whose image exceeds the inline limit (so it is content-addressed). */publicstaticScanscan(String scanId, String taxpayerId, String amount, int difficulty) {
byte[] image = new byte[IMAGE_BYTES];
// Fill deterministically from the id so the content hash is stable per scan.
byte[] seed = (scanId + taxpayerId + amount).getBytes(StandardCharsets.UTF_8);
for (int i = 0; i < image.length; i++) {
image[i] = seed[i % seed.length];
}
returnnewScan(scanId, Map.of("taxpayerId", taxpayerId, "amount", amount),
difficulty, image);
}
✓ AgentSpaces 0.5.0 library sources, and the app
How an extractor gets the image
When a record arrives whose payload lives in a block that is not local, the space does not fire the WRITTEN event. It starts a background fetch, asks the writer first and then two random members, and fires the event when the verified block lands. That is why extract can take the Scan as its parameter: by the time the binder calls it, the image is in hand. The first attempt waits 800 ms; a miss retries on the tick with growing gaps while the entry lives.
The block path. A reader never waits on the network inside a read, and a notify subscriber does not poll: the space starts the fetch, holds the event back and fires it when the verified block lands. A missed answer retries on the tick (attempts wait 0.8, 2, 5, then 15 s; the gaps are 2, 5, 15, then 60 s) for as long as the entry lives.
What to watch for
The block is named by the hash of the encoded record. The bare image hashes to a different value, so the entry's payloadRef differs from the scanContentHash the filing carries. For scan-1040-a a scratch driver measured an encoding of 82,007 bytes named zvxzoVqb2HoSAirsaVYopUybmFyWbJxgD2TyPrJpGn1c on 2026-11-04, while the filing's hash is zCYjUBUAoe4Ak6VGxHW8iv1gtLcNs3ccQb6VN94np11TB, the image alone at 81,920 bytes.
The block cap is the 8 MiB frame less 64 KiB. This app attaches only the block exchange, so a scan whose encoding exceeds the cap fails at write time with a message that names the content swarm. The demo's 80 KiB is nowhere near it.
A lapsed scan stops matching reads at its lease. The space collects it later and unpins the block, but the default block store is in memory with a 512 MiB quota, so the bytes leave when the quota needs the room or the process ends.
aspace://guide/intake-fleet/fanout · chapter 7
Parallel extraction: everyone reads, no one takes
@SpaceNotify is the choreography sibling of @SpaceTake: the method runs for every matching entry and does not consume it. All three extractors therefore see every scan, each on its own replica, and each runs extract on its own virtual thread, so a slow reader never holds the fabric's delivery thread. The binder deduplicates delivery per entry, so a re-delivered Scan does not make an extractor write its extractions twice.
The fan-out. The three extractors differ only in skill, a number the Extractor compares with the scan's difficulty. A reader whose skill covers the scan reads the true value at confidence 60 or more; the others write a misread at 45 or less. On the hardest scan the careful and the fast reader misread the same character, so two readers agree on a wrong value, and only the confidence gate keeps it out of the filing.
The table is the demo run seen from the extractors. Their skills are 90, 70 and 40. On scan-1040-a (difficulty 30) all three read the true value, at confidence 90, 80 and 65. On scan-1040-b (difficulty 60) the cheap extractor misreads and writes TP-22022 at confidence 35; the other two outvote it. On scan-1040-c (difficulty 95) nobody can read it, and the careful and the fast reader happen to misread the same character, which the confidence chapter returns to.
What a take would have changed
With @SpaceTake each scan would go to one extractor under a lease, and a dead extractor would hand it to the next. That is the right shape for work that needs doing once. Here the point is the opposite: several independent readings of one document, each a separate witness. A crashed extractor leaves a missing ballot for what it had not yet written, and its earlier extractions stay in the other replicas until their leases lapse.
The extractors are interchangeable and unequalNothing in the space says that the careful extractor is better. The skill is the extractor's own number, and the only thing the fleet sees of it is the confidence on each Extraction.
aspace://guide/intake-fleet/ballots · chapter 8
Evidence as ballots: one member, one vote
The adjudicator's quorum is a vote whose ballots are the signed extractions. It does not ask the extractors to vote again. It reads the evidence with readAllIssued, which returns each value together with its authenticated issuer, and counts per issuing peer. The extractor a record declares about itself is a label; the voter is the key that signed it.
One member, one vote. The adjudicator reads the extractions with readAllIssued, which pairs each value with the authenticated issuer, and keeps the first entry per issuing peer. The names a writer puts inside the record are labels. The test aRogueExtractorWritingUnderTwoNamesCountsOnce writes exactly this and asserts that no field is approved.
The count_□×
/**
* The first extraction each issuing peer wrote for one field of a scan: the
* evidence-as-ballots rule (SPEC §8). A ballot's voter is the entry's
* authenticated issuer, never a field the entry declares about itself, and one
* member is one vote, counted per issuing peer, exactly as the vote capability
* counts at PEER granularity. An extractor that wrote the same value twice, or
* under two invented names, still counts once.
*/privatestaticMap<String, Space.Issued<Extraction>> ballots(Space intake, String scanId, String field) {
Map<String, Space.Issued<Extraction>> firstPerMember = newLinkedHashMap<>();
for (Space.Issued<Extraction> e : intake.readAllIssued(
Template.of(Extraction.class).where("scanId", eq(scanId)), 1000)) {
if (e.entry().field().equals(field)) {
firstPerMember.putIfAbsent(e.issuer().peer().value(), e);
}
}
return firstPerMember;
}
Map<String, Space.Issued<Extraction>> ballots = ballots(intake, scanId, field);
Map<String, List<Space.Issued<Extraction>>> byValue = newLinkedHashMap<>();
for (Space.Issued<Extraction> e : ballots.values()) {
byValue.computeIfAbsent(e.entry().value(), v -> newArrayList<>()).add(e);
}
Map.Entry<String, List<Space.Issued<Extraction>>> best = byValue.entrySet().stream()
.max(Comparator.comparingInt(en -> en.getValue().size()))
.orElse(null);
int votes = best == null ? 0 : best.getValue().size();
int meanConfidence = best == null ? 0 : (int) best.getValue().stream()
.mapToInt(e -> e.entry().confidence()).average().orElse(0);
String guess = best == null ? "" : best.getKey();
int answered = ballots.size();
/**
* The evidence-as-ballots quorum counts one vote per authenticated member,
* not one per name an extraction declares (the shape of QA4 A4-7). Written
* fails-first: before the fix a single rogue extractor writing a wrong value
* under two invented names reached the quorum of two alone and the wrong
* value was approved; now it counts once and the careful reader's dissent
* keeps the field out of the filing.
*/@Test@Timeout(120)
voidaRogueExtractorWritingUnderTwoNamesCountsOnce() throwsException {
int seedPort = freePort();
Peer coordinator = IntakeFleet.startPeer("coordinator", seedPort, 0);
Peer careful = IntakeFleet.startPeer("extract-careful", freePort(), seedPort);
Peer rogue = IntakeFleet.startPeer("extract-rogue", freePort(), seedPort);
Peer adjudicator = IntakeFleet.startPeer("adjudicator", freePort(), seedPort);
List<Peer> fleet = List.of(coordinator, careful, rogue, adjudicator);
List<AutoCloseable> agents = newArrayList<>();
try {
agents.add(IntakeFleet.runExtractor(careful, 90));
agents.add(IntakeFleet.runAdjudicator(adjudicator, 2, 55, 3));
Thread.sleep(1500);
coordinator.intake().write(IntakeFleet.scan("scan-r", "TP-44444", "$1,000", 30),
Lease.of(Duration.ofHours(2)));
// The rogue "reads" the amount wrong, twice, as two different extractors.for (String alias : List.of("ghost-1", "ghost-2")) {
rogue.intake().write(newIntakeFleet.Extraction("scan-r", "amount", "$9,000",
alias, 95), Lease.of(Duration.ofHours(1)));
}
Thread.sleep(4000); // the adjudicator has seen every extraction there will beList<ApprovedField> approved = adjudicator.intake()
.readAll(Template.of(ApprovedField.class), 100);
assertThat(approved).filteredOn(f -> f.field().equals("amount"))
.as("two names from one member are one vote; no quorum for the wrong value")
.isEmpty();
// The taxpayer id, read correctly by the careful extractor alone, is not// approved either: one honest vote is below the quorum of two.assertThat(approved).isEmpty();
} finally {
agents.forEach(agent -> {
try {
agent.close();
} catch (Exception ignored) {
// best effort
}
});
fleet.forEach(Peer::close);
}
}
✓ sliced from the app and its test
firstPerMember keeps the first extraction of each issuing peer, so a member that writes the same field twice, or under two invented names, counts once. The adjudicator and the auditor share this helper, so the auditor lists the same ballots the adjudicator counted. The test writes exactly that: a peer with no agent writes a wrong amount under "ghost-1" and "ghost-2", and the adjudicator must not approve it. Before the fix a single rogue member reached the quorum of two alone (finding QA4 A4-7); the careful extractor's dissent now keeps the field open.
The tally, step by step. Each cue reruns the whole decision from the replica, so a decision rests on every extraction that has arrived by then. The review clock reruns it once per open field after the wait. The decided set makes a field's outcome final in this process: the first answer, an approval or a review, is the only one written.
What to watch for
The unit of a vote is the peer. Two agents on one peer would count once, the granularity at which the vote capability counts, so the demo puts each extractor on a peer of its own.
The tally is hand-written in ballots and Adjudicator.settle. The comment on the helper names the rule it applies: one vote per issuing peer, the way the vote capability counts.
An honest member writes one value per field, so its ballot is unambiguous. A member that writes two different values for one field is a rogue case: readAllIssued lists entries in the order of the replica's entry map, which is not sorted, so which of the two values is first can differ between replicas.
The decided set is in memory. It makes the first outcome for a field final in that process, and it does not survive a restart of the adjudicator.
aspace://guide/intake-fleet/gate · chapter 9
The confidence gate and the human review branch
A quorum alone would not be enough here. Two readers who agree are two ballots for the same value, and nothing in the count says the value is right. The adjudicator therefore requires 2 agreeing readers and a mean confidence of at least 55 across them. The three demo scans show each case.
The gate sits in the gap. In this simulation a misread never equals the true value, so agreeing readers are all legible or all illegible. The first group averages at least 60 and passes, the second averages at most 45 and fails, and the threshold of 55 needs no tuning between them. Scores from a real reader could fall in between, and the threshold would then decide.
On scan-1040-c the careful and the fast extractor misread the same character: Math.abs(worker.hashCode()) % chars.length gives position 0 for both labels in the eight-character values, so both flip the first character and write 0P-33333 for the taxpayer id. That is 2 votes for a wrong value, and the quorum of 2 is met. Their confidences are 43 and 33, a mean of 38, below 55, so the field is not approved. The gate is the only thing between two coinciding errors and a filing.
The decision_□×
if (votes >= quorum && meanConfidence >= confidenceThreshold) {
if (decided.add(key)) {
intake.write(newApprovedField(scanId, field, guess,
votes, meanConfidence, intake.writer().orElseThrow().encoded()),
Lease.of(Duration.ofHours(6)));
}
} elseif (answered >= expectedExtractors || waitOver) {
// Every extractor has weighed in and none reached quorum agreement// (or agreement is too weak), or the wait for the rest is over: a// human decides.if (decided.add(key)) {
String reason = votes + "/" + answered + " agreed, confidence " + meanConfidence;
if (answered < expectedExtractors) {
reason += ", " + answered + " of " + expectedExtractors
+ " extractors answered within " + seconds(reviewWait);
}
intake.write(newReviewItem(scanId, field, reason, guess, meanConfidence),
Lease.of(Duration.ofHours(6)));
}
}
/** A field that could not be agreed: routed to a human review queue. */publicrecordReviewItem(String scanId, String field, String reason,
String bestGuess, int confidence) {
}
✓ sliced from IntakeFleet.java
Approved, or a person decides. A field leaves the open state once, and the adjudicator remembers it in memory. A review item holds the fleet's best guess, how many peers agreed and the mean confidence, so a person sees what the fleet would have filed. The app writes the queue and stops there: nothing consumes a ReviewItem, and it lapses after its lease.
A review item is the human branch. It records the fleet's best guess, how many readers agreed and the mean confidence, in a leased entry. The app stops there: the demo prints the items, and a review user interface would read the ReviewItem entries. The README lists that as the next piece.
What to watch for
The review branch fires when the number of peers heard from reaches expectedExtractors, here 3, or when the review wait of 10 s has passed. With fewer extractors alive a field that misses the quorum reaches a person after the wait (the next chapter shows the recorded runs).
An illegible read in this simulation is never equal to the true value, so agreeing readers are all legible or all not. Real readers produce mixed groups, and then the threshold does real work between the two scores.
The auditor files a scan only when every field is approved. A scan with one approved field and one in review waits for a person and produces no partial filing.
Every record in the chain is signed by an agent key, and each agent key is certified by the key of the peer that hosts it. The app turns that on in startPeer and in the AgentSpaces facade, and the rest follows from the library: entries read back as AGENT_ATTESTED, and readAllIssued returns each entry with its issuer.
From a peer key to a signed entry. The peer signs a certificate for each agent's own key, and the agent signs its records. A receiver that can chain a record to a peer key reports it AGENT_ATTESTED, which backs the agent name in the issuer id with the agent's own key. Under PEER_ASSERTED that name would be the peer's word. The certificate renews at half its lifetime and the old ones stay valid for what they signed.
Turning on agent keys_□×
// The provenance chain is only as good as its attribution: every agent// here signs with a key of its own that its peer certifies (SPEC §4.2), so// extractions, approvals, and filings read as AGENT_ATTESTED everywhere.ReplicatedSpace intake = ReplicatedSpace.builder(runtime, "intake", identity, name)
.writer(identity.renewingSubordinate(name, java.time.Duration.ofHours(24), java.time.InstantSource.system()))
.settleWindow(Duration.ofMillis(150))
// The default block store is in memory (512 MiB quota): a scan's block// lives as long as the process and the quota allow, whatever the// entry's lease says.
.blocks(newBlockExchange(runtime, CborCodec.defaultCodec()))
.build();
// The agents are annotated POJOs bound through the facade; with the// subordinate identity factory each one signs with a certified key of its// own and its @SpaceRef is a per-agent view of the one replica. The last// argument, the discovery service, is null on purpose: this fleet publishes// no agent cards, because its agents are cued by entry type and never look// each other up. Pass a DiscoveryService here to publish cards.AgentSpaces spaces = newAgentSpaces(identity, InstantSource.system(),
agentName -> identity.renewingSubordinate(agentName, java.time.Duration.ofHours(24), java.time.InstantSource.system()));
AgentSpaces.GroupContext group = spaces.register("intake-fleet", runtime.id(), runtime, null);
group.space(INTAKE, intake);
@SpaceNotify(space = INTAKE, lease = "1d")
publicvoidonApproval(ApprovedField cue) {
String scanId = cue.scanId();
if (filed.contains(scanId)) {
return;
}
// An approval counts only when the adjudicator issued it, and issued it// under its own certified key: the issuer is read from the entry's// signature (readAllIssued), never from decidedBy, a field the entry// declares about itself. Any other member's ApprovedField is ignored,// including the one that cued this method.Map<String, ApprovedField> approved = newTreeMap<>();
for (Space.Issued<ApprovedField> a : intake.readAllIssued(
Template.of(ApprovedField.class).where("scanId", eq(scanId)), 100)) {
if (a.issuer().equals(adjudicator)
&& a.attestation() == Space.Attestation.AGENT_ATTESTED) {
approved.putIfAbsent(a.entry().field(), a.entry());
}
}
if (!approved.keySet().containsAll(FIELDS)) {
return; // not every field is approved yet
}
Map<String, String> fields = newTreeMap<>();
approved.values().forEach(f -> fields.put(f.field(), f.value()));
// The contributing extractors for the provenance record: the// authenticated issuers whose extraction agrees with a filed value, not// the names they declared, and not the dissenters. The approval says how// many extractors agreed (votes); the extractions travel separately from// the approval, so wait, up to READ_WAIT, until this replica shows that// many for every field, and then list the agreeing issuers it sees.Set<String> extractors = newTreeSet<>();
long giveUp = System.nanoTime() + READ_WAIT.toNanos();
while (true) {
extractors.clear();
boolean complete = true;
for (ApprovedField field : approved.values()) {
int agreeing = 0;
for (Space.Issued<Extraction> e : ballots(intake, scanId, field.field()).values()) {
if (e.entry().value().equals(field.value())) {
extractors.add(e.issuer().encoded());
agreeing++;
}
}
complete &= agreeing >= field.votes();
}
if (complete || System.nanoTime() >= giveUp) {
break;
}
if (!pause(100)) {
return; // the binding closed while the auditor waited
}
}
// A scan's image is over the inline limit, so the entry travels// content-addressed; the timed read waits for the block if it has not// landed here yet, rather than degrading the provenance to "unknown".// The hash is of the image alone: the Scan entry's payloadRef names the// encoded record, a different block, so the filing carries the one hash// anyone holding the scan can recompute.String contentHash = intake.read(
Template.of(Scan.class).where("scanId", eq(scanId)),
READ_WAIT)
.map(s -> BlockExchange.cidOf(s.image()))
.orElse("unknown");
if (filed.add(scanId)) {
intake.write(newFiling(scanId, fields, contentHash,
newArrayList<>(extractors), System.currentTimeMillis()),
Lease.of(Duration.ofDays(7)));
}
}
/**
* The compliance filing, with the provenance chain that backs it:
* {@code scanContentHash} is the CID of the scan's image alone (not the
* {@code payloadRef} of the Scan entry, which names the encoded record), and
* {@code contributingExtractors} lists the authenticated agent ids of the
* extractors whose extraction agreed with a filed value.
*/publicrecordFiling(String scanId, Map<String, String> fields, String scanContentHash,
List<String> contributingExtractors, long filedAtMillis) {
}
✓ sliced from IntakeFleet.java
Link
Signed by
Bound to the rest by
What the record does not carry
Scan
<peerId>/coordinator, the space's writer key
its content: the block hashes to the entry's payloadRef, and the image hash feeds the filing
the hash of the bare image
Extraction
<peerId>/extractor, one key per extractor peer
scanId, plus the issuer as the voter
a pointer to the Scan entry
ApprovedField
<peerId>/adjudicator; the auditor files only from this issuer
scanId and field; decidedBy repeats the signer, and the auditor ignores it
the ids of the extractions it counted
Filing
<peerId>/auditor
scanId, and the image hash recomputed from the bytes it read
the ids of the approvals it used
What a regulator can check, and what takes more work
A regulator who can read a replica checks each link independently. The signature and the certificate chain prove which key wrote an entry. The image hash proves that the scan a copy shows is the one the filing names. A recount of the extractions, one per issuing peer, confirms that the approved value met the quorum and the threshold. An approval states the count the adjudicator saw when it decided, and a later extraction can raise a recount above it.
The links are joined by scanId and field, and the one cryptographic anchor is the image hash. The records hold no entry-id back references, so a regulator pairs a filing with its approvals and extractions by value and by scan.
contributingExtractors lists the issuer of each extraction that agreed with a filed value, and leaves the dissenters out. The recorded demo lists two extractors for scan-1040-b, where the cheap one misread, and the approvals and extractions on file say who agreed on what. The auditor waits until its own replica shows at least the number of agreeing extractions that each approval records in votes, because the extractions and the approval travel as separate entries.
The auditor reads the approvals with readAllIssued and files only from those whose issuer is the adjudicator's agent id and whose attestation is AGENT_ATTESTED. Any other member of this OPEN group can still write an ApprovedField, and the auditor ignores it. The adjudicator's id is a bind-time argument, so a deployment that moves the adjudicator to another peer must pass the new id to the auditor.
Entries expire. A regulator's copy has to be taken inside the leases, or the evidence is the filing and the hash alone.
aspace://guide/intake-fleet/swarm · chapter 11
Content addressing and the 0.5.0 content swarm
AgentSpaces 0.5.0 adds the content swarm, aspace:cap/content-swarm, in the agentspaces-content module. It moves artifacts of any size between the members that hold them. This app does not use it, and this chapter states how its names relate to the hash the filing carries. Everything below is read from the library sources.
Names are functions of bytes. All three names depend only on bytes, so the same bytes carry the same name on every member. They name different bytes and use different rules: the prefix tells them apart (z for a block CID, b for a content root), and a swarm root needs the piece size and the piece table to recompute. The filing uses the first, which a regulator can compute from the scan alone.
Name
Rule
Prefix
Defined in
The filing's hash
sha-256 of the bytes, base58btc
z
BlockExchange.cidOf
A block reference
the same rule over the encoded record the space stores
z
ReplicatedSpace.prepareWrite
A swarm root
CIDv1 (raw codec, sha2-256), base32, over the concatenated sha-256 of the pieces
b
ContentRoots.rootOf
Two rules_□×
/**
* Computes the root of a piece table.
*
* @param table the piece hashes, 32 bytes each
* @return the CIDv1 string, beginning {@code b}
*/publicstaticStringrootOf(byte[] table) {
Objects.requireNonNull(table, "table");
if (table.length % Manifest.HASH_BYTES != 0) {
thrownewIllegalArgumentException("table of " + table.length + " bytes is not a multiple of 32");
}
byte[] digest = Digests.sha256(table);
byte[] cid = new byte[CID_PREFIX.length + digest.length];
System.arraycopy(CID_PREFIX, 0, cid, 0, CID_PREFIX.length);
System.arraycopy(digest, 0, cid, CID_PREFIX.length, digest.length);
returnMultibase.base32(cid);
}
A root is a CIDv1 over the hashes of the pieces, so a swarm root is not the sha-256 of the bytes. The default piece size is 1 MiB. The 80 KiB scan is one piece, so its root is the sha-256 of its one piece hash, wrapped as a CIDv1: bafkreieb7tszt32umo6z2loqnlm3w7wqarwtyzql6vn7gw4frr53ofoxqq for scan-1040-a, against zCYjUBUAoe4Ak6VGxHW8iv1gtLcNs3ccQb6VN94np11TB for the filing hash. The two share an input and differ as strings.
Both names are functions of bytes, so the same bytes have the same name on every member under either rule. A hash of the bare image needs only the image to recompute. A root needs the piece size and the piece table as well.
The leading character tells them apart: ContentRoots.isRoot is true for a reference that begins with b, a root, and a z begins a block reference.
A space with the swarm attached escalates a payload above its threshold (4 MiB by default) to an artifact and records the root in payloadRef. Between the 64 KiB inline limit and the threshold the block path of the previous chapters still applies, so this app's 80 KiB scans would stay on it with the default threshold.
What the swarm publishes for an escalated entry is the encoded payload (application/cbor), so that root would name the encoded record, as the block reference does here. It would not name the bare image. The filing hash is computed from the image the auditor decodes, so it does not depend on which path carried the scan.
An app that wants the artifact root of the image itself in its filing publishes the image with Content.publish and reads root() from the returned manifest, as the release notes show. The app does not do this, and this guide leaves its design as it is.
The developer guide's Large data chapter covers publishing, fetching, escalation and the stores, and the repository's example 29 runs a swarm with a killed seeder.
aspace://guide/intake-fleet/death · chapter 12
When something dies
The app's failure story is a missing ballot. Entries replicate to every peer, so what a dead extractor already wrote stays in the others' replicas until its lease lapses, and what it has not written yet is absent. The adjudicator counts the ballots it has, and a field it cannot settle waits for the missing ones for at most 10 s, the review wait, before it goes to a person. Scratch drivers, which are not part of the app, started the demo's six peers through IntakeFleet.startPeer, bound the same agents, closed the cheap extractor's binding and peer before the scans arrived, wrote the three demo scans and polled the counts every second. Recorded 2026-11-04:
One extractor down. Losing a reader costs a ballot, and the two live readers still reach the quorum on any scan they read alike. A scan they cannot settle waits for the third reader. With three expected and two alive the review rule fires when the review wait of 10 s has passed, and with two expected it fires as soon as both have answered. With no extractor at all, the scan itself starts the clock and each field goes to review after the same wait.
Cheap extractor down, adjudicator expecting 3 (the demo's setting)_□×
+ 0.0s extract-cheap closed (binding and peer); adjudicator expects 3
+ 0.0s 3 scans written
+ 1.0s extractions=12 approved=4 in-review=0 filed=2
(nine more identical lines, +2.1s to +10.1s)
+11.1s extractions=12 approved=4 in-review=2 filed=2
(six more identical lines, +12.1s to +17.1s)
filed scan-1040-a extractors=2
filed scan-1040-b extractors=2
approved scan-1040-b/taxpayerId votes=2 confidence=70
approved scan-1040-a/amount votes=2 confidence=85
approved scan-1040-b/amount votes=2 confidence=70
approved scan-1040-a/taxpayerId votes=2 confidence=85
review scan-1040-c/taxpayerId guess '0P-33333' (2/2 agreed, confidence 38, 2 of 3 extractors answered within 10 s)
review scan-1040-c/amount guess '0903,010' (2/2 agreed, confidence 38, 2 of 3 extractors answered within 10 s)
With one extractor gone, scans a and b still file. The careful and the fast reader agree on them, the quorum of 2 is met at mean confidences 85 and 70, and each filing lists the 2 extractors that agreed. Scan c produces nothing at first: no approval, since the two live readers misread it alike at mean confidence 38, and no review item, since only two peers weighed in and the adjudicator expects 3. The poll at +10.1 s still shows no review item and the poll at +11.1 s shows both fields, with the reason "2/2 agreed, confidence 38, 2 of 3 extractors answered within 10 s": the review wait, counted from the moment the adjudicator first heard of the scan, ran out in between. Set to expect two, the same adjudicator routes both fields by the first poll, at +1.1 s, with the reason "2/2 agreed, confidence 38", because every expected extractor has answered and the wait does not come into play.
With no extractor bound, no Extraction ever reaches the adjudicator, so nothing would cue it if the Scan did not. The scan starts its review clock, and after the same 10 s both fields of every scan become review items with an empty best guess and the reason "0/0 agreed, confidence 0, 0 of 3 extractors answered within 10 s" (six review items at +11.1 s in the recording). In the last recording the fast extractor's peer closes after it wrote: all six extractions, its own two included, stay on the coordinator's replica and the filing stands, listing the extractors that agreed.
The rules that decide it_□×
} elseif (answered >= expectedExtractors || waitOver) {
// Every extractor has weighed in and none reached quorum agreement// (or agreement is too weak), or the wait for the rest is over: a// human decides.if (decided.add(key)) {
String reason = votes + "/" + answered + " agreed, confidence " + meanConfidence;
if (answered < expectedExtractors) {
reason += ", " + answered + " of " + expectedExtractors
+ " extractors answered within " + seconds(reviewWait);
}
intake.write(newReviewItem(scanId, field, reason, guess, meanConfidence),
Lease.of(Duration.ofHours(6)));
}
}
privatevoidstartClock(String scanId) {
clocks.computeIfAbsent(scanId, id -> Thread.ofVirtual().name("review-clock-" + id).start(() -> {
try {
Thread.sleep(reviewWait);
} catch (InterruptedException closed) {
return;
}
// The wait is over: whatever is still open goes to a person.try {
for (String field : FIELDS) {
settle(id, field, true);
}
} catch (RuntimeException e) {
System.getLogger(IntakeFleet.class.getName()).log(System.Logger.Level.WARNING,
"review clock for " + id + " failed", e);
}
}));
}
✓ sliced from IntakeFleet.java
The wait is the group's member TTL, 10 s, the same 10 s the auditor allows for a block to arrive. The number comes from the app's own timing: an extraction takes milliseconds, so an extractor that has not answered by then is down, and the membership view has dropped a dead one by the time the clock runs out. IntakeFleet.REVIEW_WAIT is a public constant, and runAdjudicator takes another wait for a caller that wants one; the nobody-reads test uses two seconds.
What to watch for
The expected count and the wait work together. The count lets a fleet whose extractors all answer decide at once; the wait catches the rest. An operator who scales the extractors up or down has to change the count, or a failing field waits the whole review wait even though everyone answered (count too high), or goes to review before the last reader has answered (count too low).
The wait is final for a field. An extractor that answers after the review item exists adds a ballot that nothing counts, because the field is in the decided set. The review item stands, and a person decides.
The review clocks and the dedupe sets live in the adjudicator's process. A restart forgets them, so a scan the new adjudicator never hears of again gets neither an approval nor a review item.
The other agents die more quietly. The auditor keeps its filed set in memory, so a restart forgets which scans it has already filed.
aspace://guide/intake-fleet/running · chapter 13
Running and testing it
The app needs JDK 21 and Maven, and its AgentSpaces 0.5.0 coordinates resolve from Maven Central. It needs no model key, and once Maven has downloaded the libraries it uses only the loopback interface.
cd agentspaces-example-apps/agentspaces-intake-fleet
mvn test # the 6 flow tests, over real TCP
./run-demo.sh # the demo: mvn -q compile exec:java
The demo writes three scans, waits until two filings and a review item exist, and prints them. Recorded on 2026-11-04 (the demo, Maven included, took about 4 s of wall time):
./run-demo.sh_□×
intake-fleet: unstructured documents to compliance, with a signed provenance chain
3 scans intake (content-addressed); watching the pipeline:
extractions=0 approved=0 in-review=0 filed=0
extractions=18 approved=4 in-review=2 filed=2
== filings (each a signed compliance record) ==
scan-1040-b {amount=$18,750, taxpayerId=TP-22222}
provenance: scan CID zUemxJ7YJw1v89w2vE…, extractors [z7eAvothVTsWdMWY7TAUeAEHSTDLSBUEjnkEZytw4ngrg/extractor, zG743Dp6MnWVWCYYHAzGWFLP3rCU7YVkLc2frCbP7e8wR/extractor]
scan-1040-a {amount=$4,200, taxpayerId=TP-11111}
provenance: scan CID zCYjUBUAoe4Ak6VGxH…, extractors [z6YeDrg1ND1CBHVKSJEVQ72uzBESvni9DgQxY97jeFQtU/extractor, z7eAvothVTsWdMWY7TAUeAEHSTDLSBUEjnkEZytw4ngrg/extractor, zG743Dp6MnWVWCYYHAzGWFLP3rCU7YVkLc2frCbP7e8wR/extractor]
== routed to human review ==
scan-1040-c/taxpayerId best-guess '0P-33333' (2/3 agreed, confidence 38)
scan-1040-c/amount best-guess '0903,010' (2/3 agreed, confidence 38)
Every filing traces to a content hash, signed extractions,
and a signed auditor decision: the work product is the audit trail.
✓ recorded 2026-11-04, AgentSpaces 0.5.0
The hash printed for scan-1040-a, zCYjUBUAoe4Ak6VGxH…, is the prefix of the hash this guide computed from the image in the content chapter, and the review reason reads "2/3 agreed, confidence 38" because the careful and fast readers agreed on a wrong value at a mean confidence of 38. The extractor ids in the provenance line are agent ids: the peer's id, a slash, and the agent name. The two filings differ in provenance: scan-1040-a lists three extractor ids and scan-1040-b lists two, because the cheap extractor misread scan-1040-b and the filing leaves it out.
What the tests assert
6 tests, 30.58 s in Surefire and 31.46 s for the whole Maven run (the last of three green runs, which all took about 30.6 s in Surefire), recorded 2026-11-04. Each has a 120 s timeout and uses free ports. The dead-extractor test waits out the full 10 s review wait; the nobody-reads test passes a 2 s wait to stay quick.
IntakeFleetTest_□×
@Test@Timeout(120)
voidtheFleetFilesLegibleScansAndReviewsIllegibleOnesWithProvenance() throwsException {
int seedPort = freePort();
Peer coordinator = IntakeFleet.startPeer("coordinator", seedPort, 0);
Peer careful = IntakeFleet.startPeer("extract-careful", freePort(), seedPort);
Peer fast = IntakeFleet.startPeer("extract-fast", freePort(), seedPort);
Peer cheap = IntakeFleet.startPeer("extract-cheap", freePort(), seedPort);
Peer adjudicator = IntakeFleet.startPeer("adjudicator", freePort(), seedPort);
Peer auditor = IntakeFleet.startPeer("auditor", freePort(), seedPort);
List<Peer> fleet = List.of(coordinator, careful, fast, cheap, adjudicator, auditor);
List<AutoCloseable> agents = newArrayList<>();
try {
agents.add(IntakeFleet.runExtractor(careful, 90));
agents.add(IntakeFleet.runExtractor(fast, 70));
agents.add(IntakeFleet.runExtractor(cheap, 40));
agents.add(IntakeFleet.runAdjudicator(adjudicator, 2, 55, 3));
agents.add(IntakeFleet.runAuditor(auditor, IntakeFleet.adjudicatorId(adjudicator)));
Thread.sleep(1500);
// Two legible scans (all/most extractors read them) and one that is// barely legible (only the careful extractor might get it), which// should fail quorum and route to review.
coordinator.intake().write(IntakeFleet.scan("scan-a", "TP-11111", "$4,200", 30),
Lease.of(Duration.ofHours(2)));
coordinator.intake().write(IntakeFleet.scan("scan-b", "TP-22222", "$18,750", 60),
Lease.of(Duration.ofHours(2)));
coordinator.intake().write(IntakeFleet.scan("scan-c", "TP-33333", "$903,010", 98),
Lease.of(Duration.ofHours(2)));
List<Filing> filings = awaitFilings(auditor, 2, Duration.ofSeconds(60));
assertThat(filings).extracting(Filing::scanId)
.contains("scan-a", "scan-b");
// The two legible scans filed with the correct field values.Filing a = filings.stream().filter(f -> f.scanId().equals("scan-a"))
.findFirst().orElseThrow();
assertThat(a.fields()).containsEntry("taxpayerId", "TP-11111")
.containsEntry("amount", "$4,200");
// The filing's provenance is the scan's real content hash.String expectedCid = BlockExchange.cidOf(
IntakeFleet.scan("scan-a", "TP-11111", "$4,200", 30).image());
assertThat(a.scanContentHash()).isEqualTo(expectedCid);
// The provenance lists the extractors that agreed with the filed values. All// three read scan-a, but the fleet files as soon as a quorum agrees, so at// least two of the three are on file when it does.List<String> allExtractors = List.of(careful, fast, cheap).stream()
.map(p -> p.node().identity().agent("extractor").encoded()).toList();
assertThat(a.contributingExtractors()).hasSizeGreaterThanOrEqualTo(2)
.isSubsetOf(allExtractors);
// The cheap extractor misread scan-b, so it dissented: only the other two are listed.Filing b = filings.stream().filter(f -> f.scanId().equals("scan-b"))
.findFirst().orElseThrow();
assertThat(b.contributingExtractors()).containsExactlyInAnyOrder(
careful.node().identity().agent("extractor").encoded(),
fast.node().identity().agent("extractor").encoded());
// The barely-legible scan reached the human review queue, not a filing.// The review entry replicates on its own schedule, so wait for it rather than// reading once right after the filings arrived.List<ReviewItem> reviews = List.of();
long reviewDeadline = System.nanoTime() + java.time.Duration.ofSeconds(30).toNanos();
while (System.nanoTime() < reviewDeadline) {
reviews = adjudicator.intake().readAll(Template.of(ReviewItem.class), 100);
if (reviews.stream().anyMatch(r -> "scan-c".equals(r.scanId()))) {
break;
}
Thread.sleep(100);
}
assertThat(reviews).extracting(ReviewItem::scanId).contains("scan-c");
// A fresh read of the auditor's replica, now that the review item exists, not the// list read before it: scan-c has no filing.assertThat(auditor.intake().readAll(Template.of(Filing.class), 100))
.extracting(Filing::scanId).doesNotContain("scan-c");
// Approvals carry the vote count and the deciding adjudicator's authenticated id.List<ApprovedField> approved = adjudicator.intake()
.readAll(Template.of(ApprovedField.class), 100);
assertThat(approved).allSatisfy(f -> {
assertThat(f.votes()).isGreaterThanOrEqualTo(2);
assertThat(f.decidedBy()).isEqualTo(adjudicator.node().identity().agent("adjudicator").encoded());
});
// Provenance names authenticated agents, and every link in the chain is// signed by its agent's own certified key (QA4 A4-7).// Each contributing extractor is an authenticated agent on a distinct peer.assertThat(a.contributingExtractors()).allSatisfy(id ->
assertThat(id).matches("z[1-9A-HJ-NP-Za-km-z]+/extractor"));
assertThat(a.contributingExtractors().stream().map(id -> id.split("/")[0]).distinct().count())
.isEqualTo(a.contributingExtractors().size());
// Every link, read fresh from the auditor's replica: the scans (3), the// extractions (3 extractors x 2 fields x 3 scans), the approvals (2 fields x// 2 scans), the review items (2 fields of scan-c) and the filings (2) are each// AGENT_ATTESTED under the local name of the agent that wrote them.assertEveryLinkAttested(auditor, Scan.class, "coordinator", 3);
assertEveryLinkAttested(auditor, Extraction.class, "extractor", 18);
assertEveryLinkAttested(auditor, ApprovedField.class, "adjudicator", 4);
assertEveryLinkAttested(auditor, ReviewItem.class, "adjudicator", 2);
assertEveryLinkAttested(auditor, Filing.class, "auditor", 2);
} finally {
agents.forEach(agent -> {
try {
agent.close();
} catch (Exception ignored) {
// best effort
}
});
fleet.forEach(Peer::close);
}
}
/**
* The evidence-as-ballots quorum counts one vote per authenticated member,
* not one per name an extraction declares (the shape of QA4 A4-7). Written
* fails-first: before the fix a single rogue extractor writing a wrong value
* under two invented names reached the quorum of two alone and the wrong
* value was approved; now it counts once and the careful reader's dissent
* keeps the field out of the filing.
*/@Test@Timeout(120)
voidaRogueExtractorWritingUnderTwoNamesCountsOnce() throwsException {
int seedPort = freePort();
Peer coordinator = IntakeFleet.startPeer("coordinator", seedPort, 0);
Peer careful = IntakeFleet.startPeer("extract-careful", freePort(), seedPort);
Peer rogue = IntakeFleet.startPeer("extract-rogue", freePort(), seedPort);
Peer adjudicator = IntakeFleet.startPeer("adjudicator", freePort(), seedPort);
List<Peer> fleet = List.of(coordinator, careful, rogue, adjudicator);
List<AutoCloseable> agents = newArrayList<>();
try {
agents.add(IntakeFleet.runExtractor(careful, 90));
agents.add(IntakeFleet.runAdjudicator(adjudicator, 2, 55, 3));
Thread.sleep(1500);
coordinator.intake().write(IntakeFleet.scan("scan-r", "TP-44444", "$1,000", 30),
Lease.of(Duration.ofHours(2)));
// The rogue "reads" the amount wrong, twice, as two different extractors.for (String alias : List.of("ghost-1", "ghost-2")) {
rogue.intake().write(newIntakeFleet.Extraction("scan-r", "amount", "$9,000",
alias, 95), Lease.of(Duration.ofHours(1)));
}
Thread.sleep(4000); // the adjudicator has seen every extraction there will beList<ApprovedField> approved = adjudicator.intake()
.readAll(Template.of(ApprovedField.class), 100);
assertThat(approved).filteredOn(f -> f.field().equals("amount"))
.as("two names from one member are one vote; no quorum for the wrong value")
.isEmpty();
// The taxpayer id, read correctly by the careful extractor alone, is not// approved either: one honest vote is below the quorum of two.assertThat(approved).isEmpty();
} finally {
agents.forEach(agent -> {
try {
agent.close();
} catch (Exception ignored) {
// best effort
}
});
fleet.forEach(Peer::close);
}
}
/**
* With one of the three expected extractors down, a scan that the two live readers
* cannot settle still reaches a person: not at once, since the adjudicator waits for
* the third reader, but after {@link IntakeFleet#REVIEW_WAIT}. Before this rule such
* a scan got neither an approval nor a review item, because the review branch fired
* only when all three extractors had answered. The cheap extractor's binding and peer
* close before the scans arrive, as in the guide's recorded dead-extractor run.
*/@Test@Timeout(120)
voidaScanWithAnExtractorDownStillEndsInHumanReviewAfterTheWait() throwsException {
try (Fleet fleet = newFleet()) {
Peer coordinator = fleet.peer("coordinator");
Peer careful = fleet.peer("extract-careful");
Peer fast = fleet.peer("extract-fast");
Peer cheap = fleet.peer("extract-cheap");
Peer adjudicator = fleet.peer("adjudicator");
Peer auditor = fleet.peer("auditor");
fleet.bound(IntakeFleet.runExtractor(careful, 90));
fleet.bound(IntakeFleet.runExtractor(fast, 70));
AutoCloseable cheapBinding = IntakeFleet.runExtractor(cheap, 40);
fleet.bound(IntakeFleet.runAdjudicator(adjudicator, 2, 55, 3));
fleet.bound(IntakeFleet.runAuditor(auditor, IntakeFleet.adjudicatorId(adjudicator)));
Thread.sleep(1500);
fleet.kill(cheap, cheapBinding);
long written = System.nanoTime();
coordinator.intake().write(IntakeFleet.scan("scan-a", "TP-11111", "$4,200", 30),
Lease.of(Duration.ofHours(2)));
coordinator.intake().write(IntakeFleet.scan("scan-b", "TP-22222", "$18,750", 60),
Lease.of(Duration.ofHours(2)));
coordinator.intake().write(IntakeFleet.scan("scan-c", "TP-33333", "$903,010", 98),
Lease.of(Duration.ofHours(2)));
// The two live readers agree on scan-a and scan-b, so those file without the third.List<Filing> filings = awaitFilings(auditor, 2, Duration.ofSeconds(60));
assertThat(filings).extracting(Filing::scanId).containsExactlyInAnyOrder("scan-a", "scan-b");
List<String> live = List.of(careful, fast).stream()
.map(p -> p.node().identity().agent("extractor").encoded()).toList();
assertThat(filings).allSatisfy(f ->
assertThat(f.contributingExtractors()).containsExactlyInAnyOrderElementsOf(live));
// The two live readers misread scan-c alike at a mean confidence of 36, below the// threshold of 55, and only two of three expected extractors have answered. The// adjudicator keeps waiting for the third until REVIEW_WAIT has passed.List<ReviewItem> reviews = awaitReviews(adjudicator, "scan-c",
IntakeFleet.REVIEW_WAIT.plusSeconds(30));
Duration waited = Duration.ofNanos(System.nanoTime() - written);
assertThat(reviews).extracting(ReviewItem::field)
.containsExactlyInAnyOrder("taxpayerId", "amount");
assertThat(waited).as("the review item waits for the third extractor")
.isGreaterThanOrEqualTo(IntakeFleet.REVIEW_WAIT);
assertThat(reviews).allSatisfy(r -> assertThat(r.reason())
.isEqualTo("2/2 agreed, confidence 36, 2 of 3 extractors answered within 10 s"));
// No approval and no filing for scan-c, read fresh.assertThat(auditor.intake().readAll(Template.of(ApprovedField.class), 100))
.extracting(ApprovedField::scanId).doesNotContain("scan-c");
assertThat(auditor.intake().readAll(Template.of(Filing.class), 100))
.extracting(Filing::scanId).doesNotContain("scan-c");
}
}
/**
* A scan that no extractor answers has no extraction to cue the adjudicator, so the
* scan itself starts the review clock: both fields reach a person with an empty guess.
* A short wait keeps the test quick.
*/@Test@Timeout(120)
voidaScanNobodyReadsStillEndsInHumanReview() throwsException {
try (Fleet fleet = newFleet()) {
Peer coordinator = fleet.peer("coordinator");
Peer adjudicator = fleet.peer("adjudicator");
fleet.bound(IntakeFleet.runAdjudicator(adjudicator, 2, 55, 3, Duration.ofSeconds(2)));
Thread.sleep(1500);
coordinator.intake().write(IntakeFleet.scan("scan-n", "TP-66666", "$600", 30),
Lease.of(Duration.ofHours(2)));
List<ReviewItem> reviews = awaitReviews(adjudicator, "scan-n", Duration.ofSeconds(30));
assertThat(reviews).extracting(ReviewItem::field)
.containsExactlyInAnyOrder("taxpayerId", "amount");
assertThat(reviews).allSatisfy(r -> {
assertThat(r.reason()).isEqualTo(
"0/0 agreed, confidence 0, 0 of 3 extractors answered within 2 s");
assertThat(r.bestGuess()).isEmpty();
});
}
}
/**
* The auditor files only from approvals the adjudicator issued. A forger on another
* peer writes approvals for the scan the adjudicator sent to review, with the values
* the readers agreed on and with {@code decidedBy} naming the adjudicator, so the
* evidence behind them is real. Before the check the auditor read approvals with
* {@code readAll}, filed scan-c on the strength of them and skipped the human.
*/@Test@Timeout(120)
voidtheAuditorFilesOnlyFromApprovalsTheAdjudicatorIssued() throwsException {
try (Fleet fleet = newFleet()) {
Peer coordinator = fleet.peer("coordinator");
Peer careful = fleet.peer("extract-careful");
Peer fast = fleet.peer("extract-fast");
Peer adjudicator = fleet.peer("adjudicator");
Peer auditor = fleet.peer("auditor");
Peer forger = fleet.peer("forger");
AgentId adjudicatorId = IntakeFleet.adjudicatorId(adjudicator);
fleet.bound(IntakeFleet.runExtractor(careful, 90));
fleet.bound(IntakeFleet.runExtractor(fast, 70));
fleet.bound(IntakeFleet.runAdjudicator(adjudicator, 2, 55, 2));
fleet.bound(IntakeFleet.runAuditor(auditor, adjudicatorId));
Thread.sleep(1500);
coordinator.intake().write(IntakeFleet.scan("scan-a", "TP-11111", "$4,200", 30),
Lease.of(Duration.ofHours(2)));
coordinator.intake().write(IntakeFleet.scan("scan-c", "TP-33333", "$903,010", 98),
Lease.of(Duration.ofHours(2)));
// The genuine adjudicator files scan-a and sends scan-c to a person.assertThat(awaitFilings(auditor, 1, Duration.ofSeconds(60)))
.extracting(Filing::scanId).containsExactly("scan-a");
List<ReviewItem> reviews = awaitReviews(adjudicator, "scan-c", Duration.ofSeconds(30));
assertThat(reviews).hasSize(2);
// The forger approves what the readers misread. The approvals are real entries on every// replica, but their issuer is the forger, so the auditor must not file from them.for (ReviewItem review : reviews) {
forger.intake().write(newApprovedField("scan-c", review.field(), review.bestGuess(),
2, 99, adjudicatorId.encoded()), Lease.of(Duration.ofHours(1)));
}
assertThat(awaitIssued(auditor, ApprovedField.class, 4, Duration.ofSeconds(30)))
.as("the forged approvals reached the auditor's replica")
.filteredOn(a -> a.issuer().localName().equals("forger")).hasSize(2);
Thread.sleep(4000); // the auditor has had every cue it will getassertThat(auditor.intake().readAll(Template.of(Filing.class), 100))
.extracting(Filing::scanId).containsExactly("scan-a");
}
}
/**
* The filing lists only the extractors that agreed with the filed values. A dissenter's
* wrong readings are on every replica before the scan arrives, so they are on file when
* the auditor writes the filing, and the filing still leaves the dissenter out. Before,
* it listed every issuer of an extraction on file for the scan.
*/@Test@Timeout(120)
voidaFilingListsOnlyTheExtractorsThatAgreed() throwsException {
try (Fleet fleet = newFleet()) {
Peer coordinator = fleet.peer("coordinator");
Peer careful = fleet.peer("extract-careful");
Peer fast = fleet.peer("extract-fast");
Peer dissenter = fleet.peer("extract-dissenter");
Peer adjudicator = fleet.peer("adjudicator");
Peer auditor = fleet.peer("auditor");
fleet.bound(IntakeFleet.runExtractor(careful, 90));
fleet.bound(IntakeFleet.runExtractor(fast, 70));
fleet.bound(IntakeFleet.runAdjudicator(adjudicator, 2, 55, 3));
fleet.bound(IntakeFleet.runAuditor(auditor, IntakeFleet.adjudicatorId(adjudicator)));
Thread.sleep(1500);
for (String field : IntakeFleet.FIELDS) {
dissenter.intake().write(newExtraction("scan-d", field, "not-the-value",
"extract-dissenter", 50), Lease.of(Duration.ofHours(1)));
}
assertThat(awaitIssued(auditor, Extraction.class, 2, Duration.ofSeconds(30)))
.as("the dissent is on the auditor's replica before the scan is written").hasSize(2);
coordinator.intake().write(IntakeFleet.scan("scan-d", "TP-77777", "$7,700", 30),
Lease.of(Duration.ofHours(2)));
List<Filing> filings = awaitFilings(auditor, 1, Duration.ofSeconds(60));
assertThat(filings).hasSize(1);
Filing filing = filings.get(0);
assertThat(filing.fields()).containsEntry("taxpayerId", "TP-77777")
.containsEntry("amount", "$7,700");
assertThat(filing.contributingExtractors()).containsExactlyInAnyOrder(
careful.node().identity().agent("extractor").encoded(),
fast.node().identity().agent("extractor").encoded());
assertThat(filing.contributingExtractors())
.doesNotContain(dissenter.node().identity().agent("extract-dissenter").encoded());
}
}
/** Asserts that every entry of a type on a peer's replica is attested to the named agent's own key. */privatestatic <T> voidassertEveryLinkAttested(Peer peer, Class<T> type, String agentName,
int atLeast) throwsInterruptedException {
assertThat(awaitIssued(peer, type, atLeast, Duration.ofSeconds(30)))
.as(type.getSimpleName())
.hasSizeGreaterThanOrEqualTo(atLeast)
.allSatisfy(issued -> {
assertThat(issued.attestation()).isEqualTo(Space.Attestation.AGENT_ATTESTED);
assertThat(issued.issuer().localName()).isEqualTo(agentName);
});
}
✓ sliced from IntakeFleetTest.java
theFleetFilesLegibleScansAndReviewsIllegibleOnesWithProvenance starts the six peers and binds three extractors (skills 90, 70, 40), the adjudicator (2, 55, 3) and the auditor, given the adjudicator's agent id. It writes scan-a, scan-b and scan-c, whose difficulties are 30, 60, 98. It waits up to 60 s for two filings and asserts that they cover scan-a and scan-b, that scan-a's fields are TP-11111 and $4,200, that its scanContentHash equals BlockExchange.cidOf of the regenerated image, that scan-a lists at least two of the three extractors, and that scan-b lists exactly the careful and the fast one, because the cheap extractor misread it.
It then waits up to 30 s for a ReviewItem for scan-c and asserts, on a fresh read of the auditor's replica, that no filing for scan-c exists; every ApprovedField on the adjudicator's replica has at least 2 votes and the adjudicator's agent id in decidedBy; each contributing extractor matches z.../extractor, with distinct peer parts; and, read fresh from the auditor's replica, every Scan, Extraction, ApprovedField, ReviewItem and Filing is AGENT_ATTESTED under the local name of the agent that wrote it.
aRogueExtractorWritingUnderTwoNamesCountsOnce runs the rogue scenario of the ballots chapter and asserts that no ApprovedField exists after four seconds, for the amount and for the taxpayer id alike.
aScanWithAnExtractorDownStillEndsInHumanReviewAfterTheWait closes the cheap extractor before the scans arrive. Scans a and b file with exactly the two live extractors listed. Scan c gets no review item until the review wait has passed (the test times the first sighting against the write), then one for each field with the reason "2/2 agreed, confidence 36, 2 of 3 extractors answered within 10 s", and it has neither an approval nor a filing. Its scan-c has difficulty 98, so the mean confidence is 36 where the demo's 95 gives 38.
aScanNobodyReadsStillEndsInHumanReview binds only the adjudicator, with a 2 s wait, writes one scan and asserts a review item per field with the reason "0/0 agreed, confidence 0, 0 of 3 extractors answered within 2 s" and an empty best guess: no extraction ever arrives, so only the scan cue can have started the clock.
theAuditorFilesOnlyFromApprovalsTheAdjudicatorIssued adds a forger peer. After the genuine adjudicator files scan-a and sends scan-c to review, the forger writes an ApprovedField for each field of scan-c, with the review items' own guesses as values and the adjudicator's id in decidedBy. The test waits until the forgeries reach the auditor's replica and four seconds more, then asserts that a fresh read shows a filing for scan-a only. Before the issuer check the auditor filed scan-c from them.
aFilingListsOnlyTheExtractorsThatAgreed has a dissenter peer write wrong extractions for both fields of scan-d, waits until they are on the auditor's replica, then writes the scan. The filing lists exactly the careful and the fast extractor and not the dissenter.
What the tests leave openThey do not assert scan-b's field values or the best guess of a review item. The recordings of the death chapter are scratch drivers: the dead-extractor and nobody-reads tests cover the first and the third, and no test covers an extractor whose peer closes after it has written. No test restarts the adjudicator or the auditor, whose dedupe sets and review clocks are in memory by design.
aspace://guide/intake-fleet/next · chapter 14
Where to go next
The README names three ways to take the app on: point the extractors at a real OCR or vision model behind the same Extraction record, add a review user interface that reads the ReviewItem queue, and add the fleet console, which is not a dependency of this app, and wire it at the intake space for an operator view. The stages are decoupled by the space, so each scales and fails independently.
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.