Eve library

Review inbox and saved queues

Evidence

Revision 1

On this page

Why a worklist that ships every row and narrows it in the browser has disclosed everything it does not draw, which of a reader’s five grounds decides what they may do to a row and why the strongest of them has to win, what a recusal is that a missing ground is not, why finished work has to leave the count in the same place it leaves the list, what a filter owes a reader when a row has no value on the axis at all, why a sort with no unique backstop is the reason a surface has no pagination rather than a detail of it, which four things a cursor has to be bound to, what a saved queue has to carry besides its query before it can be reopened a release later, what sharing a queue does and does not share, and which single action a bulk gesture may never take.

Generated from libs/oshun/workbench-kit/src/review-inbox.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: S8.10. Do not edit by hand.

Summary#

  • src/review-inbox.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/review-inbox contract S8.10

Exports#

Symbol Kind Summary
ABSENCE_POLICIES enumeration What a predicate does with a row that has no value on its axis.
AbsencePolicy type —
ACTION_REFUSALS enumeration —
actionAuditRow function —
ActionAuditRow interface The row an action owes the audit.
ActionContext interface What the host knows about the row at the moment the action arrives.
actionImpact function —
ActionImpact interface Whose lists change, which is what "impact" means on a worklist.
ActionRefusal type —
ACTIONS_BY_GROUND constant What each ground authorizes, and the two asymmetries that matter.
ACTIONS_BY_KIND constant Which actions each kind defines at all. A gate is not declined; it is waived.
ACTIONS_REQUIRING_A_DESTINATION enumeration —
ACTIONS_REQUIRING_A_REASON enumeration Actions that cannot be taken without saying why.
ADMISSION_FAULTS enumeration —
ADMISSION_REFUSALS enumeration —
AdmissionFault type —
admissionFaults function Check a host's own admission against the one the grounds support (S8.10.b).
AdmissionObservation interface What a host says it decided, so the decision itself can be checked.
AdmissionRefusal type —
AdmissionResult interface —
admitAll function Admit a whole worklist for one reader.
AdmittedRow interface An admitted row, carrying the admission that let it through.
admittedSetFaults function Check the number a surface puts beside the list against the list (S8.10.b).
admitToInbox function Decide whether a row belongs in this reader's list, and on what ground (S8.10.b).
ALL_REVIEW_INBOX_FAULTS constant Every fault kind this module can emit.
answerInboxQuery function Admit, filter, order, count and cut — in that order, on the server (S8.10.c/d).
applyInboxFilter function Narrow an ADMITTED set (S8.10.c).
AXIS_VERDICTS enumeration —
AxisPredicate interface —
axisValue function The row's value on an axis, or null when the row has none.
AxisVerdict type —
Blocker interface Something in the way, and whether the reader can do anything about it.
BULK_DISPOSITIONS enumeration —
BulkActionRequest interface —
BulkDisposition type —
BulkPlan interface —
BulkSelectionEntry interface A frozen selection: the ids AND the revision each was read at.
compareInboxOrder function Compare two order keys. Total, and never NaN (S8.10.d).
CURRENT_VOCABULARY_VERSION constant —
cursorBindingFaults function What a cursor was minted against, so the minting can be checked (S8.10.d).
CursorResumption type —
decideInboxAction function Decide one action (S8.10.f).
decodeInboxCursor function —
DEEP_LINK_LANDINGS enumeration Where a deep link into a worklist actually lands.
DeepLinkLanding interface —
DeepLinkLandingKind type —
DelegationGrant interface An authority somebody else's ground was lent under.
DeliveryObservation interface What actually crossed the wire, against what the reader was shown.
DueSnapshot interface The deadline and the clock, each independently absent-able.
ELIGIBILITY_GROUNDS enumeration The five ways a row gets into somebody's list.
EligibilityGround type —
encodeInboxCursor function —
evaluatePredicate function Three-valued: a row with no value on the axis neither matches nor fails.
FIELDS_NEVER_SEARCHABLE enumeration Fields a full-text query may never reach, whatever the caller asks for.
FILTER_FAULTS enumeration —
FilterAccounting interface How many rows a filter removed, and for which of the two reasons.
FilterObservation interface What a host says its query surface did.
FilterResult interface —
FOCUS_LANDINGS enumeration Where focus goes when the row holding it leaves the list.
FOCUS_LANDINGS_THAT_LOSE_THE_PLACE enumeration Focus landings that lose the reader's place in the work.
FocusLanding type —
foldForSearch function The one folding both sides of a search must use.
FRESHNESS_REQUIRING_A_REREAD enumeration Freshness values that do not entitle a reader to act without re-reading.
FRESHNESS_STANDINGS enumeration How much of the reader's answer the projection could actually establish.
grantAdmits function Whether a grant admits this reader at this moment.
GROUND_STRENGTH constant How specific a ground is to THIS reader and THIS row. Higher wins.
INBOX_ACTION_FAULTS enumeration —
INBOX_ACTIONS enumeration What a reader can do to a row they hold.
INBOX_COUNT_BASES enumeration What a count was computed over.
INBOX_CURSOR_REJECTIONS enumeration —
INBOX_FILTER_AXES enumeration The axes a worklist is narrowed on.
INBOX_JOURNEY_FAULTS enumeration —
INBOX_ORDER_FAULTS enumeration —
INBOX_PROJECTOR_VERSION constant —
INBOX_SORT_AXES enumeration What a worklist may be ordered by.
InboxActionFault type —
inboxActionFaults function Check a bulk run against the freeze, the ladder and the log it owes (S8.10.f).
InboxActionName type —
InboxActionObservation interface —
InboxActionOutcome type —
InboxActionRequest interface —
InboxAnswer interface —
InboxCount interface —
InboxCountBasis type —
InboxCursor interface What a cursor is bound to.
InboxCursorRejection type —
inboxDeliveryFaults function Compare what was sent with what was shown (S8.10.c/d, decision 1).
InboxEligibility type —
InboxFilter interface —
InboxFilterAxis type —
InboxFilterFault type —
inboxFilterFaults function Check a host's filtering against what admission and the predicates support (S8.10.c).
InboxFinding interface —
InboxItem interface One row of a worklist.
inboxItemId function The row id, which is decodable and carries the kind.
inboxItemIdComponents function The inverse of , or null if the text is not one.
InboxJourneyFault type —
inboxJourneyFaults function Check the journey a reader actually has through a worklist (S8.10.g).
InboxJourneyObservation interface —
InboxOrderFault type —
inboxOrderFaults function Check a rendered order against the canonical one (S8.10.d).
inboxOrderKey function —
InboxOrderKey interface The four components after the axis, and their directions.
InboxQuery interface —
inboxQueryDigest function A digest of the query, for binding a cursor to the question it answers.
InboxReader interface The reader, and every membership that could put a row in front of them.
InboxSort interface —
InboxSortAxis type —
itemCountedMinutes function Counted minutes burned against this row's budget, or null with no clock.
itemDueStanding function Where this row's deadline stands, or no-deadline when it has none.
ItemFreshness type —
itemSlaStanding function Where this row's SLA stands, or null when the kind has no clock.
JUDGING_INBOX_ROLES enumeration Roles whose holder is deciding rather than watching, so a recusal binds.
KINDS_A_BULK_GESTURE_MAY_NOT_COMPLETE enumeration Kinds whose completion may not be produced by a single bulk gesture.
KINDS_REQUIRING_A_DIRECT_GROUND enumeration Kinds whose completion needs the most specific ground there is.
KINDS_WITH_AN_SLA_CLOCK enumeration Kinds that carry an SLA clock at all.
matchesText function —
MigrationRecord interface —
NarrowObservation interface —
NULLABLE_AXES enumeration Axes a row may legitimately have no value on.
offAxisRows function Rows the sort could not place, which is a segment and not a tail.
openSavedQueue function Open a saved queue for a reader (S8.10.e).
orderInbox function The canonical order for a set of rows.
OrderObservation interface —
PageObservation interface —
PageReconciliation interface —
planInboxActions function Plan a bulk run over a FROZEN selection (S8.10.f).
primaryRank function Where a row sits on a sort axis, or null when it is not on that axis.
PROJECTION_FAULTS enumeration —
ProjectionFault type —
projectionFaults function Check one projected row against the kind it claims to be (S8.10.a).
QUEUE_DENSITIES enumeration —
QUEUE_OPEN_REFUSALS enumeration —
QueueAudience type Who a saved queue has been shared with.
QueueDensity type —
QueueGrant interface —
QueueOpening type —
QueueOpenRefusal type —
QueueVocabulary interface The vocabulary a saved filter's VALUES were drawn from.
reconcilePages function Account for the difference between two reads of the same query (S8.10.d).
RECONCILIATION_FAULTS enumeration —
ReconciliationFault type —
reconciliationFaults function Check a two-page traversal against the arithmetic it owes (S8.10.d).
RefusedRow interface A row that did not get in, and why.
resumeInboxCursor function Whether a cursor may be resumed against the query now being asked.
ReviewInboxFault type —
SafeSummary interface The row's one line of prose, in the S8.9 shape: a template plus classified parameters, never a rendered string.
SAVED_QUEUE_FAULTS enumeration —
SavedQueue interface —
SavedQueueFault type —
savedQueueFaults function Check a saved-queue surface against what a share and a migration owe (S8.10.e).
SavedQueueObservation interface What a host's saved-queue surface actually does.
SEARCHABLE_FIELDS enumeration Fields a full-text query is allowed to reach.
SearchableField type —
searchableText function The searchable text of one field, or null when the row has none.
SlaSnapshot interface —
SORT_DIRECTIONS enumeration —
SortDirection type —
TextSearch interface —
TraversalObservation interface —
UnsearchableField type —
VocabularyChange interface One value's fate between two vocabulary versions.
Withdrawal interface —
WITHDRAWAL_REASONS enumeration Why a row that was on one page is not on the next.
WithdrawalReason type —
WORK_KINDS enumeration The five things that put a row in somebody's inbox.
WorkKind type —
WorkRouting interface Who the row is routed to, from the source rather than from the projection.
WorkSource interface Where the row came from, so a projection can be rebuilt and compared.
WorkTarget interface What the row is about, and the revision the projection read.

Shapes#

ABSENCE_POLICIES#

What a predicate does with a row that has no value on its axis.

Values: exclude, include, only

AbsencePolicy#

ts
(typeof ABSENCE_POLICIES)[number];

ACTION_REFUSALS#

Values: row-no-longer-admitted, not-permitted-on-this-ground, action-not-defined-for-this-kind, expected-revision-is-stale, reason-required, destination-required, destination-not-eligible, reassigned-to-the-current-holder, one-gesture-may-not-attest

actionAuditRow#

ts
actionAuditRow(request: InboxActionRequest, context: ActionContext): ActionAuditRow

ActionAuditRow#

The row an action owes the audit.

Field Type Required Notes
itemId string required —
action InboxActionName required —
actorId ActorId required —
onBehalfOf ActorId | null — ActorId required —
grant string | null required —
ground EligibilityGround required —
expectedRevision RevisionId required —
reason string | null required —
at Instant required —

ActionContext#

What the host knows about the row at the moment the action arrives.

Field Type Required Notes
row AdmittedRow required —
currentRevision RevisionId required The revision the store holds NOW, which the reader may not have seen.
destinationEligible boolean required Whether the destination of a reassignment could itself be admitted.
partOfABulkGesture boolean required True when this request is one of many dispatched by a single gesture.

actionImpact#

ts
actionImpact(request: InboxActionRequest, context: ActionContext, escalationTarget: ActorId | null): ActionImpact

ActionImpact#

Whose lists change, which is what "impact" means on a worklist.

Field Type Required Notes
itemId string required —
action InboxActionName required —
removesFrom readonly ActorId[] — ActorId required —
addsTo readonly ActorId[] — ActorId required —
returnsToQueue string | null required The queue the row falls back into, when it falls back into one.

ActionRefusal#

ts
(typeof ACTION_REFUSALS)[number];

ACTIONS_BY_GROUND#

What each ground authorizes, and the two asymmetries that matter.

ACTIONS_BY_KIND#

Which actions each kind defines at all. A gate is not declined; it is waived.

ACTIONS_REQUIRING_A_DESTINATION#

Values: reassign

ACTIONS_REQUIRING_A_REASON#

Actions that cannot be taken without saying why.

Values: block, decline, escalate

ADMISSION_FAULTS#

Values: admitted-on-the-first-ground-not-the-strongest, delegated-beyond-the-delegator, delegate-may-reassign, stage-owner-may-decide, queue-member-may-decide, signoff-completable-without-a-direct-ground, terminal-row-in-the-admitted-set, count-includes-what-the-list-excludes, reread-not-required-on-a-row-that-needs-one

ADMISSION_REFUSALS#

Values: tenant-mismatch, actor-kind-may-not-hold-work, recused-from-the-object, work-is-finished, ground-has-lapsed, no-ground

AdmissionFault#

ts
(typeof ADMISSION_FAULTS)[number];

admissionFaults#

Check a host's own admission against the one the grounds support (S8.10.b).

ts
admissionFaults(observation: AdmissionObservation): readonly InboxFinding[]

AdmissionObservation#

What a host says it decided, so the decision itself can be checked.

Field Type Required Notes
item InboxItem required —
routing WorkRouting required —
reader InboxReader required —
now Instant required —
recordedGround EligibilityGround required The ground the host says admitted the row.
recordedActions readonly InboxActionName[] — InboxActionName required The actions the host says the reader may take.
recordedRequiresReread boolean required —

AdmissionRefusal#

ts
(typeof ADMISSION_REFUSALS)[number];

AdmissionResult#

Field Type Required Notes
admitted readonly AdmittedRow[] — AdmittedRow required —
refused readonly RefusedRow[] — RefusedRow required —

admitAll#

Admit a whole worklist for one reader.

ts
admitAll(items: readonly InboxItem[], routings: readonly WorkRouting[], reader: InboxReader, now: Instant): AdmissionResult

AdmittedRow#

An admitted row, carrying the admission that let it through.

Field Type Required Notes
item InboxItem required —
routing WorkRouting required —
ground EligibilityGround required —
mayAct readonly InboxActionName[] — InboxActionName required —
requiresReread boolean required —

admittedSetFaults#

Check the number a surface puts beside the list against the list (S8.10.b).

ts
admittedSetFaults(result: AdmissionResult, recordedCount: number): readonly InboxFinding[]

admitToInbox#

Decide whether a row belongs in this reader's list, and on what ground (S8.10.b).

ts
admitToInbox(item: InboxItem, routing: WorkRouting, reader: InboxReader, now: Instant): InboxEligibility

ALL_REVIEW_INBOX_FAULTS#

Every fault kind this module can emit.

answerInboxQuery#

Admit, filter, order, count and cut — in that order, on the server (S8.10.c/d).

ts
answerInboxQuery(items: readonly InboxItem[], routings: readonly WorkRouting[], reader: InboxReader, query: InboxQuery, now: Instant): InboxAnswer

applyInboxFilter#

Narrow an ADMITTED set (S8.10.c).

ts
applyInboxFilter(rows: readonly AdmittedRow[], filter: InboxFilter, now: Instant): FilterResult

AXIS_VERDICTS#

Values: matches, does-not-match, axis-absent

AxisPredicate#

Field Type Required Notes
axis InboxFilterAxis required —
values readonly string[] required Values that match. Empty means this axis is not being filtered at all.
onAbsent AbsencePolicy required —

axisValue#

The row's value on an axis, or null when the row has none.

ts
axisValue(row: AdmittedRow, axis: InboxFilterAxis, now: Instant): string | null

AxisVerdict#

ts
(typeof AXIS_VERDICTS)[number];

Blocker#

Something in the way, and whether the reader can do anything about it.

Field Type Required Notes
blockerId string required —
reasonCode string required —
clearableByHolder boolean required Whether clearing it is within the reader's own gift.
since Instant required —

BULK_DISPOSITIONS#

Values: all, partial, none

BulkActionRequest#

Field Type Required Notes
action InboxActionName required —
selection readonly BulkSelectionEntry[] — BulkSelectionEntry required —
reason string | null required —
destination ActorId | null — ActorId required —
actor ActorRef required —
at Instant required —

BulkDisposition#

ts
(typeof BULK_DISPOSITIONS)[number];

BulkPlan#

Field Type Required Notes
perItem readonly { readonly itemId: string; readonly outcome: InboxActionOutcome; }[] — InboxActionOutcome required —
applied number required —
refused number required —
disposition BulkDisposition required —

BulkSelectionEntry#

A frozen selection: the ids AND the revision each was read at.

Field Type Required Notes
itemId string required —
expectedRevision RevisionId required —

compareInboxOrder#

Compare two order keys. Total, and never NaN (S8.10.d).

ts
compareInboxOrder(left: InboxOrderKey, right: InboxOrderKey, direction: SortDirection): number

CURRENT_VOCABULARY_VERSION#

Value: 2

cursorBindingFaults#

What a cursor was minted against, so the minting can be checked (S8.10.d).

ts
cursorBindingFaults(encoded: string, mintedUnder: { readonly queryDigest: string; readonly sort: InboxSort; readonly readerId: ActorId; readonly projectorVersion: number; }): readonly InboxFinding[]

CursorResumption#

ts
| { readonly resumed: true; readonly cursor: InboxCursor }
| { readonly resumed: false; readonly rejection: InboxCursorRejection; readonly detail: string }

decideInboxAction#

Decide one action (S8.10.f).

ts
decideInboxAction(request: InboxActionRequest, context: ActionContext): InboxActionOutcome

decodeInboxCursor#

ts
decodeInboxCursor(text: string): InboxCursor | null

Where a deep link into a worklist actually lands.

Values: landed, moved, not-admitted, offset-only

DeepLinkLanding#

Field Type Required Notes
requestedItemId string required —
landing DeepLinkLandingKind required —
announcedTheMove boolean required Whether the surface told the reader the row had moved.
disclosedPosition number | null required Position shown to the reader, if any.
disclosedTotal number | null required Total shown to the reader, if any.

DeepLinkLandingKind#

ts
(typeof DEEP_LINK_LANDINGS)[number];

DelegationGrant#

An authority somebody else's ground was lent under.

Field Type Required Notes
grantId string required —
from ActorId required —
scopeKinds readonly WorkKind[] — WorkKind required Kinds the delegate may act on. Empty means the grant covers none.
scopeQueues readonly string[] required Queues the grant covers. Empty means every queue the delegator holds.
notBefore Instant required —
notAfter Instant required —
delegatorGround EligibilityGround required The ground the DELEGATOR holds, which caps what this grant can confer.

DeliveryObservation#

What actually crossed the wire, against what the reader was shown.

Field Type Required Notes
transmittedIds readonly string[] required —
displayedIds readonly string[] required —
narrowedIn 'server' | 'renderer' required —
transmittedFields readonly string[] required Field names present in the response body.
displayedFields readonly string[] required Field names the surface renders.

DueSnapshot#

The deadline and the clock, each independently absent-able.

Field Type Required Notes
commitment DueCommitment required —
soonWithinMinutes number required Minutes before the deadline at which this kind calls itself due-soon.

ELIGIBILITY_GROUNDS#

The five ways a row gets into somebody's list.

Values: direct-assignment, quorum-seat, delegation, stage-ownership, queue-membership

EligibilityGround#

ts
(typeof ELIGIBILITY_GROUNDS)[number];

encodeInboxCursor#

ts
encodeInboxCursor(cursor: InboxCursor): string

evaluatePredicate#

Three-valued: a row with no value on the axis neither matches nor fails.

ts
evaluatePredicate(row: AdmittedRow, predicate: AxisPredicate, now: Instant): AxisVerdict

FIELDS_NEVER_SEARCHABLE#

Fields a full-text query may never reach, whatever the caller asks for.

Values: authored-title, person-display-name, summary-authored-param

FILTER_FAULTS#

Values: filter-applied-before-admission, filter-widens-the-admitted-set, absent-axis-counted-as-a-mismatch, withheld-rows-not-reported, search-reaches-a-withheld-field, search-reaches-an-authored-value, search-folded-with-a-locale-lowercase, search-not-normalized, predicate-on-an-axis-that-does-not-exist

FilterAccounting#

How many rows a filter removed, and for which of the two reasons.

Field Type Required Notes
axis InboxFilterAxis required —
removedByMismatch number required —
withheldForAbsentAxis number required —
policy AbsencePolicy required —

FilterObservation#

What a host says its query surface did.

Field Type Required Notes
admitted readonly AdmittedRow[] — AdmittedRow required Rows the host admitted, before filtering.
filter InboxFilter required —
now Instant required —
returned readonly AdmittedRow[] — AdmittedRow required Rows the host returned.
reportsWithholding boolean required Whether the host reported per-axis withholding to the reader.
hostAccounting readonly FilterAccounting[] | null — FilterAccounting required The host's OWN per-axis accounting, or null when it keeps none.
indexedFields readonly string[] required Fields the host's search index actually covers, as the host names them. Entries drawn from are the finding.
withheldFields readonly string[] required Fields this row's disclosure withholds from this reader.
foldsWithLocaleLowercase boolean required Whether the host folds with toLocaleLowerCase.
normalizesBeforeFolding boolean required Whether the host normalizes before folding.

FilterResult#

Field Type Required Notes
kept readonly AdmittedRow[] — AdmittedRow required —
accounting readonly FilterAccounting[] — FilterAccounting required —
removedByText number required —

FOCUS_LANDINGS#

Where focus goes when the row holding it leaves the list.

Values: same-position, list-top, document-body, lost

FOCUS_LANDINGS_THAT_LOSE_THE_PLACE#

Focus landings that lose the reader's place in the work.

Values: list-top, document-body, lost

FocusLanding#

ts
(typeof FOCUS_LANDINGS)[number];

foldForSearch#

The one folding both sides of a search must use.

ts
foldForSearch(text: string): string

FRESHNESS_REQUIRING_A_REREAD#

Freshness values that do not entitle a reader to act without re-reading.

Values: stale, expired, unknown

FRESHNESS_STANDINGS#

How much of the reader's answer the projection could actually establish.

Values: current, stale, expired, unknown

grantAdmits#

Whether a grant admits this reader at this moment.

ts
grantAdmits(grant: QueueGrant, reader: InboxReader, now: Instant): boolean

GROUND_STRENGTH#

How specific a ground is to THIS reader and THIS row. Higher wins.

INBOX_ACTION_FAULTS#

Values: action-without-an-expected-revision, bulk-completed-a-signoff, partial-run-reported-as-a-success, per-item-outcomes-do-not-cover-the-selection, selection-re-evaluated-at-execution, decline-without-a-reason, audit-names-the-delegate-and-not-the-authority, audit-does-not-name-the-ground, impact-not-shown-before-a-handover

INBOX_ACTIONS#

What a reader can do to a row they hold.

Values: accept, start, block, complete, decline, reassign, escalate

INBOX_COUNT_BASES#

What a count was computed over.

Values: admitted, after-filter, after-filter-and-search

INBOX_CURSOR_REJECTIONS#

Values: unreadable, different-query, different-sort, different-reader, different-projector

INBOX_FILTER_AXES#

The axes a worklist is narrowed on.

Values: domain, workbench, kind, state, stage, assignee, role, priority, due, sla, freshness, gate, target

INBOX_JOURNEY_FAULTS#

Values: announced-count-is-the-window, every-row-control-is-a-tab-stop, rows-not-reachable-by-arrow-keys, focus-lost-when-the-row-left, row-departure-not-announced, focus-scrolled-out-of-the-window, deep-link-restores-an-offset, deep-link-move-not-announced, refusal-discloses-the-position, refusal-discloses-the-total, narrow-drops-a-column-an-offered-action-needs, off-axis-segment-not-announced

INBOX_ORDER_FAULTS#

Values: order-disagrees-with-the-canonical-order, off-axis-rows-not-segregated, off-axis-segment-moves-with-the-direction, off-axis-segment-not-labelled, order-key-is-not-total, comparator-reads-an-unparseable-time-as-a-tie, sequences-compared-across-streams, cursor-not-bound-to-the-sort, cursor-not-bound-to-the-query, cursor-not-bound-to-the-reader, cursor-not-bound-to-the-projector

INBOX_PROJECTOR_VERSION#

Value: 1

INBOX_SORT_AXES#

What a worklist may be ordered by.

Values: due, sla-burn, priority, freshness, last-observed

InboxActionFault#

ts
(typeof INBOX_ACTION_FAULTS)[number];

inboxActionFaults#

Check a bulk run against the freeze, the ladder and the log it owes (S8.10.f).

ts
inboxActionFaults(observation: InboxActionObservation): readonly InboxFinding[]

InboxActionName#

ts
(typeof INBOX_ACTIONS)[number];

InboxActionObservation#

Field Type Required Notes
request BulkActionRequest required —
plan BulkPlan required —
reportedDisposition BulkDisposition required The outcome the host reported to the reader.
actedOn readonly string[] required Ids the host actually acted on, which must equal the frozen selection.
auditRows readonly ActionAuditRow[] — ActionAuditRow required —
showedImpactBeforeConfirming boolean required Whether a handover's impact was shown before it was confirmed.

InboxActionOutcome#

ts
| { readonly outcome: 'applied'; readonly detail: string }
| { readonly outcome: 'refused'; readonly refusal: ActionRefusal; readonly detail: string; }

InboxActionRequest#

Field Type Required Notes
itemId string required —
action InboxActionName required —
expectedRevision RevisionId required The revision the reader was looking at when they decided.
reason string | null required —
destination ActorId | null — ActorId required —
actor ActorRef required —
at Instant required —

InboxAnswer#

Field Type Required Notes
rows readonly AdmittedRow[] — AdmittedRow required —
count InboxCount required —
nextCursor string | null required —
accounting readonly FilterAccounting[] — FilterAccounting required —
refused readonly RefusedRow[] — RefusedRow required —
offAxisCount number required —
cursorRejection InboxCursorRejection | null — InboxCursorRejection required —

InboxCount#

Field Type Required Notes
basis InboxCountBasis required —
value number required —
asOf Instant required —
fromTheSameReadAsThePage boolean required Whether this number and the page it is shown beside came from one read.

InboxCountBasis#

ts
(typeof INBOX_COUNT_BASES)[number];

InboxCursor#

What a cursor is bound to.

Field Type Required Notes
key InboxOrderKey required —
sort InboxSort required —
queryDigest string required —
readerId ActorId required —
projectorVersion number required —

InboxCursorRejection#

ts
(typeof INBOX_CURSOR_REJECTIONS)[number];

inboxDeliveryFaults#

Compare what was sent with what was shown (S8.10.c/d, decision 1).

ts
inboxDeliveryFaults(observation: DeliveryObservation): readonly InboxFinding[]

InboxEligibility#

ts
| { readonly admitted: true; readonly ground: EligibilityGround; readonly grounds: readonly EligibilityGround[]; readonly mayAct: readonly InboxActionName[]; readonly requiresReread: boolean; readonly detail: string; }
| { readonly admitted: false; readonly refusal: AdmissionRefusal; readonly detail: string; }

InboxFilter#

Field Type Required Notes
predicates readonly AxisPredicate[] — AxisPredicate required —
text TextSearch | null — TextSearch required —

InboxFilterAxis#

ts
(typeof INBOX_FILTER_AXES)[number];

InboxFilterFault#

ts
(typeof FILTER_FAULTS)[number];

inboxFilterFaults#

Check a host's filtering against what admission and the predicates support (S8.10.c).

ts
inboxFilterFaults(observation: FilterObservation): readonly InboxFinding[]

InboxFinding#

Field Type Required Notes
kind ReviewInboxFault required —
subject string required The item, query, page, saved queue, action or journey the finding is about.
detail string required —

InboxItem#

One row of a worklist.

Field Type Required Notes
itemId string required —
kind WorkKind required —
target WorkTarget required —
role AssignmentRole required The role the reader would be acting IN, which is not who they are.
priority AssignmentPriority | null — AssignmentPriority required null when this kind has no priority axis — never a band called unknown.
state string required The source's own state word, verbatim.
terminal boolean required —
due DueSnapshot | null — DueSnapshot required —
sla SlaSnapshot | null — SlaSnapshot required —
freshness ItemFreshness required —
blockers readonly Blocker[] — Blocker required —
summary SafeSummary required —
source WorkSource required —
projectedAt Instant required When the projector ran. Separate from source.observedAt on purpose.

inboxItemId#

The row id, which is decodable and carries the kind.

ts
inboxItemId(kind: WorkKind, objectId: string): string

inboxItemIdComponents#

The inverse of , or null if the text is not one.

ts
inboxItemIdComponents(itemId: string): { readonly kind: WorkKind; readonly objectId: string } | null

InboxJourneyFault#

ts
(typeof INBOX_JOURNEY_FAULTS)[number];

inboxJourneyFaults#

Check the journey a reader actually has through a worklist (S8.10.g).

ts
inboxJourneyFaults(observation: InboxJourneyObservation): readonly InboxFinding[]

InboxJourneyObservation#

Field Type Required Notes
totalRows number required Rows in the filtered set, which is what the count must be about.
renderedRows number required Rows the virtualizer has in the DOM.
announcedRowCount number required The number a screen reader is given for the list.
tabStopsInsideTheList number required Tab stops inside the list itself, excluding its toolbar.
rowsReachableByArrowKeys boolean required —
focusAfterRowLeft FocusLanding required —
announcesRowDeparture boolean required —
focusSurvivesScrollOutOfWindow boolean required Whether focus is retained when its row scrolls out of the window.
deepLink DeepLinkLanding required —
narrow NarrowObservation required —
offAxisSegmentAnnounced boolean required Whether the off-axis segment is announced as off-axis, not as last.
offAxisRowCount number required —

InboxOrderFault#

ts
(typeof INBOX_ORDER_FAULTS)[number];

inboxOrderFaults#

Check a rendered order against the canonical one (S8.10.d).

ts
inboxOrderFaults(observation: OrderObservation): readonly InboxFinding[]

inboxOrderKey#

ts
inboxOrderKey(item: InboxItem, axis: InboxSortAxis, now: Instant): InboxOrderKey

InboxOrderKey#

The four components after the axis, and their directions.

Field Type Required Notes
primary number | null required The primary axis's rank, or null when this row is not on the axis.
observedMillis number required —
stream string required —
sequence number required —
itemId string required —

InboxQuery#

Field Type Required Notes
filter InboxFilter required —
sort InboxSort required —
limit number required —
after string | null required An encoded cursor, or null for the first page.

inboxQueryDigest#

A digest of the query, for binding a cursor to the question it answers.

ts
inboxQueryDigest(filter: InboxFilter): string

InboxReader#

The reader, and every membership that could put a row in front of them.

Field Type Required Notes
actor ActorRef required —
tenant TenantId required —
queues readonly string[] required —
ownedStages readonly string[] required —
delegations readonly DelegationGrant[] — DelegationGrant required —
recusals readonly string[] required Object ids this reader has been recused from, beyond authorship.

InboxSort#

Field Type Required Notes
axis InboxSortAxis required —
direction SortDirection required —

InboxSortAxis#

ts
(typeof INBOX_SORT_AXES)[number];

itemCountedMinutes#

Counted minutes burned against this row's budget, or null with no clock.

ts
itemCountedMinutes(item: InboxItem, now: Instant): number | null

itemDueStanding#

Where this row's deadline stands, or no-deadline when it has none.

ts
itemDueStanding(item: InboxItem, now: Instant): DueStanding

ItemFreshness#

ts
(typeof FRESHNESS_STANDINGS)[number];

itemSlaStanding#

Where this row's SLA stands, or null when the kind has no clock.

ts
itemSlaStanding(item: InboxItem, now: Instant): SlaStanding | null

JUDGING_INBOX_ROLES#

Roles whose holder is deciding rather than watching, so a recusal binds.

Values: reviewer, approver, publisher

KINDS_A_BULK_GESTURE_MAY_NOT_COMPLETE#

Kinds whose completion may not be produced by a single bulk gesture.

Values: signoff

KINDS_REQUIRING_A_DIRECT_GROUND#

Kinds whose completion needs the most specific ground there is.

Values: signoff

KINDS_WITH_AN_SLA_CLOCK#

Kinds that carry an SLA clock at all.

Values: review, assignment, escalation

matchesText#

ts
matchesText(row: AdmittedRow, search: TextSearch): boolean

MigrationRecord#

Field Type Required Notes
fromVersion number required —
toVersion number required —
rewrites readonly { readonly axis: InboxFilterAxis; readonly from: string; readonly to: string; }[] — InboxFilterAxis required —

NarrowObservation#

Field Type Required Notes
droppedColumns readonly string[] required Columns the narrow layout stops rendering.
columnsActionsDependOn Readonly<Partial<Record<InboxActionName, readonly string[]>>> — InboxActionName required Action → the column ids a reader needs in order to take it responsibly.
offeredActions readonly InboxActionName[] — InboxActionName required Actions the narrow layout still offers.

NULLABLE_AXES#

Axes a row may legitimately have no value on.

Values: stage, assignee, priority, due, sla, gate

offAxisRows#

Rows the sort could not place, which is a segment and not a tail.

ts
offAxisRows(rows: readonly AdmittedRow[], axis: InboxSortAxis, now: Instant): readonly AdmittedRow[]

openSavedQueue#

Open a saved queue for a reader (S8.10.e).

ts
openSavedQueue(queue: SavedQueue, reader: InboxReader, now: Instant, vocabulary: QueueVocabulary, changes: readonly VocabularyChange[], withheldFields: readonly string[] = []): QueueOpening

orderInbox#

The canonical order for a set of rows.

ts
orderInbox(rows: readonly AdmittedRow[], sort: InboxSort, now: Instant): readonly AdmittedRow[]

OrderObservation#

Field Type Required Notes
observed readonly AdmittedRow[] — AdmittedRow required —
sort InboxSort required —
now Instant required —
labelsOffAxisSegment boolean required Whether the surface labels the off-axis segment as off-axis.
observedReversed readonly AdmittedRow[] | null — AdmittedRow required What the SURFACE renders when the reader flips the direction.

PageObservation#

Field Type Required Notes
rows readonly string[] required Item ids in the order they were rendered.
count InboxCount required —
at Instant required —

PageReconciliation#

Field Type Required Notes
appeared readonly string[] required —
withdrawn readonly Withdrawal[] — Withdrawal required —
repeated readonly string[] required Ids present on both pages, which a keyset traversal must never produce.
unexplained readonly string[] required Rows that left with no explanation offered.
countDelta number required —
countReconciles boolean required Whether the count moved by exactly what the explanations account for.

planInboxActions#

Plan a bulk run over a FROZEN selection (S8.10.f).

ts
planInboxActions(request: BulkActionRequest, rows: readonly AdmittedRow[], contextFor: (itemId: string) => Omit<ActionContext, 'row' | 'partOfABulkGesture'> | null): BulkPlan

primaryRank#

Where a row sits on a sort axis, or null when it is not on that axis.

ts
primaryRank(item: InboxItem, axis: InboxSortAxis, now: Instant): number | null

PROJECTION_FAULTS#

Values: item-id-is-not-derived-from-the-kind-and-target, priority-absence-rendered-as-a-band, clock-on-a-kind-that-has-none, no-clock-on-a-kind-that-has-one, terminal-row-projected-as-work, freshness-unknown-rendered-as-current, blocker-without-a-reason-code, summary-carries-an-authored-value-without-declaring-it, summary-param-is-not-classified, projected-before-it-was-observed, source-position-is-not-a-position, revision-missing-from-the-target, state-word-is-empty, due-in-a-zone-the-promise-was-not-made-in

ProjectionFault#

ts
(typeof PROJECTION_FAULTS)[number];

projectionFaults#

Check one projected row against the kind it claims to be (S8.10.a).

ts
projectionFaults(item: InboxItem): readonly InboxFinding[]

QUEUE_DENSITIES#

Values: comfortable, compact

QUEUE_OPEN_REFUSALS#

Values: not-granted, grant-expired, grant-revoked, tenant-mismatch, vocabulary-version-unknown, vocabulary-version-from-the-future, value-retired-without-a-successor, axis-no-longer-exists

QueueAudience#

Who a saved queue has been shared with.

ts
| { readonly kind: 'actor'; readonly actorId: ActorId }
| { readonly kind: 'queue'; readonly queue: string }
| { readonly kind: 'tenant'; readonly tenant: TenantId }

QueueDensity#

ts
(typeof QUEUE_DENSITIES)[number];

QueueGrant#

Field Type Required Notes
grantId string required —
audience QueueAudience required —
grantedBy ActorId required Who granted it. A grant nobody made is a grant nobody can be asked about.
grantedAt Instant required —
notAfter Instant | null — Instant required —
revokedAt Instant | null — Instant required —

QueueOpening#

ts
| { readonly opened: true; readonly filter: InboxFilter; readonly sort: InboxSort; readonly columns: readonly string[]; readonly droppedColumns: readonly string[]; readonly migration: MigrationRecord | null; readonly detail: string; }
| { readonly opened: false; readonly refusal: QueueOpenRefusal; readonly detail: string; }

QueueOpenRefusal#

ts
(typeof QUEUE_OPEN_REFUSALS)[number];

QueueVocabulary#

The vocabulary a saved filter's VALUES were drawn from.

Field Type Required Notes
version number required —
oldestReadableVersion number required The oldest version this build still carries migration records for.
values Readonly<Partial<Record<InboxFilterAxis, readonly string[]>>> — InboxFilterAxis required Axis → the values that exist at this version.

reconcilePages#

Account for the difference between two reads of the same query (S8.10.d).

ts
reconcilePages(before: PageObservation, after: PageObservation, explanations: readonly Withdrawal[]): PageReconciliation

RECONCILIATION_FAULTS#

Values: count-moved-without-an-explanation, row-left-without-a-reason, row-appeared-on-a-later-page-of-the-same-traversal, count-and-page-from-different-reads, count-taken-before-the-filter, transmitted-more-rows-than-it-displayed, narrowed-in-the-renderer, transmitted-a-field-it-does-not-display

ReconciliationFault#

ts
(typeof RECONCILIATION_FAULTS)[number];

reconciliationFaults#

Check a two-page traversal against the arithmetic it owes (S8.10.d).

ts
reconciliationFaults(observation: TraversalObservation): readonly InboxFinding[]

RefusedRow#

A row that did not get in, and why.

Field Type Required Notes
itemId string required —
refusal AdmissionRefusal required —
detail string required —

resumeInboxCursor#

Whether a cursor may be resumed against the query now being asked.

ts
resumeInboxCursor(text: string, context: { readonly queryDigest: string; readonly sort: InboxSort; readonly readerId: ActorId; readonly projectorVersion: number; }): CursorResumption

ReviewInboxFault#

ts
| ProjectionFault
| AdmissionFault
| InboxFilterFault
| InboxOrderFault
| ReconciliationFault
| SavedQueueFault
| InboxActionFault
| InboxJourneyFault

SafeSummary#

The row's one line of prose, in the S8.9 shape: a template plus classified parameters, never a rendered string.

Field Type Required Notes
templateId string required —
paramClasses Readonly<Record<string, string>> required Parameter name → the class of data it carries. Values are the host's.
authoredParams readonly string[] required Param names whose values are the object's own text rather than a code.

SAVED_QUEUE_FAULTS#

Values: shared-by-a-boolean, queue-visible-only-to-its-owner, grant-without-an-audience, grant-without-a-granter, grant-outlives-the-authority-that-made-it, rows-shared-with-the-definition, count-is-the-authors-count, values-rehydrated-without-a-vocabulary, retired-value-returns-an-empty-queue, migration-not-disclosed, column-the-reader-may-not-see, more-than-one-default-for-one-owner

SavedQueue#

Field Type Required Notes
queueId string required —
title string required —
ownerId ActorId required —
tenant TenantId required —
filter InboxFilter required —
sort InboxSort required —
columns readonly string[] required Column ids, in order. Not every reader may be admitted to every one.
groupBy InboxFilterAxis | null — InboxFilterAxis required —
density QueueDensity required —
vocabularyVersion number required The vocabulary version the filter's values were drawn from.
grants readonly QueueGrant[] — QueueGrant required —
isOwnerDefault boolean required —
createdAt Instant required —
updatedAt Instant required —
revision number required —

SavedQueueFault#

ts
(typeof SAVED_QUEUE_FAULTS)[number];

savedQueueFaults#

Check a saved-queue surface against what a share and a migration owe (S8.10.e).

ts
savedQueueFaults(observation: SavedQueueObservation): readonly InboxFinding[]

SavedQueueObservation#

What a host's saved-queue surface actually does.

Field Type Required Notes
queue SavedQueue required —
reader InboxReader required —
now Instant required —
vocabulary QueueVocabulary required —
changes readonly VocabularyChange[] — VocabularyChange required —
withheldFields readonly string[] required Fields the reader is not admitted to on these rows.
storesSharingAsABoolean boolean required Whether the host stores sharing as a boolean rather than as grants. A boolean here with an empty queue.grants is the production shape.
listedFor readonly ActorId[] — ActorId required Actors the host actually returns this queue to when they list theirs.
reevaluatesRowsPerReader boolean required Whether the host re-runs the query as the reader rather than the owner.
displayedCountBelongsTo ActorId required The count the host displays beside the queue, and whose it is.
checkedVocabularyOnRead boolean required Whether the host validated the saved values against a vocabulary at all.
disclosesMigration boolean required Whether a migration, if any, was shown to the reader.
ownerDefaults readonly string[] required Every queue this owner has marked default in this workspace.
granterStillHoldsAuthority Readonly<Record<string, boolean>> required Whether the granter still holds any authority over this queue.

SEARCHABLE_FIELDS#

Fields a full-text query is allowed to reach.

Values: state, target-id, target-kind, domain, workbench, summary-template, blocker-reason, queue, stage

SearchableField#

ts
(typeof SEARCHABLE_FIELDS)[number];

searchableText#

The searchable text of one field, or null when the row has none.

ts
searchableText(row: AdmittedRow, field: SearchableField): string | null

SlaSnapshot#

Field Type Required Notes
slaClass SlaClass required —
segments readonly ClockSegment[] — ClockSegment required —

SORT_DIRECTIONS#

Values: ascending, descending

SortDirection#

ts
(typeof SORT_DIRECTIONS)[number];

TextSearch#

Field Type Required Notes
text string required —
fields readonly SearchableField[] — SearchableField required —

TraversalObservation#

Field Type Required Notes
before PageObservation required —
after PageObservation required —
explanations readonly Withdrawal[] — Withdrawal required —
keysetTraversal boolean required Whether the two pages were cut from one keyset traversal.

UnsearchableField#

ts
(typeof FIELDS_NEVER_SEARCHABLE)[number];

VocabularyChange#

One value's fate between two vocabulary versions.

Field Type Required Notes
axis InboxFilterAxis required —
from string required —
to string | null required What it became, or null when it was retired with nothing to become.
atVersion number required The version at which the change took effect.
why string required —

Withdrawal#

Field Type Required Notes
itemId string required —
reason WithdrawalReason required —
at Instant required —

WITHDRAWAL_REASONS#

Why a row that was on one page is not on the next.

Values: finished, taken-by-another, ground-revoked, filter-no-longer-matches

WithdrawalReason#

ts
(typeof WITHDRAWAL_REASONS)[number];

WORK_KINDS#

The five things that put a row in somebody's inbox.

Values: review, assignment, gate, signoff, escalation

WorkKind#

ts
(typeof WORK_KINDS)[number];

WorkRouting#

Who the row is routed to, from the source rather than from the projection.

Field Type Required Notes
itemId string required —
assignee ActorId | null — ActorId required —
quorumSeats readonly ActorId[] — ActorId required Actors holding a seat in a quorum decision on this row.
queue string | null required —
stage string | null required —
gate string | null required The gate this row is waiting on, when it is waiting on one.
authoredBy readonly ActorId[] — ActorId required Who produced the thing under review. A judge may not be one of them.

WorkSource#

Where the row came from, so a projection can be rebuilt and compared.

Field Type Required Notes
stream string required The ordering partition the source record belongs to.
sequence number required The source's own position within its stream.
observedAt Instant required When the source record last changed, from the SOURCE and not the clock.

WorkTarget#

What the row is about, and the revision the projection read.

Field Type Required Notes
objectId string required —
objectKind string required —
domain string required The product domain the object belongs to.
workbench string required The workbench the object is worked on in, which is not its domain.
revision RevisionId required The revision the projected fields were read from.
tenant TenantId required —

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 | | -------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------- | --- | | ActionAuditRow.actorId | ActorId | — | | ActionAuditRow.grant | string | null | — | | BulkActionRequest.actor | ActorRef | — | | DelegationGrant.grantId | string | — | | DelegationGrant.scopeKinds | readonly WorkKind[] | Kinds the delegate may act on. Empty means the grant covers none. | | DelegationGrant.scopeQueues | readonly string[] | Queues the grant covers. Empty means every queue the delegator holds. | | grantAdmits | function | Whether a grant admits this reader at this moment. | | InboxActionRequest.actor | ActorRef | — | | InboxReader.actor | ActorRef | — | | InboxReader.tenant | TenantId | — | | QueueGrant.grantedAt | Instant | — | | QueueGrant.grantedBy | ActorId | Who granted it. A grant nobody made is a grant nobody can be asked about. | | QueueGrant.grantId | string | — | | SavedQueue.grants | readonly QueueGrant[] | — | | SavedQueue.tenant | TenantId | — | | SavedQueueObservation.granterStillHoldsAuthority | Readonly<Record<string, boolean>> | Whether the granter still holds any authority over this queue. | | WorkTarget.tenant | TenantId | — |

Idempotency and concurrency#

Symbol Type Notes
ActionAuditRow.expectedRevision RevisionId —
ActionContext.currentRevision RevisionId The revision the store holds NOW, which the reader may not have seen.
BulkSelectionEntry.expectedRevision RevisionId —
InboxActionRequest.expectedRevision RevisionId The revision the reader was looking at when they decided.
InboxOrderKey.sequence number —
SavedQueue.revision number —
WorkSource.sequence number The source's own position within its stream.
WorkTarget.revision RevisionId The revision the projected fields were read from.

Pagination#

| Symbol | Type | Notes | | ----------------------------- | --------------------- | -------------------------------------------------------------------------- | --- | | cursorBindingFaults | function | What a cursor was minted against, so the minting can be checked (S8.10.d). | | CursorResumption | type | — | | decodeInboxCursor | function | — | | encodeInboxCursor | function | — | | INBOX_CURSOR_REJECTIONS | enumeration | — | | InboxAnswer.cursorRejection | InboxCursorRejection | null | — | | InboxAnswer.nextCursor | string | null | — | | InboxCursorRejection | type | — | | PROJECTION_FAULTS | enumeration | — | | ProjectionFault | type | — | | projectionFaults | function | Check one projected row against the kind it claims to be (S8.10.a). | | resumeInboxCursor | function | Whether a cursor may be resumed against the query now being asked. |

State and failure#

Symbol Type Notes
ACTION_REFUSALS enumeration —
ActionRefusal type —
ADMISSION_REFUSALS enumeration —
AdmissionRefusal type —
AdmissionResult.refused readonly RefusedRow[] —
AXIS_VERDICTS enumeration —
AxisVerdict type —
BulkPlan.refused number —
InboxActionOutcome type —
InboxAnswer.refused readonly RefusedRow[] —
InboxItem.state string The source's own state word, verbatim.
QUEUE_OPEN_REFUSALS enumeration —
QueueOpenRefusal type —
RefusedRow.refusal AdmissionRefusal —

Compatibility#

Symbol Type Notes
CURRENT_VOCABULARY_VERSION constant —
INBOX_PROJECTOR_VERSION constant —
InboxCursor.projectorVersion number —
MigrationRecord.fromVersion number —
MigrationRecord.toVersion number —
QueueVocabulary.oldestReadableVersion number The oldest version this build still carries migration records for.
QueueVocabulary.version number —
SavedQueue.vocabularyVersion number The vocabulary version the filter's values were drawn from.
VocabularyChange.atVersion number The version at which the change took effect.

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/review-inbox.ts