Why a feed row identified by the object it is about is a row rather than an event, which of a row’s two clocks may reach the sort and what happens to the order when the wrong one does, why a per-stream sequence is a total order inside one stream and no order at all across the streams a feed merges, what a redaction may change about a stored row and what it may never move, which five things a surface discloses when it shows a filtered feed and why only the first of them carries a field, and what has to be true before a rebuild and a stored copy can be compared at all.
Generated from libs/oshun/workbench-kit/src/activity-feed.ts by
node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger:
S8.9. Do not edit by hand.
Summary#
src/activity-feed.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/activity-feed |
contract |
S8.9 |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| ACTIVITY_AUDIENCES | enumeration | What may be said about an event, to whom. |
| ACTIVITY_CAPABILITIES | enumeration | — |
| ACTIVITY_CLASSIFICATIONS | enumeration | The four protected classes the parent phase names, plus the two ordinary ones. |
| ACTIVITY_DISCLOSURE_FAULTS | enumeration | — |
| ACTIVITY_EVENT_FAULTS | enumeration | — |
| ACTIVITY_EVENT_SCHEMA_VERSION | constant | The schema this module writes. A reader that meets a higher number has met a row it cannot fully understand, and the honest response is to say so rather than to render the fields it recognises. |
| ACTIVITY_MUTATION_FAULTS | enumeration | — |
| ACTIVITY_SOURCE_KINDS | enumeration | Where the row came from, and whether that place can be read again. |
| ACTIVITY_TYPES | enumeration | What a feed row can be about. |
| ActivityAudience | type | — |
| ActivityCapability | type | — |
| ActivityClassification | type | — |
| ActivityDisclosureFault | type | — |
| activityDisclosureFaults | function | Compare what a surface showed against what the viewer was entitled to (S8.9.d). |
| ActivityEvent | interface | — |
| ActivityEventFault | type | — |
| activityEventFaults | function | Everything a single row must satisfy before anything else looks at it (S8.9.a). |
| activityEventId | function | The id of the row a source position produces (decision 2). |
| activityEventIdComponents | function | Take an id apart again. Null when it is not one of ours. |
| ActivityFeedFault | type | — |
| ActivityFinding | interface | — |
| ActivityMutationFault | type | — |
| ActivityOutcome | type | — |
| activityReplayParity | function | Compare a rebuild from an empty feed against the stored projection (S8.9.f). |
| ActivitySource | interface | — |
| ActivitySourceKind | type | — |
| ActivitySummary | interface | — |
| ActivityTarget | interface | — |
| ActivityType | type | — |
| ActivityViewer | interface | — |
| ActivityVisibility | interface | — |
| ACTOR_REFERENCE_KINDS | enumeration | How an actor may be named to an audience. |
| ActorReference | interface | — |
| ActorReferenceKind | type | — |
| ADMISSIBLE_PARAM_CLASSES | enumeration | Parameter classes a feed row may carry. |
| ADMISSIBLE_SOURCE_KINDS | enumeration | The two a feed row may be generated from. S8.9.b is this list. |
| AdmissibleParamClass | type | — |
| admitArrival | function | Decide what to do with a row that has just arrived (S8.9.e). |
| advanceWatermark | function | A watermark only ever moves forward. Going back re-opens settled pages. |
| ALL_ACTIVITY_FEED_FAULTS | constant | — |
| ARRIVAL_CLASSES | enumeration | — |
| ArrivalClass | type | — |
| ArrivalDecision | interface | — |
| assessActivityMutation | function | Decide whether a change to a stored row is one the policy permits (S8.9.b). |
| AUDIENCES_WITHOUT_PER_OBJECT_GRANT | enumeration | Audiences that read across objects by definition, so a per-object grant is not what authorizes them. |
| AUTHORED_PARAM_CLASSES | enumeration | Classes that carry a value somebody wrote, rather than a value the system derived. |
| CatalogueEntry | type | — |
| CLASSIFICATIONS_WITHOUT_AUTHORED_TITLES | enumeration | Classifications that exist to protect the content, so a title taken from that content may not appear in a row about it. |
| classifyArrival | function | — |
| compareFeedOrder | function | Newest first, and total (decision 3). |
| cursorFaults | function | Whether a cursor survives a round trip and carries the whole key (S8.9.e). |
| decodeFeedCursor | function | — |
| discloseActivity | function | What one viewer may be told about one row (S8.9.d). |
| Disclosure | type | — |
| EMPTY_FEED_PROJECTION | function | — |
| encodeFeedCursor | function | A cursor is the whole key (decision 4). |
| FEED_ORDER_FAULTS | enumeration | — |
| FeedOrderFault | type | — |
| feedOrderFaults | function | Whether a page came out in the one order the key defines (S8.9.e). |
| feedOrderKey | function | The key a row sits at. Derived, never stored, never a counter. |
| FeedOrderKey | interface | — |
| FeedProjection | interface | — |
| FeedRendering | interface | — |
| FeedWatermark | interface | — |
| FIELD_FOR_PARAM_CLASS | constant | Which field each admissible class must have come from. |
| FORBIDDEN_PARAM_CLASSES | enumeration | Classes that may never appear in a feed row, named so the check can say which one it found. |
| ForbiddenParamClass | type | — |
| MAX_AUDIENCE_FOR_CLASSIFICATION | constant | The widest audience each classification may reach. |
| MUTATION_EFFECTS | enumeration | — |
| MUTATION_REASONS | enumeration | The only three reasons a stored row may change, plus the one that is not a reason. |
| MutationEffect | type | — |
| MutationReason | type | — |
| MutationRequest | interface | — |
| MutationVerdict | interface | — |
| orderActivityFeed | function | — |
| orderDivergenceBetweenViewers | function | Whether two readers of the same rows were given them in the same order (S8.9.e ∩ S8.9.d). |
| ParityComparison | interface | — |
| PLURAL_CATEGORIES | enumeration | — |
| pluralCategoriesFor | function | Every category a locale can produce, so a catalogue entry can be checked for completeness. |
| pluralCategory | function | The plural category a count falls into for a locale. |
| PluralCategory | type | — |
| projectActivityFeed | function | Fold a log into a feed (S8.9.b and S8.9.f). |
| PROJECTION_REFUSALS | enumeration | — |
| ProjectionOutcome | interface | — |
| ProjectionRefusal | type | — |
| ProjectorOptions | interface | — |
| PseudonymAssignment | interface | — |
| pseudonymFaults | function | Whether the handles a feed hands out are stable in the one direction and unstable in the other (decision 9). |
| RefusedRecord | interface | — |
| renderActivitySummary | function | Turn a stored summary into a sentence in the reader's locale (S8.9.c). |
| RenderedSummary | interface | — |
| RenderOptions | interface | — |
| REPLAY_PARITY_FAULTS | enumeration | — |
| ReplayParityFault | type | — |
| RetentionPolicy | interface | — |
| SAFE_SUMMARY_FAULTS | enumeration | — |
| SafeSummaryFault | type | — |
| safeSummaryFaults | function | Everything a summary must satisfy before it is stored (S8.9.c). |
| SCOPED_REFERENCE_KINDS | enumeration | Reference kinds that carry a per-audience handle and therefore need a scope. |
| SOURCE_LINKAGE_FAULTS | enumeration | — |
| SourceLinkageFault | type | — |
| sourceLinkageFaults | function | Whether a set of rows was generated from something that can be read again (S8.9.b). |
| SourceRecord | interface | One row of the log, as the projector receives it. |
| SUMMARY_SOURCE_FIELDS | enumeration | Every field of the event a summary parameter is allowed to have come from. |
| SummaryCheckOptions | interface | — |
| summaryLeaks | function | The canary scan on its own, over every string a summary carries. |
| SummaryParam | interface | — |
| SummaryParamClass | type | — |
| summarySlots | function | The parameter names a template interpolates, in the order it first mentions them. |
| SummarySourceField | type | — |
| WITHHOLD_REASONS | enumeration | — |
| WithholdReason | type | — |
Shapes#
ACTIVITY_AUDIENCES#
What may be said about an event, to whom.
Values: actor, object-collaborators, tenant-members,
workbench-operators, auditors, public
ACTIVITY_CAPABILITIES#
Values: read-feed, read-actors, read-links, export
ACTIVITY_CLASSIFICATIONS#
The four protected classes the parent phase names, plus the two ordinary ones.
Values: public, internal, restricted, protected-source,
learner-record, biometric, unreleased-asset
ACTIVITY_DISCLOSURE_FAULTS#
Values: row-released-across-tenants, row-released-without-a-shared-audience,
row-released-without-an-object-grant,
row-released-without-the-read-feed-capability,
parameter-released-without-a-grant,
actor-named-without-the-read-actors-capability,
count-includes-withheld-rows, count-below-the-rows-shown,
actor-facet-names-an-actor-in-no-released-row,
target-title-from-a-withheld-row, link-to-an-object-the-viewer-cannot-open,
link-released-without-the-read-links-capability,
feed-exposes-a-dense-position, export-without-the-export-capability,
export-to-an-audience-the-viewer-does-not-hold,
export-carries-more-rows-than-were-released,
pseudonym-unstable-within-an-audience, pseudonym-shared-across-audiences,
pseudonym-collides-between-actors
ACTIVITY_EVENT_FAULTS#
Values: event-id-blank, event-id-not-derived-from-the-source-position,
event-id-is-the-target-id, event-version-not-a-positive-integer,
schema-version-not-a-positive-integer, schema-version-ahead-of-this-reader,
projector-version-not-a-positive-integer, unknown-activity-type,
unknown-outcome, target-object-blank, target-kind-blank,
target-revision-missing-on-a-mutating-outcome,
target-revision-present-on-a-nonmutating-outcome,
unknown-actor-reference-kind, actor-handle-on-an-anonymous-reference,
actor-handle-missing-on-a-scoped-reference,
actor-scope-missing-on-a-scoped-reference, actor-handle-is-an-address,
role-only-reference-without-a-role, occurred-at-unparseable,
recorded-at-unparseable, recorded-before-occurred,
occurred-at-is-not-the-source-time, causation-blank,
causation-is-the-events-own-id, causation-does-not-name-the-source-event,
correlation-blank, correlation-not-inherited-from-the-source,
visibility-tenant-blank, visibility-object-differs-from-the-target,
visibility-has-no-audience, unknown-audience, unknown-classification,
classification-exceeds-its-audience-ceiling,
property-scope-wider-than-the-event, property-scope-names-no-parameter,
linked-object-is-the-target, tombstone-carries-a-summary
ACTIVITY_EVENT_SCHEMA_VERSION#
The schema this module writes. A reader that meets a higher number has met a row it cannot fully understand, and the honest response is to say so rather than to render the fields it recognises.
Value: 1
ACTIVITY_MUTATION_FAULTS#
Values: row-changed-for-no-stated-reason, correction-edited-a-delivered-row,
redaction-without-a-named-authority,
order-written-against-a-different-policy-version,
redaction-by-an-authority-the-policy-does-not-name,
redaction-changed-the-order-key, redaction-widened-visibility,
redaction-did-not-move-the-event-version, redaction-added-content,
retention-removal-before-the-row-expired,
retention-removal-without-a-tombstone, tombstone-lost-the-order-key,
tombstone-still-visible-beyond-the-original-audience,
row-removed-for-a-reason-that-is-not-retention,
mutation-changed-the-event-id, mutation-changed-the-source
ACTIVITY_SOURCE_KINDS#
Where the row came from, and whether that place can be read again.
Values: audit-event, domain-event, current-state-read, ui-observation
ACTIVITY_TYPES#
What a feed row can be about.
Values: object-created, revision-published, stage-advanced,
stage-refused, gate-passed, gate-failed, waiver-granted,
signoff-recorded, signoff-invalidated, comment-posted,
suggestion-accepted, assignment-changed, access-granted, access-revoked,
object-withdrawn, object-deleted
ActivityAudience#
(typeof ACTIVITY_AUDIENCES)[number];
ActivityCapability#
(typeof ACTIVITY_CAPABILITIES)[number];
ActivityClassification#
(typeof ACTIVITY_CLASSIFICATIONS)[number];
ActivityDisclosureFault#
(typeof ACTIVITY_DISCLOSURE_FAULTS)[number];
activityDisclosureFaults#
Compare what a surface showed against what the viewer was entitled to (S8.9.d).
activityDisclosureFaults(rendering: FeedRendering, universe: readonly ActivityEvent[]): readonly ActivityFinding[]
ActivityEvent#
| Field | Type | Required | Notes |
|---|---|---|---|
eventId |
string |
required | — |
eventVersion |
number |
required | Bumped by a lawful redaction or retention action, never by a correction. |
schemaVersion |
number |
required | — |
projectorVersion |
number |
required | — |
type |
ActivityType | required | — |
target |
ActivityTarget | required | — |
actor |
ActorReference | required | — |
outcome |
ActivityOutcome | required | — |
occurredAt |
Instant | required | The source's time, copied. Never the projector's. |
recordedAt |
Instant | required | The projector's clock. Data, never a sort key. |
causationId |
string |
required | — |
correlationId |
string |
required | — |
source |
ActivitySource | required | — |
visibility |
ActivityVisibility | required | — |
summary |
ActivitySummary | required | — |
linkedObjectIds |
readonly string[] |
required | Objects this row points at besides its target. |
tombstone |
boolean |
required | True once retention or redaction has emptied it. Keeps the position. |
ActivityEventFault#
(typeof ACTIVITY_EVENT_FAULTS)[number];
activityEventFaults#
Everything a single row must satisfy before anything else looks at it (S8.9.a).
activityEventFaults(event: ActivityEvent): readonly ActivityFinding[]
activityEventId#
The id of the row a source position produces (decision 2).
activityEventId(streamId: string, streamSequence: number, type: ActivityType): string
activityEventIdComponents#
Take an id apart again. Null when it is not one of ours.
activityEventIdComponents(eventId: string): { readonly streamId: string; readonly streamSequence: number; readonly type: string } | null
ActivityFeedFault#
| ActivityEventFault
| SourceLinkageFault
| ActivityMutationFault
| SafeSummaryFault
| ActivityDisclosureFault
| FeedOrderFault
| ReplayParityFault
ActivityFinding#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
ActivityFeedFault | required | — |
subject |
string |
required | The event, parameter, viewer, cursor or projection the finding is about. |
detail |
string |
required | — |
ActivityMutationFault#
(typeof ACTIVITY_MUTATION_FAULTS)[number];
ActivityOutcome#
AuditOutcome;
activityReplayParity#
Compare a rebuild from an empty feed against the stored projection (S8.9.f).
activityReplayParity(rebuilt: FeedProjection, stored: FeedProjection, audiences: readonly ActivityAudience[] = ACTIVITY_AUDIENCES): ParityComparison
ActivitySource#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
ActivitySourceKind | required | — |
streamId |
string |
required | — |
streamSequence |
number |
required | Position within the stream. Gapless per stream; meaningless across them. |
sourceEventId |
string |
required | — |
sourceOccurredAt |
Instant | required | The authoritative time. The activity event copies it and adds nothing. |
sourceCorrelationId |
string |
required | Carried into the row so a trace survives the projection. |
appendOnly |
boolean |
required | — |
ActivitySourceKind#
(typeof ACTIVITY_SOURCE_KINDS)[number];
ActivitySummary#
| Field | Type | Required | Notes |
|---|---|---|---|
messageKey |
string |
required | A translation key. Never a sentence, never locale-suffixed. |
params |
readonly SummaryParam[] — SummaryParam |
required | — |
renderedIn |
string | null |
required | Non-null when somebody rendered before storing. |
ActivityTarget#
| Field | Type | Required | Notes |
|---|---|---|---|
objectId |
string |
required | — |
kind |
string |
required | — |
revision |
string | null |
required | Which version of the object the event is about. |
ActivityType#
(typeof ACTIVITY_TYPES)[number];
ActivityViewer#
| Field | Type | Required | Notes |
|---|---|---|---|
viewerId |
string |
required | — |
tenantId |
string |
required | — |
audiences |
readonly ActivityAudience[] — ActivityAudience |
required | — |
objectGrants |
readonly string[] |
required | — |
propertyGrants |
readonly string[] |
required | Summary parameter names this viewer may see when a scope narrows them. |
capabilities |
readonly ActivityCapability[] — ActivityCapability |
required | — |
ActivityVisibility#
| Field | Type | Required | Notes |
|---|---|---|---|
tenantId |
string |
required | — |
objectId |
string |
required | — |
audiences |
readonly ActivityAudience[] — ActivityAudience |
required | — |
propertyScopes |
Readonly<Record<string, ActivityAudience>> — ActivityAudience |
required | Summary parameters that are narrower than the event carrying them. |
classification |
ActivityClassification | required | — |
ACTOR_REFERENCE_KINDS#
How an actor may be named to an audience.
Values: named, pseudonymous, role-only, system, withheld
ActorReference#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
ActorReferenceKind | required | — |
handle |
string |
required | What the reader sees. Never the raw actor id, never an address. |
audienceScope |
string |
required | The audience the handle is stable within, and outside which it must differ. |
roleKey |
string | null |
required | — |
ActorReferenceKind#
(typeof ACTOR_REFERENCE_KINDS)[number];
ADMISSIBLE_PARAM_CLASSES#
Parameter classes a feed row may carry.
Values: count, pseudonym, role, object-title, revision-label,
stage-name, timestamp, duration, outcome-key, type-key
ADMISSIBLE_SOURCE_KINDS#
The two a feed row may be generated from. S8.9.b is this list.
Values: audit-event, domain-event
AdmissibleParamClass#
(typeof ADMISSIBLE_PARAM_CLASSES)[number];
admitArrival#
Decide what to do with a row that has just arrived (S8.9.e).
admitArrival(event: ActivityEvent, watermark: FeedWatermark): ArrivalDecision
advanceWatermark#
A watermark only ever moves forward. Going back re-opens settled pages.
advanceWatermark(watermark: FeedWatermark, toMillis: number): { readonly throughMillis: number; readonly findings: readonly ActivityFinding[] }
ALL_ACTIVITY_FEED_FAULTS#
ARRIVAL_CLASSES#
Values: in-order, out-of-order-within-grace, late-past-the-watermark,
replayed, second-row-for-one-source-position
ArrivalClass#
(typeof ARRIVAL_CLASSES)[number];
ArrivalDecision#
| Field | Type | Required | Notes |
|---|---|---|---|
arrival |
ArrivalClass | required | — |
admitted |
boolean |
required | — |
reissueFrom |
FeedOrderKey | null — FeedOrderKey |
required | The key a reader must be sent back to, or null. |
findings |
readonly ActivityFinding[] — ActivityFinding |
required | — |
assessActivityMutation#
Decide whether a change to a stored row is one the policy permits (S8.9.b).
assessActivityMutation(request: MutationRequest, policy: RetentionPolicy): MutationVerdict
AUDIENCES_WITHOUT_PER_OBJECT_GRANT#
Audiences that read across objects by definition, so a per-object grant is not what authorizes them.
Values: auditors
AUTHORED_PARAM_CLASSES#
Classes that carry a value somebody wrote, rather than a value the system derived.
Values: object-title
CatalogueEntry#
string | Readonly<Partial<Record<PluralCategory, string>>>;
CLASSIFICATIONS_WITHOUT_AUTHORED_TITLES#
Classifications that exist to protect the content, so a title taken from that content may not appear in a row about it.
Values: protected-source, learner-record, biometric, unreleased-asset
classifyArrival#
classifyArrival(event: ActivityEvent, watermark: FeedWatermark): ArrivalClass
compareFeedOrder#
Newest first, and total (decision 3).
compareFeedOrder(left: FeedOrderKey, right: FeedOrderKey): number
cursorFaults#
Whether a cursor survives a round trip and carries the whole key (S8.9.e).
cursorFaults(cursorText: string, key: FeedOrderKey): readonly ActivityFinding[]
decodeFeedCursor#
decodeFeedCursor(text: string): FeedOrderKey | null
discloseActivity#
What one viewer may be told about one row (S8.9.d).
discloseActivity(event: ActivityEvent, viewer: ActivityViewer): Disclosure
Disclosure#
| { readonly kind: 'withheld'; readonly reason: WithholdReason }
| { readonly kind: 'released'; readonly event: ActivityEvent; readonly withheldParams: readonly string[]; readonly withheldLinks: readonly string[]; readonly actorDowngraded: boolean; }
EMPTY_FEED_PROJECTION#
EMPTY_FEED_PROJECTION(projectorVersion: number, policyVersion: number): FeedProjection
encodeFeedCursor#
A cursor is the whole key (decision 4).
encodeFeedCursor(key: FeedOrderKey): string
FEED_ORDER_FAULTS#
Values: feed-not-in-time-order, tie-broken-by-arrival,
tie-broken-by-the-recording-clock, ordered-by-the-recording-clock,
order-key-not-total, duplicate-event-id-in-one-page,
cursor-not-round-trippable, cursor-carries-only-the-time,
order-differs-between-viewers, late-row-inserted-behind-an-issued-cursor,
replayed-source-produced-a-second-row,
duplicate-event-id-with-different-content, watermark-moved-backwards
FeedOrderFault#
(typeof FEED_ORDER_FAULTS)[number];
feedOrderFaults#
Whether a page came out in the one order the key defines (S8.9.e).
feedOrderFaults(observed: readonly ActivityEvent[]): readonly ActivityFinding[]
feedOrderKey#
The key a row sits at. Derived, never stored, never a counter.
feedOrderKey(event: ActivityEvent): FeedOrderKey
FeedOrderKey#
| Field | Type | Required | Notes |
|---|---|---|---|
occurredAtMillis |
number |
required | — |
streamId |
string |
required | — |
streamSequence |
number |
required | — |
eventId |
string |
required | — |
FeedProjection#
| Field | Type | Required | Notes |
|---|---|---|---|
events |
readonly ActivityEvent[] — ActivityEvent |
required | — |
projectorVersion |
number |
required | — |
policyVersion |
number |
required | — |
throughMillis |
number |
required | The authoritative time of the newest row folded. Zero for an empty feed. |
FeedRendering#
| Field | Type | Required | Notes |
|---|---|---|---|
viewer |
ActivityViewer | required | — |
rows |
readonly ActivityEvent[] — ActivityEvent |
required | The rows the surface actually put in front of the reader. |
totalCount |
number |
required | The total the surface displayed beside them. |
actorFacets |
readonly string[] |
required | — |
targetTitles |
readonly string[] |
required | — |
links |
readonly { readonly href: string; readonly objectId: string }[] |
required | — |
positions |
readonly number[] | null |
required | A dense index, when the surface exposes one. Null when it does not. |
exported |
{ readonly audience: ActivityAudience; readonly rows: number } | null — ActivityAudience |
required | — |
FeedWatermark#
| Field | Type | Required | Notes |
|---|---|---|---|
throughMillis |
number |
required | Rows at or before this instant are considered settled. |
graceMillis |
number |
required | How far behind the watermark a row may still land quietly. |
issuedCursor |
FeedOrderKey | null — FeedOrderKey |
required | The furthest cursor handed to a reader, or null if none has been. |
seen |
ReadonlyMap<string, ActivityEvent> — ActivityEvent |
required | — |
positions |
ReadonlyMap<string, string> |
required | stream#sequence#type positions already projected. |
FIELD_FOR_PARAM_CLASS#
Which field each admissible class must have come from.
FORBIDDEN_PARAM_CLASSES#
Classes that may never appear in a feed row, named so the check can say which one it found.
Values: raw-content, secret, protected-identity, learner-record,
biometric, unreleased-asset
ForbiddenParamClass#
(typeof FORBIDDEN_PARAM_CLASSES)[number];
MAX_AUDIENCE_FOR_CLASSIFICATION#
The widest audience each classification may reach.
MUTATION_EFFECTS#
Values: none, content-removed, content-changed, visibility-narrowed,
visibility-widened, order-key-changed, version-bumped, row-removed,
tombstoned
MUTATION_REASONS#
The only three reasons a stored row may change, plus the one that is not a reason.
Values: retention-expiry, redaction-order, correction, none
MutationEffect#
(typeof MUTATION_EFFECTS)[number];
MutationReason#
(typeof MUTATION_REASONS)[number];
MutationRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
before |
ActivityEvent | required | — |
after |
ActivityEvent | null — ActivityEvent |
required | Null means the row is being removed outright. |
reason |
MutationReason | required | — |
authorizedBy |
string | null |
required | — |
orderedUnderPolicyVersion |
number |
required | The policy version the order was WRITTEN against. |
at |
Instant | required | — |
MutationVerdict#
| Field | Type | Required | Notes |
|---|---|---|---|
allowed |
boolean |
required | — |
effects |
readonly MutationEffect[] — MutationEffect |
required | What the request actually does, whatever it says it does. |
findings |
readonly ActivityFinding[] — ActivityFinding |
required | — |
orderActivityFeed#
orderActivityFeed(events: readonly ActivityEvent[]): readonly ActivityEvent[]
orderDivergenceBetweenViewers#
Whether two readers of the same rows were given them in the same order (S8.9.e ∩ S8.9.d).
orderDivergenceBetweenViewers(left: { readonly viewerId: string; readonly rows: readonly ActivityEvent[] }, right: { readonly viewerId: string; readonly rows: readonly ActivityEvent[] }): readonly ActivityFinding[]
ParityComparison#
| Field | Type | Required | Notes |
|---|---|---|---|
comparable |
boolean |
required | False when the two projections were produced under different rules. |
findings |
readonly ActivityFinding[] — ActivityFinding |
required | — |
PLURAL_CATEGORIES#
Values: zero, one, two, few, many, other
pluralCategoriesFor#
Every category a locale can produce, so a catalogue entry can be checked for completeness.
pluralCategoriesFor(locale: string): readonly PluralCategory[]
pluralCategory#
The plural category a count falls into for a locale.
pluralCategory(count: number, locale: string): PluralCategory
PluralCategory#
(typeof PLURAL_CATEGORIES)[number];
projectActivityFeed#
Fold a log into a feed (S8.9.b and S8.9.f).
projectActivityFeed(records: readonly SourceRecord[], options: ProjectorOptions): ProjectionOutcome
PROJECTION_REFUSALS#
Values: inadmissible-source-kind, mutable-source-stream,
unusable-source-position, unparseable-source-time
ProjectionOutcome#
| Field | Type | Required | Notes |
|---|---|---|---|
projection |
FeedProjection | required | — |
refused |
readonly RefusedRecord[] — RefusedRecord |
required | Records the projector declined. Never rows it invented a source for. |
findings |
readonly ActivityFinding[] — ActivityFinding |
required | — |
ProjectionRefusal#
(typeof PROJECTION_REFUSALS)[number];
ProjectorOptions#
| Field | Type | Required | Notes |
|---|---|---|---|
projectorVersion |
number |
required | — |
policyVersion |
number |
required | — |
recordedAt |
Instant | required | The projector's clock. Lands in recordedAt and reaches nothing else. |
pseudonym |
(actorId: string, audienceScope: string) => string |
required | — |
audienceScopeFor |
(visibility: ActivityVisibility) => string — ActivityVisibility |
required | — |
PseudonymAssignment#
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
string |
required | — |
audienceScope |
string |
required | — |
handle |
string |
required | — |
pseudonymFaults#
Whether the handles a feed hands out are stable in the one direction and unstable in the other (decision 9).
pseudonymFaults(assignments: readonly PseudonymAssignment[]): readonly ActivityFinding[]
RefusedRecord#
| Field | Type | Required | Notes |
|---|---|---|---|
refusal |
ProjectionRefusal | required | — |
at |
string |
required | — |
detail |
string |
required | — |
renderActivitySummary#
Turn a stored summary into a sentence in the reader's locale (S8.9.c).
renderActivitySummary(summary: ActivitySummary, options: RenderOptions): RenderedSummary
RenderedSummary#
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | null |
required | Null when the summary could not be rendered honestly. |
categoryUsed |
PluralCategory | null — PluralCategory |
required | — |
findings |
readonly ActivityFinding[] — ActivityFinding |
required | — |
RenderOptions#
| Field | Type | Required | Notes |
|---|---|---|---|
locale |
string |
required | — |
catalogue |
Readonly<Record<string, CatalogueEntry>> — CatalogueEntry |
required | — |
withheldParams |
readonly string[] |
optional | Parameters authorization removed. Their slots must not be filled. |
REPLAY_PARITY_FAULTS#
Values: projector-version-differs, policy-version-differs,
row-missing-from-the-rebuild, row-only-in-the-rebuild, order-disagrees,
content-disagrees, visibility-disagrees, watermark-disagrees
ReplayParityFault#
(typeof REPLAY_PARITY_FAULTS)[number];
RetentionPolicy#
| Field | Type | Required | Notes |
|---|---|---|---|
maxAgeDays |
number |
required | — |
redactionAuthorities |
readonly string[] |
required | Who may order a redaction. Empty means nobody may, which is a valid policy. |
tombstoneRequired |
boolean |
required | Whether a removed row must leave its position behind. |
policyVersion |
number |
required | — |
SAFE_SUMMARY_FAULTS#
Values: message-key-blank, message-key-is-a-sentence,
message-key-carries-a-locale, summary-stored-rendered,
parameter-name-blank, duplicate-parameter-name, parameter-class-forbidden,
unknown-parameter-class, parameter-class-does-not-match-its-field,
parameter-field-not-in-the-admissible-set, parameter-value-is-a-leak,
canary-value-in-a-summary, count-parameter-is-not-a-number,
timestamp-parameter-is-preformatted, pseudonym-parameter-is-a-display-name,
authored-title-above-its-classification, parameter-not-used-by-the-template,
template-slot-without-a-parameter, plural-selected-without-a-count,
plural-entry-missing-a-category-the-locale-uses,
catalogue-has-no-entry-for-the-key, render-left-a-slot-unfilled
SafeSummaryFault#
(typeof SAFE_SUMMARY_FAULTS)[number];
safeSummaryFaults#
Everything a summary must satisfy before it is stored (S8.9.c).
safeSummaryFaults(summary: ActivitySummary, options: SummaryCheckOptions = {}): readonly ActivityFinding[]
SCOPED_REFERENCE_KINDS#
Reference kinds that carry a per-audience handle and therefore need a scope.
Values: named, pseudonymous
SOURCE_LINKAGE_FAULTS#
Values: unknown-source-kind, derived-from-a-current-state-read,
derived-from-a-ui-observation, source-stream-is-not-append-only,
source-stream-blank, source-sequence-not-a-positive-integer,
source-event-id-blank, source-occurred-at-unparseable,
source-correlation-blank, two-rows-at-one-source-position,
one-source-event-under-two-streams, one-source-position-under-two-event-ids,
two-rows-one-source-disagree-on-content,
projector-versions-mixed-in-one-projection
SourceLinkageFault#
(typeof SOURCE_LINKAGE_FAULTS)[number];
sourceLinkageFaults#
Whether a set of rows was generated from something that can be read again (S8.9.b).
sourceLinkageFaults(events: readonly ActivityEvent[]): readonly ActivityFinding[]
SourceRecord#
One row of the log, as the projector receives it.
| Field | Type | Required | Notes |
|---|---|---|---|
source |
ActivitySource | required | — |
type |
ActivityType | required | — |
target |
ActivityTarget | required | — |
actorId |
string |
required | — |
actorKind |
ActorReferenceKind | required | — |
roleKey |
string | null |
required | — |
outcome |
ActivityOutcome | required | — |
visibility |
ActivityVisibility | required | — |
summary |
ActivitySummary | required | — |
linkedObjectIds |
readonly string[] |
required | — |
SUMMARY_SOURCE_FIELDS#
Every field of the event a summary parameter is allowed to have come from.
Values: type, outcome, occurredAt, target.kind, target.revision,
target.title, actor.handle, actor.roleKey, stage.name, computed.count,
computed.duration
SummaryCheckOptions#
| Field | Type | Required | Notes |
|---|---|---|---|
canaries |
readonly string[] |
optional | Literal strings planted by a leakage suite. Any appearance is a failure. |
template |
string |
optional | The template the key resolves to, when the catalogue is available. |
classification |
ActivityClassification | optional | — |
summaryLeaks#
The canary scan on its own, over every string a summary carries.
summaryLeaks(summary: ActivitySummary, options: { readonly canaries?: readonly string[]; readonly tenant?: TenantId | null } = {}): readonly Leak[]
SummaryParam#
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string |
required | — |
paramClass |
SummaryParamClass | required | — |
value |
string |
required | — |
fromField |
SummarySourceField | string — SummarySourceField |
required | — |
SummaryParamClass#
AdmissibleParamClass | ForbiddenParamClass;
summarySlots#
The parameter names a template interpolates, in the order it first mentions them.
summarySlots(template: string): readonly string[]
SummarySourceField#
(typeof SUMMARY_SOURCE_FIELDS)[number];
WITHHOLD_REASONS#
Values: other-tenant, no-audience-in-common, no-grant-on-the-object,
no-read-feed-capability
WithholdReason#
(typeof WITHHOLD_REASONS)[number];
Valid examples#
No committed fixture corpus covers this page's accepted cases; they are unit-level and live in the module's own spec.
Invalid examples#
No committed fixture corpus covers this page's refused cases; they are unit-level and live in the module's own spec.
Authorization and scope#
| Symbol | Type | Notes |
| ------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --- |
| ActivityEvent.actor | ActorReference | — |
| ActivityViewer.objectGrants | readonly string[] | — |
| ActivityViewer.propertyGrants | readonly string[] | Summary parameter names this viewer may see when a scope narrows them. |
| ActivityViewer.tenantId | string | — |
| ActivityVisibility.propertyScopes | Readonly<Record<string, ActivityAudience>> | Summary parameters that are narrower than the event carrying them. |
| ActivityVisibility.tenantId | string | — |
| ACTOR_REFERENCE_KINDS | enumeration | How an actor may be named to an audience. |
| ActorReference.audienceScope | string | The audience the handle is stable within, and outside which it must differ. |
| ActorReferenceKind | type | — |
| AUDIENCES_WITHOUT_PER_OBJECT_GRANT | enumeration | Audiences that read across objects by definition, so a per-object grant is not what authorizes them. |
| FeedRendering.actorFacets | readonly string[] | — |
| MutationRequest.authorizedBy | string | null | — |
| ProjectorOptions.audienceScopeFor | (visibility: ActivityVisibility) => string | — |
| PseudonymAssignment.actorId | string | — |
| PseudonymAssignment.audienceScope | string | — |
| SCOPED_REFERENCE_KINDS | enumeration | Reference kinds that carry a per-audience handle and therefore need a scope. |
| SourceRecord.actorId | string | — |
| SourceRecord.actorKind | ActorReferenceKind | — |
Idempotency and concurrency#
| Symbol | Type | Notes |
| ------------------------------- | -------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
| ActivityEvent.causationId | string | — |
| ActivitySource.streamSequence | number | Position within the stream. Gapless per stream; meaningless across them. |
| ActivityTarget.revision | string | null | Which version of the object the event is about. |
| FeedOrderKey.streamSequence | number | — |
Pagination#
| Symbol | Type | Notes |
| ------------------------------ | ---------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| cursorFaults | function | Whether a cursor survives a round trip and carries the whole key (S8.9.e). |
| decodeFeedCursor | function | — |
| EMPTY_FEED_PROJECTION | function | — |
| encodeFeedCursor | function | A cursor is the whole key (decision 4). |
| FeedWatermark.issuedCursor | FeedOrderKey | null | The furthest cursor handed to a reader, or null if none has been. |
| PROJECTION_REFUSALS | enumeration | — |
| ProjectionOutcome.projection | FeedProjection | — |
| ProjectionRefusal | type | — |
State and failure#
| Symbol | Type | Notes |
|---|---|---|
ActivityEvent.outcome |
ActivityOutcome |
— |
ActivityOutcome |
type |
— |
PROJECTION_REFUSALS |
enumeration |
— |
ProjectionOutcome.refused |
readonly RefusedRecord[] |
Records the projector declined. Never rows it invented a source for. |
ProjectionRefusal |
type |
— |
RefusedRecord.refusal |
ProjectionRefusal |
— |
SourceRecord.outcome |
ActivityOutcome |
— |
Compatibility#
| Symbol | Type | Notes |
|---|---|---|
ACTIVITY_EVENT_SCHEMA_VERSION |
constant |
The schema this module writes. A reader that meets a higher number has met a row it cannot fully understand, and the honest response is to say so rather than to render the fields it recognises. |
ActivityEvent.eventVersion |
number |
Bumped by a lawful redaction or retention action, never by a correction. |
ActivityEvent.projectorVersion |
number |
— |
ActivityEvent.schemaVersion |
number |
— |
FeedProjection.policyVersion |
number |
— |
FeedProjection.projectorVersion |
number |
— |
MutationRequest.orderedUnderPolicyVersion |
number |
The policy version the order was WRITTEN against. |
ProjectorOptions.policyVersion |
number |
— |
ProjectorOptions.projectorVersion |
number |
— |
RetentionPolicy.policyVersion |
number |
— |
Deprecation#
Not applicable: nothing on this page can be deprecated on its own; the package version is its lifecycle.
Evidence#
evidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/activity-feed.ts