The Case Ledger and Status Histories Are Named Ordered Collections
Context and Problem Statement
The CASE_MANAGER publishes each ledger commit as Announce(CaseLedgerEntry).
That message carries no context, so the case is only inside the entry, and the ledger it extends has no name.
The sender of an act gets no positive acknowledgement: the entry that later commits it does not say that it answers that act.
A participant states its ledger position with a Read of a bare entry id, the only message whose object is a bare id.
A participant that holds nothing asks for a replay with a Reject that has no object.
A status goes out as Add(ParticipantStatus)[target=CaseParticipant] or Add(CaseStatus)[target=VulnerabilityCase], which name the record they are added to but not a history.
How do the ledger and the status histories go on the wire, so that a replica reads each message without inference?
Decision Drivers
Addsays something was added to a collection, and the collection is itstarget(VOC Add);Announceonly calls attention to an object.- An answer names what it answers (VOC
inReplyTo). - Every case activity carries
context= the case (notes/activitystreams-semantics.md). - Status records are not updated; a new status is added to a history, one message form per act (ADR-0137).
- One form per message, with no exceptions in the pattern rules.
Considered Options
- Named ordered collections, with an
Addto them that acknowledges the act it commits Announce(CaseLedgerEntry)withcontextadded, and a separate acknowledgement message- No change
Decision Outcome
Chosen option: "Named ordered collections, with an Add to them that acknowledges the act it commits", because each message then says what it does in AS2's own terms, and the acknowledgement costs no extra message.
The ledger is a named ordered collection
A case's ledger has the identity <case>/ledger, an OrderedCollection whose items are its entries in order, positioned by their log index.
This is identity only: it opens no fetch surface.
A commit is an Add that acknowledges the act
The CASE_MANAGER publishes each commit as Add(CaseLedgerEntry, target=<case>/ledger), with context the case and inReplyTo the committed act.
That Add is the positive acknowledgement of the act; there is no separate acknowledgement message, and a refusal stays the refusal notice.
The Add lists nothing in result.
An act that a commit causes names its cause in its own inReplyTo, so causation is read from effect to cause, with no ids made in advance and no waiting.
A position statement is a Read of the ledger
A participant states its position with Read(<case>/ledger) carrying ledgerPosition.
The empty ledger's position, log index −1 with the case's genesis hash, says the sender holds no entry; the CASE_MANAGER replays every entry after the stated position.
This replaces the Read of a bare entry id and the objectless Reject.
A gap in the chain is still answered with Reject(CaseLedgerEntry), which now names the Add in inReplyTo.
Status histories are named ordered collections
Each participant's statuses are <participant>/statuses, and the case's are <case>/statuses, both ordered collections with identity only.
A participant asserts a status with Add(ParticipantStatus, target=<participant>/statuses); the CASE_MANAGER records a case status with Add(CaseStatus, target=<case>/statuses).
The newest item is the current status.
Consequences
- Good, because a replica reads the case, the collection and the position from each message.
- Good, because the sender of an act learns that it committed, from the message that commits it.
- Good, because no pattern needs a bare object id or an objectless activity.
- Bad, because replication, position statements, replay and the status messages all change form, with their patterns, examples and message reference; pre-1.0, the old forms are replaced outright.
Validation
- A test asserts that a commit goes out as
Add(CaseLedgerEntry, target=<case>/ledger)withcontextthe case andinReplyTothe committed act. - A test asserts that
Read(<case>/ledger)at −1 replays the whole ledger, and that no pattern accepts a bare object id or an objectlessReject. - A test asserts both status
Addforms name their history intargetand the case incontext.
Pros and Cons of the Options
Named ordered collections, with an Add to them that acknowledges the act it commits
- Good, because every message uses AS2's own verbs and slots.
- Bad, because many message forms change at once.
Announce(CaseLedgerEntry) with context added, and a separate acknowledgement message
- Good, because replication keeps its form.
- Bad, because it adds a message per act, and
Announcestill does not say the entry was added to anything.
No change
- Good, because nothing changes.
- Bad, because the ledger keeps its unnamed collection, its bare-id
Readand its objectlessReject.
More Information
ADR-0107 and ADR-0124 name Announce(CaseLedgerEntry) as the replication message.
Their decisions, that an entry is a postmark on the received envelope and that a case is a projection of its ledger, stand; only the message's form changes.
ADR-0156 names Announce(CaseLedgerEntry) and Read(CaseLedgerEntry) in its position rules; its rule that case activities state the sender's position stands, now over these forms.
A fetchable ledger, GET <case>/ledger in pages, is separate work (#5089).
This record partially supersedes ADR-0137 in the target of a status Add, now the named history rather than the participant or the case; its rule that a record is attached by one message stands.
It partially supersedes ADR-0155 in the form of a position statement, now a Read of the ledger rather than of the last entry applied; its rule that a participant states its position and the CASE_MANAGER answers a lag stands.