aspace://guide/intake-fleet

Intake Fleet

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
The provenance chainOne run, end to endRun it
aspace://guide/intake-fleet/idea · chapter 1

The idea: a filing you can walk backward

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.

THE PROVENANCE CHAIN OF ONE FILING, FROM THE SCAN'S HASH TO THE PAPERWORKSIGNED BYA REGULATOR CAN CHECKScancoordinator, 2 h lease<peerId>/coordinator, the space's writer key,certified by the coordinator peerthe image travels as a block named by its hashthe block hashes to the entry's payloadRefsha-256 of the image is the filing's hashthe signature chains to the writer's peer keyExtraction x 63 extractors x 2 fields, 1 heach extractor's own key, <peerId>/extractor,certified by its peer; the declared name in therecord is a label nobody trustsone issuing peer is one ballot, however manynames it writes under; the value and theconfidence are the signed evidence itselfApprovedFieldadjudicator, 6 h lease<peerId>/adjudicator; decidedBy repeats it, butthe auditor reads the issuer from the signatureand files only from the adjudicator's idrecount the extractions, one per issuing peer:the value met votes >= 2 at mean >= 55; therecord states the count the adjudicator sawFilingauditor, 7 d lease<peerId>/auditor; the fields come from theapprovals, the extractor ids from the issuersthat agreed with them, the hash from the imagehash the scan you hold: it equals the filing'sscanContentHash; each contributing extractorissued an extraction equal to a filed valueeach extractor reads the Scan once its image block is localthe adjudicator tallies per field: scanId, field, one vote per memberthe auditor waits until the adjudicator has approved every field (taxpayerId, amount)sha-256 of the image, carried into the filing
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
Coordinatorno class; the peer coordinator on :7561none; it writes through the space handle-Scan, 2 h lease in the demo and the test
Extractor x 3Extractor on extract-careful (skill 90), extract-fast (70), extract-cheap (40)@SpaceNotify on extract(Scan), subscription lease 1hthe Scan, image includedtwo Extraction, 1 h lease
AdjudicatorAdjudicator on adjudicator (quorum 2, confidence 55, expects 3, waits 10 s)@SpaceNotify on onScan(Scan) and on onExtraction(Extraction), lease 1devery Extraction of the scan, with its issuer; each Scan, only to start the scan's review clockan ApprovedField or a ReviewItem, 6 h lease
AuditorAuditor on auditor, bound with the adjudicator's agent id@SpaceNotify on onApproval(ApprovedField), lease 1dthe approvals the adjudicator issued, the issuers of the extractions that agreed, and the scana Filing, 7 d lease
SIX PEERS IN ONE GROUP: ONE IDENTITY, ONE TCP LISTENER AND ONE intake REPLICA EACHcoordinator:7561 (the seed)no agentwrites the Scansspace handlewrite(scan)intake replicaBlockExchangeextract-careful:7562Extractorskill 90@SpaceNotifyextract()cue: Scanwrites Extractionintake replicaBlockExchangeextract-fast:7563Extractorskill 70@SpaceNotifyextract()cue: Scanwrites Extractionintake replicaBlockExchangeextract-cheap:7564Extractorskill 40@SpaceNotifyextract()cue: Scanwrites Extractionintake replicaBlockExchangeadjudicator:7565Adjudicatorquorum 2, conf 55@SpaceNotifyonScan()onExtraction()cues: Scan, Extractionwrites ApprovedFieldor ReviewItemintake replicaBlockExchangeauditor:7566Auditorfiles the record@SpaceNotifyonApproval()cue: ApprovedField(issuer: adjudicator)writes Filingintake replicaBlockExchange
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.
The three agent classes
@AgentSpec(name = "extractor", description = "Reads fields off a scanned document",
        goals = {"extract"})
public static final class Extractor {
    private final String label;
    private final int skill;
    @SpaceRef(INTAKE)
    Space intake;

    public Extractor(String label, int skill) {
        this.label = label;
        this.skill = skill;
    }

    @SpaceNotify(space = INTAKE, lease = "1h")
    public void extract(Scan doc) {
        for (String field : FIELDS) {
            boolean legible = skill >= doc.difficulty();
            String value = legible ? doc.truth().get(field)
                    : misread(doc.truth().get(field), label);
            int confidence = legible
                    ? Math.min(99, 60 + (skill - doc.difficulty()) / 2)
                    : Math.max(10, 45 - (doc.difficulty() - skill) / 2);
            intake.write(new Extraction(doc.scanId(), field, value, label, confidence),
                    Lease.of(Duration.ofHours(1)));
        }
    }
}
✓ sliced from IntakeFleet.java

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, foundingintake-fleet, literal intake-fleet-v1IntakeFleet.group()
Group idsha-256 of the founding text, base58btcGroupId.fromFounding
Membership policyOPENthe group advertisement
Default strategyLEASE_RACEthe group advertisement
Seed127.0.0.1:7561, the coordinatorstartPeer(name, port, seedPort)
TransportTcpTransport on 127.0.0.1, one port per peernode.listen
Securityevery frame carries the peer's signature (ChannelAuth.SIGNED); no TLSthe PeerNode default
Membershipmember TTL 10 s, ping timeout 2 s, 2 indirect probes, one probe per secondGroupMembership.Config
Gossipfanout 3, period 1 sGossipParameters.defaults()
Tick250 msnode.startTicking
Space settle window150 msReplicatedSpace.builder(...).settleWindow
Agent key certificates24 h, renewingrenewingSubordinate
HOW A PEER JOINS: group intake-fleet, founding literal "intake-fleet-v1"extract-carefula peer on :7562coordinator:7561, the seedthe other four:7563 to :75661 dial the seed127.0.0.1:7561 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 rumorsgroup id = sha-256 of the founding text; membership OPEN; default strategy LEASE_RACE; frames signed (ChannelAuth.SIGNED), no TLSSWIM membership: member TTL 10 s, ping timeout 2 s, 2 indirect probes, probe every 1 s; gossip fanout 3, period 1 s; peer tick 250 ms
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
 */
public static Peer startPeer(String name, int port, int seedPort) throws Exception {
    PeerIdentity identity = PeerIdentity.generate();
    PeerNode node = PeerNode.builder(identity).build();
    node.listen(new TcpTransport(), HOST + ":" + port);
    List<PeerAdvertisement.Endpoint> seeds = seedPort == 0 ? List.of()
            : List.of(new PeerAdvertisement.Endpoint("tcp", HOST + ":" + seedPort, 0));
    GroupRuntime runtime = node.joinGroup(group(),
            new GroupMembership.Config(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(new BlockExchange(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 = new AgentSpaces(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));
    return new Peer(name, node, runtime, intake, spaces, group);
}
✓ sliced from IntakeFleet.java

No cards, no names

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.

NO CARDS, NO NAMES: EACH AGENT SUBSCRIBES TO A TYPE IN THE intake SPACEScanfrom the coordinatorExtractor x 3@SpaceNotify, lease 1hExtraction6 per scanAdjudicator@SpaceNotify, lease 1dApprovedFieldper fieldAuditor@SpaceNotify, lease 1dFilingonce per scanReviewItema human's queuethe Scan also cues the adjudicator, which starts that scan's review clockregister("intake-fleet", runtime.id(), runtime, null): the discovery argument is null, so the binder publishes no AgentCardan agent reads a type it is cued by and writes the next type; the one name an agent holds is the adjudicator's id, which the auditor checks issuers against
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
ScanscanId, truth, difficulty, imagethe coordinator2 hthe extractors, and the adjudicator's review clock
ExtractionscanId, field, value, extractor, confidenceeach extractor, twice per scan1 hthe adjudicator
ApprovedFieldscanId, field, value, votes, confidence, decidedBythe adjudicator6 hthe auditor
ReviewItemscanId, field, reason, bestGuess, confidencethe adjudicator6 hnobody in the app
FilingscanId, fields, scanContentHash, contributingExtractors, filedAtMillisthe auditor7 dthe regulator
ONE ENTRY IN THE SPACE intakeExtractionscanId: "scan-1040-b"field: "taxpayerId"value: "TP-22222"extractor: "extract-fast"confidence: 65space strategyLEASE_RACElease1 hsigned by<peerId>/extractor, the agent's key
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)
 */
public record Scan(String scanId, Map<String, String> truth, int difficulty,
                   byte[] image) {
}
✓ 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.

HOW LONG EACH RECORD LIVES: THE LEASE ON THE WRITE (SOLID) AND ON THE SUBSCRIPTION (OUTLINE), LOG SCALEExtraction1 hScan2 hApprovedField6 hReviewItem6 hFiling7 dExtractor cue1 hAdjudicator cue1 dAuditor cue1 d1 h6 h1 d7 d
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 SCAN, END TO END: scan-1040-b, difficulty 60coordinator:7561extractors x 3careful, fast, cheapadjudicator:7565auditor:75661 write the Scanblock put, record gossiped2 fetch the block, read the imageWRITTEN fires once the block is local3 write 2 Extractions each6 entries, 1 h lease4 tally per fieldone vote per issuing peer5 write ApprovedField x 2votes, confidence, decidedBy6 all fields approved?by the adjudicator; hash the image7 write the Filinghash, agreeing extractors, 7 d leasethe cheap extractor misread both fields at confidence 35; the careful and fast readers agreed at 75 and 65,so each field is approved with 2 votes at mean confidence 70the same run for scan-1040-c ends at step 4 with a ReviewItem per field, and no Filing
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.

Writing the scans
coordinator.intake().write(scan("scan-1040-a", "TP-11111", "$4,200", 30),
        Lease.of(Duration.ofHours(2)));
coordinator.intake().write(scan("scan-1040-b", "TP-22222", "$18,750", 60),
        Lease.of(Duration.ofHours(2)));
coordinator.intake().write(scan("scan-1040-c", "TP-33333", "$903,010", 95),
        Lease.of(Duration.ofHours(2)));
✓ the coordinator writes three Scans

Steps 2 and 3: every extractor reads every scan

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.

The extractor
@SpaceNotify(space = INTAKE, lease = "1h")
public void extract(Scan doc) {
    for (String field : FIELDS) {
        boolean legible = skill >= doc.difficulty();
        String value = legible ? doc.truth().get(field)
                : misread(doc.truth().get(field), label);
        int confidence = legible
                ? Math.min(99, 60 + (skill - doc.difficulty()) / 2)
                : Math.max(10, 45 - (doc.difficulty() - skill) / 2);
        intake.write(new Extraction(doc.scanId(), field, value, label, confidence),
                Lease.of(Duration.ofHours(1)));
    }
}
✓ sliced from IntakeFleet.java

Steps 4 and 5: the adjudicator tallies each field

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")
public void onScan(Scan doc) {
    startClock(doc.scanId());
}

@SpaceNotify(space = INTAKE, lease = "1d")
public void onExtraction(Extraction cue) {
    startClock(cue.scanId());
    settle(cue.scanId(), cue.field(), false);
}
✓ 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")
public void onApproval(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 = new TreeMap<>();
    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 = new TreeMap<>();
    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 = new TreeSet<>();
    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(new Filing(scanId, fields, contentHash,
                new ArrayList<>(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.

A SCAN IS TOO BIG TO TRAVEL IN THE RECORD, SO THE RECORD CARRIES ITS HASHScanintakescanIdtruth: Mapdifficulty: intimage: byte[80 KiB]encodeCBOR payloada little over 80 KiBover 64 KiBinline limit exceededblocks.putblock storez + base58btc(sha-256)the CIDEntryRecordgossipedentryId, spaceId, typepayload: nullpayloadRef: z...issuer: <peerId>/coordinatorissued: hybrid-clock stamplease: 2 htags, sigrecords travel by gossipsmall, signed, leasedblocks travel by BLOCK_WANTto a peer that holds the CIDexactly one of payload or payloadRef is set;an inline payload may not exceed 64 KiB;the signature covers the reference, so thehash is signed along with the recordthe hash names the encoded record; thefiling's hash comes later, from the imagealone
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) {
    throw new IllegalArgumentException("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;
} else if (payload.length > EntryRecord.INLINE_PAYLOAD_LIMIT) {
    if (blocks == null) {
        throw new IllegalStateException("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;
}
✓ 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
}
✓ 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.

HOW AN EXTRACTOR GETS THE IMAGE: THE SPACE FETCHES IT AND THEN CUES extract()coordinatorthe writerextract-carefula reader1 write: put the block, sign the recordthe block stays in the writer's store2 gossip: the EntryRecord, payloadRef onlysmall and signed3 payload is null and the block is not localWRITTEN is deferred; a background fetch starts4 BLOCK_WANT(cid)the writer first, then 2 random members; first wait 800 ms5 BLOCK(cid, bytes)the reader hashes the bytes; a mismatch is dropped6 store the block, fire WRITTENextract(scan) runs on its own virtual thread
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.

EVERY EXTRACTOR READS EVERY SCAN, NONE TAKES ONE: THE taxpayerId READS OF THE DEMO'S THREE SCANSscan-1040-adifficulty 30scan-1040-bdifficulty 60scan-1040-cdifficulty 95extract-carefulskill 90TP-11111confidence 90, legibleTP-22222confidence 75, legible0P-33333confidence 43, misreadextract-fastskill 70TP-11111confidence 80, legibleTP-22222confidence 65, legible0P-33333confidence 33, misreadextract-cheapskill 40TP-11111confidence 65, legibleTP-22022confidence 35, misreadTP-33033confidence 18, misreadadjudicatorquorum 2, conf 55approved3 of 3 agree, mean 78approved2 of 3 agree, mean 70review2 of 3 agree, mean 38
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.

EVIDENCE AS BALLOTS: THE VOTER IS THE ISSUER, NEVER THE NAME THE ENTRY DECLARES (scan-r, field amount)ENTRIES IN intakeONE PER ISSUING PEER$1,000 conf 90declares "extract-careful"issuer<careful peer>/extractor$9,000 conf 95declares "ghost-1"issuer<rogue peer>/extract-rogue$9,000 conf 95declares "ghost-2"issuer<rogue peer>/extract-rogue$1,0001 vote$9,0001 vote, two namesno approval1 < quorum 2before the fix a single rogue reached the quorum of two alone under two invented names and the wrong value was approved (QA4 A4-7);now firstPerMember keeps one Extraction per issuer.peer(), so the two names count once and the careful reader's dissent keeps the field open
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.
 */
private static Map<String, Space.Issued<Extraction>> ballots(Space intake, String scanId, String field) {
    Map<String, Space.Issued<Extraction>> firstPerMember = new LinkedHashMap<>();
    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;
}
✓ 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.

ONE CUE TO THE ADJUDICATOR: ANY Extraction, ANY MEMBER'S, ANY SCANExtraction cue arrives, or the review clock firesdecided has scanId/field?decided once per (scan, field)yesreadAllIssued(Extraction where scanId), this fieldfirst Extraction per issuing peergroup by value, best = the largest groupvotes >= 2 and mean confidence >= 55 ?nowrite ApprovedField(votes, mean, decidedBy)yespeers heard from >= 3, or the wait is over ?nowrite ReviewItem(reason, bestGuess, mean)yesopen: a later cue, or the clock, tries againthe review clock starts at the first Scan or Extraction ofa scan; 10 s later it settles each field still open, withthe wait over, so no field can stay open for good
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 CONFIDENCE EACH SKILL WRITES, BY HOW HARD THE SCAN IS02550751000255075100scan difficultyconfidencethreshold 55scan ascan bscan ccareful 90fast 70cheap 40legible, skill >= difficulty: 60 + (skill - difficulty) / 2, at most 99illegible: 45 - (difficulty - skill) / 2, at least 10a legible read scores 60or more, an illegible one 45or less; 55 sits in the gapfilled dots: a true read; open dots:a misread, as in the demo's scans
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(new ApprovedField(scanId, field, guess,
                votes, meanConfidence, intake.writer().orElseThrow().encoded()),
                Lease.of(Duration.ofHours(6)));
    }
} else if (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(new ReviewItem(scanId, field, reason, guess, meanConfidence),
                Lease.of(Duration.ofHours(6)));
    }
}
✓ sliced from IntakeFleet.java
ONE (SCAN, FIELD) IN THE ADJUDICATOR: THREE STATES, TWO OF THEM FINALopenno outcome yetapprovedApprovedField, 6 hin reviewReviewItem, 6 hvotes >= 2, mean >= 553 peers heard, or 10 s passed,and no group reached the gatefewer peers and time leftAuditorfiles when every field is approveda humanno agent in the app reads itscan-1040-c, taxpayerId: 2 of 3 agree on '0P-33333' at mean confidence 38, below 55, so the field goes to review when the third reader answersor after 10 s if it never does. The same happens to amount; the adjudicator approves neither field, so no Filing exists for scan-1040-c
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.
aspace://guide/intake-fleet/provenance · chapter 10

The signed provenance: who signed each link

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.

WHERE AN AGENT'S SIGNATURE COMES FROMPeerIdentityEd25519 key; PeerId = its hashcertifiesAgentCertificateagent: <peerId>/extractoragent public key, issued, ttl 24 hthe peer's signature over the bodyagent keyrenewingSubordinate, own Ed25519signsEntryRecordsignature + the covering certificateeach agent has a key of its own:every bound agent gets its own key from theidentity factory passed to AgentSpaces, and thespace handle's writer gets one tooWHAT A RECEIVER CHECKS BEFORE IT REPORTS AGENT_ATTESTEDthe peer key hashes tothe agent's PeerIdPeerId.fromPublicKeythe peer's signatureverifies the certificatecanonical CBOR of the bodythe certificate coversthe record's issue stampjudged at signing timethe agent key verifiesthe record's signaturea peer-signed one is PEER_ASSERTED
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(new BlockExchange(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 = new AgentSpaces(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);
✓ 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 keyits content: the block hashes to the entry's payloadRef, and the image hash feeds the filingthe hash of the bare image
Extraction<peerId>/extractor, one key per extractor peerscanId, plus the issuer as the votera pointer to the Scan entry
ApprovedField<peerId>/adjudicator; the auditor files only from this issuerscanId and field; decidedBy repeats the signer, and the auditor ignores itthe ids of the extractions it counted
Filing<peerId>/auditorscanId, and the image hash recomputed from the bytes it readthe 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.

ONE IMAGE, THREE KINDS OF NAME: scan-1040-a, 80 KiBthe image81920 bytesthe filing's hashz + base58btc(sha-256(image))zCYjUBUAoe4Ak6VGxHW8iv1gtLcNs3ccQb6VN94np11TBBlockExchange.cidOf(image), in the Auditor: this is Filing.scanContentHashthe Scan entry's payloadRefz + base58btc(sha-256(encoded Scan record))zvxzoVqb2HoSAirsaVYopUybmFyWbJxgD2TyPrJpGn1cblocks.put(payload) in the space: 82007 bytes, the image plus scanId, truth, difficultya swarm root, which this app does not useCIDv1, raw, sha2-256 over the piece tablebafkreieb7tszt32umo6z2loqnlm3w7wqarwtyzql6vn7gw4frr53ofoxqqContentRoots.rootOf: one piece at the default 1 MiB, so sha-256(sha-256(image))
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 hashsha-256 of the bytes, base58btczBlockExchange.cidOf
A block referencethe same rule over the encoded record the space storeszReplicatedSpace.prepareWrite
A swarm rootCIDv1 (raw codec, sha2-256), base32, over the concatenated sha-256 of the piecesbContentRoots.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}
 */
public static String rootOf(byte[] table) {
    Objects.requireNonNull(table, "table");
    if (table.length % Manifest.HASH_BYTES != 0) {
        throw new IllegalArgumentException("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);
    return Multibase.base32(cid);
}
✓ AgentSpaces 0.5.0 library sources
  • 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:

THE CHEAP EXTRACTOR'S PEER CLOSES BEFORE THE SCANS ARRIVE (RECORDED RUNS, SECONDS AFTER THE CLOSE)expects 3, waits 10 s0 s4 s8 s12 s16 sextract-cheap closed, 3 scans written1.0 s: approved 4, filed 2, in review 011.1 s: in review 217.1 s: unchangedexpects 2, waits 10 s0 s4 s8 s12 s16 sextract-cheap closed, 3 scans written1.1 s: approved 4, filed 2, in review 217.1 s: unchangedno extractor, expects 30 s4 s8 s12 s16 sno extractor bound, 3 scans written1.0 s: no extractions, no outcome11.1 s: in review 617.1 s: unchangedWHAT EACH SCAN CAME TO WITH THE CHEAP EXTRACTOR DOWNscanthe two live readersadjudicator's countexpects 3, waits 10 sexpects 2scan-1040-acareful 90, fast 80they agree on the true value2 votes, mean 85at least 55approvedfiledapprovedfiledscan-1040-bcareful 75, fast 65they agree on the true value2 votes, mean 70at least 55approvedfiledapprovedfiledscan-1040-ccareful 43, fast 33they misread the same character2 votes, mean 38below 55ReviewItem by 11.1 s2 of 3 answeredReviewItem by 1.1 s2/2 agreed, conf 38
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)
✓ recorded 2026-11-04
The same, adjudicator expecting 2
+ 0.0s extract-cheap closed (binding and peer); adjudicator expects 2
+ 0.1s 3 scans written
+ 1.1s extractions=12 approved=4 in-review=2 filed=2
(sixteen more identical lines, +2.1s to +17.1s)
filed scan-1040-b extractors=2
filed scan-1040-a extractors=2
approved scan-1040-a/amount votes=2 confidence=85
approved scan-1040-a/taxpayerId votes=2 confidence=85
approved scan-1040-b/taxpayerId votes=2 confidence=70
approved scan-1040-b/amount votes=2 confidence=70
review scan-1040-c/taxpayerId guess '0P-33333' (2/2 agreed, confidence 38)
review scan-1040-c/amount guess '0903,010' (2/2 agreed, confidence 38)
✓ recorded 2026-11-04
No extractor bound at all, adjudicator expecting 3
+ 0.0s no extractor bound; adjudicator expects 3
+ 0.0s 3 scans written
+ 1.0s extractions=0 approved=0 in-review=0 filed=0
(nine more identical lines, +2.0s to +10.1s)
+11.1s extractions=0 approved=0 in-review=6 filed=0
(six more identical lines, +12.1s to +17.1s)
review scan-1040-c/amount guess '' (0/0 agreed, confidence 0, 0 of 3 extractors answered within 10 s)
review scan-1040-a/taxpayerId guess '' (0/0 agreed, confidence 0, 0 of 3 extractors answered within 10 s)
review scan-1040-b/taxpayerId guess '' (0/0 agreed, confidence 0, 0 of 3 extractors answered within 10 s)
review scan-1040-b/amount guess '' (0/0 agreed, confidence 0, 0 of 3 extractors answered within 10 s)
review scan-1040-a/amount guess '' (0/0 agreed, confidence 0, 0 of 3 extractors answered within 10 s)
review scan-1040-c/taxpayerId guess '' (0/0 agreed, confidence 0, 0 of 3 extractors answered within 10 s)
✓ recorded 2026-11-04
Another driver: the fast extractor's peer closes after it has written
+ 0.0s scan-1040-b written
+ 0.1s extractions=6 issuers=[extract-careful@extractor, extract-cheap@extractor, extract-fast@extractor] filed=0
+ 0.1s extract-fast closed (binding and peer)
+ 7.1s extractions=6 issuers=[extract-careful@extractor, extract-cheap@extractor, extract-fast@extractor] filed=1
filing scan-1040-b extractors=[extract-careful, extract-fast]
✓ recorded 2026-11-04

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
} else if (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(new ReviewItem(scanId, field, reason, guess, meanConfidence),
                Lease.of(Duration.ofHours(6)));
    }
}
✓ 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)
void theFleetFilesLegibleScansAndReviewsIllegibleOnesWithProvenance() throws Exception {
    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 = new ArrayList<>();
    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);
    }
}
✓ 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 FIVE LAYERS, AND WHAT INTAKE FLEET STANDS ONagents and the binderAgentSpaces facade, @AgentSpec, @SpaceNotify, @SpaceRef, an identity factoryLayer 4 capabilitiesvote, ordered log, aggregate, content, remote actionsLayer 3 spacesreplicated tuple spaces, leases, strategiesIntake Fleetone ReplicatedSpace, readAllIssued, leases, block-addressed entriesLayer 2 discoverycards, advertisements, locatorsLayer 1 peeringmembership, gossip, transportsIntake FleetPeerNode, TcpTransport, GroupMembership, BlockExchangeLayer 0 identityEd25519 keys, signed documents, groupsIntake FleetPeerIdentity, renewingSubordinate agent keys, signed frames
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.