Eve library

Immutable activity-feed events

Evidence

Revision 1

On this page

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#

ts
(typeof ACTIVITY_AUDIENCES)[number];

ActivityCapability#

ts
(typeof ACTIVITY_CAPABILITIES)[number];

ActivityClassification#

ts
(typeof ACTIVITY_CLASSIFICATIONS)[number];

ActivityDisclosureFault#

ts
(typeof ACTIVITY_DISCLOSURE_FAULTS)[number];

activityDisclosureFaults#

Compare what a surface showed against what the viewer was entitled to (S8.9.d).

ts
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#

ts
(typeof ACTIVITY_EVENT_FAULTS)[number];

activityEventFaults#

Everything a single row must satisfy before anything else looks at it (S8.9.a).

ts
activityEventFaults(event: ActivityEvent): readonly ActivityFinding[]

activityEventId#

The id of the row a source position produces (decision 2).

ts
activityEventId(streamId: string, streamSequence: number, type: ActivityType): string

activityEventIdComponents#

Take an id apart again. Null when it is not one of ours.

ts
activityEventIdComponents(eventId: string): { readonly streamId: string; readonly streamSequence: number; readonly type: string } | null

ActivityFeedFault#

ts
| 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#

ts
(typeof ACTIVITY_MUTATION_FAULTS)[number];

ActivityOutcome#

ts
AuditOutcome;

activityReplayParity#

Compare a rebuild from an empty feed against the stored projection (S8.9.f).

ts
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#

ts
(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#

ts
(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#

ts
(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#

ts
(typeof ADMISSIBLE_PARAM_CLASSES)[number];

admitArrival#

Decide what to do with a row that has just arrived (S8.9.e).

ts
admitArrival(event: ActivityEvent, watermark: FeedWatermark): ArrivalDecision

advanceWatermark#

A watermark only ever moves forward. Going back re-opens settled pages.

ts
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#

ts
(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).

ts
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#

ts
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#

ts
classifyArrival(event: ActivityEvent, watermark: FeedWatermark): ArrivalClass

compareFeedOrder#

Newest first, and total (decision 3).

ts
compareFeedOrder(left: FeedOrderKey, right: FeedOrderKey): number

cursorFaults#

Whether a cursor survives a round trip and carries the whole key (S8.9.e).

ts
cursorFaults(cursorText: string, key: FeedOrderKey): readonly ActivityFinding[]

decodeFeedCursor#

ts
decodeFeedCursor(text: string): FeedOrderKey | null

discloseActivity#

What one viewer may be told about one row (S8.9.d).

ts
discloseActivity(event: ActivityEvent, viewer: ActivityViewer): Disclosure

Disclosure#

ts
| { 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#

ts
EMPTY_FEED_PROJECTION(projectorVersion: number, policyVersion: number): FeedProjection

encodeFeedCursor#

A cursor is the whole key (decision 4).

ts
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#

ts
(typeof FEED_ORDER_FAULTS)[number];

feedOrderFaults#

Whether a page came out in the one order the key defines (S8.9.e).

ts
feedOrderFaults(observed: readonly ActivityEvent[]): readonly ActivityFinding[]

feedOrderKey#

The key a row sits at. Derived, never stored, never a counter.

ts
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#

ts
(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#

ts
(typeof MUTATION_EFFECTS)[number];

MutationReason#

ts
(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#

ts
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).

ts
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.

ts
pluralCategoriesFor(locale: string): readonly PluralCategory[]

pluralCategory#

The plural category a count falls into for a locale.

ts
pluralCategory(count: number, locale: string): PluralCategory

PluralCategory#

ts
(typeof PLURAL_CATEGORIES)[number];

projectActivityFeed#

Fold a log into a feed (S8.9.b and S8.9.f).

ts
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#

ts
(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).

ts
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).

ts
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#

ts
(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#

ts
(typeof SAFE_SUMMARY_FAULTS)[number];

safeSummaryFaults#

Everything a summary must satisfy before it is stored (S8.9.c).

ts
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#

ts
(typeof SOURCE_LINKAGE_FAULTS)[number];

sourceLinkageFaults#

Whether a set of rows was generated from something that can be read again (S8.9.b).

ts
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.

ts
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#

ts
AdmissibleParamClass | ForbiddenParamClass;

summarySlots#

The parameter names a template interpolates, in the order it first mentions them.

ts
summarySlots(template: string): readonly string[]

SummarySourceField#

ts
(typeof SUMMARY_SOURCE_FIELDS)[number];

WITHHOLD_REASONS#

Values: other-tenant, no-audience-in-common, no-grant-on-the-object, no-read-feed-capability

WithholdReason#

ts
(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.json
  • libs/oshun/workbench-kit/src/activity-feed.ts