Skip to content

An Embargo's End Is an Update of the Embargo, Announced to Every Signatory

Context and Problem Statement

An embargo ends as Remove(EmbargoEvent)[origin=<case>], with what ended it in content (END_TIME_REACHED or EARLY) and why in a Vultron terminationCause. Remove says the embargo left the case, but it stays on the case, terminated. content is natural-language text in ActivityStreams 2.0, not a machine field. When the Case Owner ends an embargo early, it sends that Remove to the CASE_MANAGER, which records the Owner's message as the act, though the CASE_MANAGER is the one that changes the embargo.

After an embargo ends, the CASE_MANAGER also sends a teardown Announce(EmbargoEvent) to every active participant, so that everyone the embargo may have bound learns that it ended. Signatories the ledger does not reach, such as a removed participant, get a separate direct copy of the termination instead (ADR-0116).

How does an embargo's end go on the wire, and how does every participant it may have bound learn of it?

Decision Drivers

  • A verb describes what was done: the embargo stays on the case, and its status changes.
  • An activity states what its sender did. An actor sends the decision it has the authority to make as the act itself, and the CASE_MANAGER admits or refuses it (ADR-0199).
  • Everyone an embargo may have bound is told, explicitly, that it ended.
  • A notice of a change announces the act that made it, so a receiver can tell the notice and the ledger entry are the same change.

Considered Options

  • An Update of the embargo, announced as an Announce of that Update
  • An Update of the embargo, announced as an Announce of the embargo
  • Remove(EmbargoEvent), as today

Decision Outcome

Chosen option: "An Update of the embargo, announced as an Announce of that Update", because the verb is true, the notice carries who ended the embargo and why, and a receiver matches the notice to its ledger entry by the act's id.

The end is an Update of the embargo

An embargo ends with Update(EmbargoEvent) setting its status to terminated and its termination: the cause kind, the act that caused it when known, and a human reason in summary (ADR-0202). End time reached is a cause like the others, so the separate END_TIME_REACHED/EARLY field goes. The CASE_MANAGER ledgers every such Update: its own, including an end-time termination, and the Case Owner's, once admitted. The termination's causing act is part of the embargo's stored state, so a reader of the embargo alone sees why it ended. The Update's inReplyTo is a link on the act: it may name that same act (ADR-0204).

When the CASE_MANAGER ends an embargo itself, at its end time or on a threat signal, it sends the Update as its own act. ADR-0122's two triggers for an end-time end, the CASE_MANAGER's lazy check and an outside request such as a Sentinel, stand, and both lead to this one Update. When the Case Owner ends an embargo early, the decision is the Owner's, so it sends the Update(EmbargoEvent) itself, to the CASE_MANAGER (ADR-0199). The CASE_MANAGER refuses it with a refusal notice, for instance when it names a threat signal, which only the CASE_MANAGER may name; otherwise it admits the Owner's Update as the ledger entry.

Remove(EmbargoEvent) is retired.

Every signatory is told, by an Announce of the Update

After the Update commits, the CASE_MANAGER sends Announce(<the Update>) to every active participant and to every signatory the ledger fan-out does not reach. That one notice replaces the separate direct copy to an unreached signatory. It is sent on every termination, the end time included, so a signatory the fan-out skips now hears of an expiry, which ADR-0116 left without a notice. The announced act carries the embargo and its termination and no other case content, as a notice to an unreached signatory requires (CM-31-031). A signatory whose stream is paused applies the end from the notice, and a later replay of the ledger entry carrying the same act changes nothing. The notice of a shorter revision follows the same rule: it announces the act that made the revision active.

Consequences

  • Good, because every message about an embargo's end is true of its sender, and a generic reader reads it as an event's status change.
  • Good, because one notice reaches everyone the embargo may have bound, and it carries the act's id, cause, author and request.
  • Bad, because the termination messages, their patterns, the teardown, the examples and the message reference all change; pre-1.0, the old forms are replaced outright.

Validation

  • A test ends an embargo at its end time and asserts one ledgered Update with status terminated and an end-time cause.
  • A test sends the Owner's Update(EmbargoEvent) ending the embargo early and asserts that the ledger entry carries the Owner's act, and that a threat-signal cause from the Owner is refused with nothing committed.
  • A test asserts that the Announce reaches every active participant and every signatory the fan-out skips, and that replaying the entry after applying the notice changes nothing.

Pros and Cons of the Options

An Update of the embargo, announced as an Announce of that Update

  • Good, because the notice is the change, with its id, cause and author.
  • Bad, because a receiver must read the embargo's new status from inside the announced act.

An Update of the embargo, announced as an Announce of the embargo

  • Good, because the notice carries the embargo as it now stands.
  • Bad, because the receiver must infer the end from the status, and needs a separate rule to match the notice to the ledger entry.

Remove(EmbargoEvent), as today

  • Good, because nothing changes.
  • Bad, because it says the embargo left the case, and its reason travels in a natural-language field.

More Information

The embargo's stored status and termination are ADR-0202. When an actor sends its decision as the act and when it offers the act instead is ADR-0199. Revision 2 makes the Case Owner's early end the Owner's own Update, not an Offer of it, after ADR-0199 revision 2 (issue #6487).

This record partially supersedes ADR-0116 in its embargo-change notices: the termination and shorter-revision messages, and the expiry that had no notice. It partially supersedes ADR-0122 in the termination message: Remove(EmbargoEvent), the END_TIME_REACHED/EARLY value in content, the terminationCause property, and the rule that an end-time termination has no cause. The other decisions of both records stand.