Eve library

Reviewer handoff and temporary delegation

Evidence

Revision 1

On this page

Why a delegation that cannot expire makes the sentence ‘expired delegations stop authorizing actions’ false rather than untested, what a grant has to be before any of its lifecycle questions can be asked of it, why the provenance of the instant an expiry is judged against is part of the answer, what has to have RUN before an expiry has happened, which two facts a revocation carries that an expiry does not, which of a delegate’s unfinished work survives the authority ending and which does not, where a row goes when its ground is withdrawn and nobody is named to take it, why the delegator’s standing has to be read in the present tense, what an omitted scope dimension says, which action no grant may ever confer and which action-and-kind PAIR cannot be expressed as one, at which instant a destination’s six eligibility axes are measured, why a load count that cannot exceed its ceiling is a refusal that can never fire, and which of the ways of attributing a delegated action reads correctly to a person and wrongly to a query.

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

Summary#

  • src/reviewer-handoff.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/reviewer-handoff contract S8.11

Exports#

Symbol Kind Summary
ALL_REVIEWER_HANDOFF_FAULTS constant Every fault kind this module can produce.
ATTRIBUTION_SHAPES enumeration The shapes an attribution can take, including the two that look right.
ATTRIBUTION_SURFACES enumeration Surfaces a delegated action can appear on.
attributionShape function Classify one record against the two actors it should name.
AttributionShape type —
AttributionSurface type —
AudienceNotice interface —
AUDIENCES_ENTITLED_TO_THE_REASON enumeration Audiences the reason may reach: the ones it is ABOUT.
AUDIENCES_FOR_AN_ENDING enumeration Audiences an ENDING must reach, which are not the audiences of a beginning.
AuthorityGrant interface —
AUTHORIZATION_REFUSALS enumeration —
AuthorizationObservation interface What the host says is true, so that this module can disagree with it.
AuthorizationRefusal type —
authorizesDelegatedAction function The function the evidence clause is about: does this grant authorize this action, at this instant, on this clock.
AUTHORIZING_STANDINGS enumeration Only one standing authorizes anything. Named so nothing has to remember.
AVAILABILITY_STANDINGS enumeration Whether somebody can take work, as three values rather than two.
AvailabilityStanding type —
CapacityObservation interface —
CENSUS_MAX_AGE_MINUTES constant How stale a census may be before it is describing a different review.
checkDestination function Decide whether this destination may receive this work, AT effectiveAt (S8.11.b).
CLOCK_SOURCES enumeration Where the instant an expiry is judged against came from.
ClockSource type —
COUNT_TRUSTS enumeration Whether a load count can be believed.
CountTrust type —
DELEGATED_ATTRIBUTION_FAULTS enumeration —
DelegatedAsk interface What is being attempted, in the six dimensions a grant is scoped on.
delegatedAskOf function Build the delegated ask FROM the target, for the same reason.
DelegatedAttributionFault type —
delegatedAttributionFaults function Check what the record says against what happened (S8.11.g).
DelegatedAuthorization type —
DelegatorStanding interface What the delegator holds, NOW.
DESTINATION_AXES enumeration The six axes a destination is judged on.
DESTINATION_REFUSALS enumeration —
DestinationAxis type —
DestinationCandidate interface Everything about a destination that the host knows and this module does not.
DestinationRefusal type —
DestinationRequirement interface —
destinationRequirementOf function Build the destination requirement FROM the handoff's own target.
DestinationVerdict type —
EffectiveActor interface The two actors behind a delegated action, and the grant joining them.
effectiveActorLabel function How a delegated actor is rendered, everywhere, in one order.
GRANT_AUTHORITY_FAULTS enumeration —
GRANT_EVENTS enumeration —
GRANT_LIFECYCLE_FAULTS enumeration —
GRANT_SCOPE_FAULTS enumeration —
GRANT_STANDINGS enumeration Where a grant stands, as six values.
GrantAuthorityContext interface —
GrantAuthorityFault type —
grantAuthorityFaults function Check that the authority being lent was the delegator's to lend (S8.11.e).
GrantEvent type —
GrantLifecycleFault type —
grantLifecycleFaults function Compare the deployment's accounting with what the register actually says (S8.11.f).
grantNotices function Build the notices for one event.
GrantRevocation interface Somebody ending a grant early, which is an act and not a lapse.
GrantScope interface —
GrantScopeFault type —
grantScopeFaults function Judge the grant as written, before anybody's authority is consulted (S8.11.d).
grantStanding function Compute the standing of one grant (S8.11.f).
GrantStanding type —
HANDOFF_DISPOSITIONS enumeration Whether this handoff moves the work or merely covers it.
HANDOFF_NOTICE_AUDIENCES enumeration The parties a handoff or a grant event concerns.
HANDOFF_NOTICE_FAULTS enumeration —
HANDOFF_SCHEMA_FAULTS enumeration —
HANDOFF_TENSES enumeration Where a handoff sits relative to the clock.
HandoffDisposition type —
HandoffFinding interface —
HandoffNoticeAudience type —
HandoffNoticeFault type —
handoffNoticeFaults function Judge a notice set (S8.11.g).
HandoffRecord interface —
HandoffSchemaFault type —
handoffSchemaFaults function Judge the handoff REQUEST, before any ledger row exists (S8.11.a).
HandoffTarget interface —
HandoffTense type —
NONDELEGABLE_PAIRS constant The rule that is a PAIR rather than an action.
nondelegableActions function Actions no grant may confer, DERIVED from what a delegation already means.
NOTICE_KEYS constant —
OnwardPolicy type Whether a grant may be used to cut further grants, and how deep.
PART_OUTCOMES enumeration —
PartOutcome type —
PartResult interface —
PendingWorkRow interface A piece of work whose holder may be holding it on borrowed authority.
PREDECESSOR_RECORDS enumeration Where the previous holder's identity survives the transfer.
PredecessorRecord type —
QualificationRecord interface A competency with an end on it, because competencies lapse.
RecordedAttribution interface —
REFUSAL_AXIS constant Which axis a refusal came from, so a caller can report by axis.
resolveGrant function Look a grant up in the register. A grant is a row, so this can fail.
ReviewerHandoffFault type —
SCOPE_DIMENSIONS enumeration —
ScopeDimension type —
ScopeSelector type One dimension of a grant's reach.
selectorAdmits function Whether a selector admits a value. all admits everything by construction.
ServerClock interface —
SURFACES_REQUIRING_BOTH_ACTORS enumeration Surfaces on which both actors are MANDATORY.
SWEEP_OUTCOMES enumeration —
sweepGrants function Re-evaluate every pending row against the register, now (S8.11.f).
SweepInput interface —
SweepOutcome type —
SweepResult interface —
TRANSFER_FAULTS enumeration —
TRANSFER_ORDER enumeration The order the parts must be applied in.
TRANSFER_PARTS enumeration The parts a handoff actually consists of.
TransferFault type —
transferFaults function Judge what actually happened when the work moved (S8.11.c).
TransferJudgment interface The two verdicts a transfer gets, kept apart on purpose.
TransferOutcome interface —
TransferPart type —
UNRESOLVED_WORK_KINDS enumeration The kinds of loose end a review can be holding when it changes hands.
UnresolvedCensus type What was found when somebody looked, or the fact that nobody did.
UnresolvedItem interface —
UnresolvedWorkKind type —

Shapes#

ALL_REVIEWER_HANDOFF_FAULTS#

Every fault kind this module can produce.

ATTRIBUTION_SHAPES#

The shapes an attribution can take, including the two that look right.

Values: both, delegate-only, delegator-only, delegate-label-over-delegator-id, delegator-label-over-delegate-id, neither

ATTRIBUTION_SURFACES#

Surfaces a delegated action can appear on.

Values: action, audit, activity, notification

attributionShape#

Classify one record against the two actors it should name.

ts
attributionShape(record: RecordedAttribution, effective: EffectiveActor): AttributionShape

AttributionShape#

ts
(typeof ATTRIBUTION_SHAPES)[number];

AttributionSurface#

ts
(typeof ATTRIBUTION_SURFACES)[number];

AudienceNotice#

Field Type Required Notes
audience HandoffNoticeAudience required —
key string required —
carriesTheReason boolean required —

AUDIENCES_ENTITLED_TO_THE_REASON#

Audiences the reason may reach: the ones it is ABOUT.

Values: source, delegator, delegate

AUDIENCES_FOR_AN_ENDING#

Audiences an ENDING must reach, which are not the audiences of a beginning.

Values: delegator, delegate, waiting-parties

AuthorityGrant#

Field Type Required Notes
grantId string required —
tenant TenantId required —
delegator ActorId required —
delegate ActorId required —
scope GrantScope required —
notBefore Instant required —
notAfter Instant required The end in force now, which a revocation does NOT move.
issuedNotAfter Instant required The end the grant was issued with.
reasonCode string required —
delegatorGround EligibilityGround required The ground the delegator held when this was cut. Caps what it confers.
onward OnwardPolicy required —
parentGrantId string | null required Set when this grant was itself cut from another.
depth number required 0 for a grant cut from held authority, 1 for one cut from a grant.
revocation GrantRevocation | null — GrantRevocation required —

AUTHORIZATION_REFUSALS#

Values: clock-is-not-the-servers, grant-has-not-started, grant-has-ended, grant-was-revoked, grant-lapsed-with-its-delegator, grant-is-malformed, action-outside-the-granted-scope, action-is-nondelegable

AuthorizationObservation#

What the host says is true, so that this module can disagree with it.

Field Type Required Notes
clock ServerClock required —
lastSweptAt Instant | null — Instant required When the sweep last ran. Null when it never has.
grants readonly AuthorityGrant[] — AuthorityGrant required —
delegatorsStillHold Readonly<Record<string, boolean>> required —
rows readonly PendingWorkRow[] — PendingWorkRow required —
stillAuthorized readonly string[] required Item ids the deployment is still treating as authorized.
successors Readonly<Record<string, ActorId | null>> — ActorId required —
retroactivelyInvalidated readonly string[] required Completed items the deployment has since unwound.

AuthorizationRefusal#

ts
(typeof AUTHORIZATION_REFUSALS)[number];

authorizesDelegatedAction#

The function the evidence clause is about: does this grant authorize this action, at this instant, on this clock.

ts
authorizesDelegatedAction(grant: AuthorityGrant, ask: DelegatedAsk, clock: ServerClock, delegatorStillHolds: boolean): DelegatedAuthorization

AUTHORIZING_STANDINGS#

Only one standing authorizes anything. Named so nothing has to remember.

Values: active

AVAILABILITY_STANDINGS#

Whether somebody can take work, as three values rather than two.

Values: available, unavailable, unknown

AvailabilityStanding#

ts
(typeof AVAILABILITY_STANDINGS)[number];

CapacityObservation#

Field Type Required Notes
openCount number required Live items the destination already holds, as the HOST counted them.
ceiling number required —
basis CountTrust required —

CENSUS_MAX_AGE_MINUTES#

How stale a census may be before it is describing a different review.

Value: 120

checkDestination#

Decide whether this destination may receive this work, AT effectiveAt (S8.11.b).

ts
checkDestination(requirement: DestinationRequirement, candidate: DestinationCandidate, effectiveAt: Instant): DestinationVerdict

CLOCK_SOURCES#

Where the instant an expiry is judged against came from.

Values: server, client, unknown

ClockSource#

ts
(typeof CLOCK_SOURCES)[number];

COUNT_TRUSTS#

Whether a load count can be believed.

Values: actual, clamped-at-the-ceiling

CountTrust#

ts
(typeof COUNT_TRUSTS)[number];

DELEGATED_ATTRIBUTION_FAULTS#

Values: attributed-to-the-delegate-alone, attributed-to-the-delegator-alone, recorded-under-one-actor-and-labelled-with-the-other, attributed-to-neither-actor, attribution-with-no-grant-to-trace-it-to, attribution-citing-a-grant-the-register-cannot-resolve, attribution-missing-from-a-surface-that-shows-the-action

DelegatedAsk#

What is being attempted, in the six dimensions a grant is scoped on.

Field Type Required Notes
action InboxActionName required —
role AssignmentRole required —
domain string required —
workbench string required —
kind WorkKind required —
objectId string required —

delegatedAskOf#

Build the delegated ask FROM the target, for the same reason.

ts
delegatedAskOf(target: HandoffTarget, action: InboxActionName): DelegatedAsk

DelegatedAttributionFault#

ts
(typeof DELEGATED_ATTRIBUTION_FAULTS)[number];

delegatedAttributionFaults#

Check what the record says against what happened (S8.11.g).

ts
delegatedAttributionFaults(effective: EffectiveActor, records: readonly RecordedAttribution[], grants: readonly AuthorityGrant[]): readonly HandoffFinding[]

DelegatedAuthorization#

ts
| { readonly authorized: true; readonly grantId: string; readonly detail: string }
| { readonly authorized: false; readonly refusal: AuthorizationRefusal; readonly detail: string }

DelegatorStanding#

What the delegator holds, NOW.

Field Type Required Notes
actorId ActorId required —
ground EligibilityGround | null — EligibilityGround required Null when the delegator holds no ground on this work at all.
actions readonly InboxActionName[] — InboxActionName required —
roles readonly AssignmentRole[] — AssignmentRole required —
domains readonly string[] required —
workbenches readonly string[] required —
kinds readonly WorkKind[] — WorkKind required —
objects readonly string[] required —
heldByGrant string | null required Set when the delegator's own authority came from a grant.
stillHeld boolean required Whether the host still recognises this standing at the instant asked.

DESTINATION_AXES#

The six axes a destination is judged on.

Values: role, qualification, object-access, capacity, conflict, availability

DESTINATION_REFUSALS#

Values: destination-is-not-an-active-actor, destination-kind-may-not-hold-work, destination-does-not-hold-the-role, destination-lacks-a-required-qualification, destination-qualification-expires-before-the-handoff-takes-effect, destination-qualification-with-an-unparseable-end, destination-cannot-reach-the-object, destination-is-in-another-tenant, destination-is-at-or-over-its-ceiling, destination-capacity-measured-on-a-clamped-count, destination-authored-the-object, destination-is-recused-from-the-object, destination-reports-to-the-source, destination-availability-is-unknown, destination-is-unavailable, destination-cannot-attest, destination-qualification-not-yet-granted

DestinationAxis#

ts
(typeof DESTINATION_AXES)[number];

DestinationCandidate#

Everything about a destination that the host knows and this module does not.

Field Type Required Notes
actorId ActorId required —
actor ActorRef required —
tenant TenantId required —
active boolean required Whether the account is live. Unread by the product's delegation path.
roles readonly AssignmentRole[] — AssignmentRole required —
qualifications readonly QualificationRecord[] — QualificationRecord required —
mayAccessObject boolean required —
capacity CapacityObservation required —
availability AvailabilityStanding required —
authoredTheObject boolean required —
recusedFromTheObject boolean required —
reportsToTheSource boolean required Whether the destination reports to the source of the handoff.

DestinationRefusal#

ts
(typeof DESTINATION_REFUSALS)[number];

DestinationRequirement#

Field Type Required Notes
tenant TenantId required —
role AssignmentRole required —
kind WorkKind required —
requiredQualifications readonly string[] required Qualification ids the work requires. Empty is allowed and is a decision.

destinationRequirementOf#

Build the destination requirement FROM the handoff's own target.

ts
destinationRequirementOf(target: HandoffTarget, requiredQualifications: readonly string[]): DestinationRequirement

DestinationVerdict#

ts
| { readonly eligible: true; readonly measured: readonly DestinationAxis[]; readonly detail: string; }
| { readonly eligible: false; readonly refusals: readonly HandoffFinding[]; readonly refusedAxes: readonly DestinationAxis[]; }

EffectiveActor#

The two actors behind a delegated action, and the grant joining them.

Field Type Required Notes
acting ActorId required Whose hands.
onBehalfOf ActorId required Whose authority.
grantId string required —

effectiveActorLabel#

How a delegated actor is rendered, everywhere, in one order.

ts
effectiveActorLabel(effective: EffectiveActor): string

GRANT_AUTHORITY_FAULTS#

Values: grant-cut-by-somebody-who-held-nothing, grant-that-outlived-its-delegators-authority, grant-wider-than-the-delegator, grant-conferring-a-stronger-ground-than-the-delegator-holds, onward-grant-from-a-grant-that-refused-it, onward-grant-whose-parent-is-not-the-one-it-names, onward-grant-outliving-its-parent, onward-grant-wider-than-its-parent, onward-chain-past-its-depth-limit, grant-to-an-actor-who-may-not-hold-work, grant-to-an-actor-already-acting-on-the-delegators-authority, grant-that-crosses-a-tenant, grant-that-fills-a-second-quorum-seat, grant-to-an-author-of-the-object, grant-whose-delegate-is-recused, grant-conferring-work-the-delegate-is-not-qualified-for, grant-whose-window-outlives-the-delegates-qualification

GRANT_EVENTS#

Values: granted, revoked, expired, handed-off

GRANT_LIFECYCLE_FAULTS#

Values: standing-computed-from-a-clock-that-is-not-the-servers, sweep-that-has-never-run, expiry-that-was-never-swept, work-still-authorized-by-a-grant-that-ended, in-flight-work-grandfathered-past-its-grant, completed-action-retroactively-invalidated, withdrawn-work-left-with-nowhere-to-go, sole-ground-naming-a-grant-the-register-cannot-resolve, revocation-that-authorized-work-after-it-was-decided, sweep-recorded-as-having-run-in-the-future

GRANT_SCOPE_FAULTS#

Values: grant-with-no-end, grant-with-an-unparseable-window, grant-whose-window-never-opens, grant-longer-than-a-role-change, grant-scope-widened-to-all-with-no-justification, grant-scope-dimension-that-selects-nothing, grant-conferring-a-nondelegable-action, grant-conferring-an-attestation, grant-to-the-delegator-themselves, grant-with-no-reason-code, onward-permitted-with-a-depth-of-zero, grant-with-a-parent-and-a-depth-of-zero, grant-with-no-parent-and-a-nonzero-depth, grant-whose-end-moved-with-no-revocation, revocation-with-no-reason-code, revocation-recorded-under-the-grant-it-revokes, revocation-by-an-erased-identity

GRANT_STANDINGS#

Where a grant stands, as six values.

Values: malformed, revoked, pending, expired, lapsed-with-its-source, active

GrantAuthorityContext#

Field Type Required Notes
grant AuthorityGrant required —
delegator DelegatorStanding required —
delegate DestinationCandidate required —
parent AuthorityGrant | null — AuthorityGrant required The grant this one was cut from, when it names one.
quorumSeats readonly ActorId[] — ActorId required Actors already holding a seat in a quorum decision on this work.
authoredBy readonly ActorId[] — ActorId required Who produced the thing under review.
askRole AssignmentRole required Roles whose holder is deciding, so a conflict binds.
requiredQualifications readonly string[] required Competencies the work requires, which a grant cannot confer.

GrantAuthorityFault#

ts
(typeof GRANT_AUTHORITY_FAULTS)[number];

grantAuthorityFaults#

Check that the authority being lent was the delegator's to lend (S8.11.e).

ts
grantAuthorityFaults(context: GrantAuthorityContext): readonly HandoffFinding[]

GrantEvent#

ts
(typeof GRANT_EVENTS)[number];

GrantLifecycleFault#

ts
(typeof GRANT_LIFECYCLE_FAULTS)[number];

grantLifecycleFaults#

Compare the deployment's accounting with what the register actually says (S8.11.f).

ts
grantLifecycleFaults(observation: AuthorizationObservation): readonly HandoffFinding[]

grantNotices#

Build the notices for one event.

ts
grantNotices(event: GrantEvent): readonly AudienceNotice[]

GrantRevocation#

Somebody ending a grant early, which is an act and not a lapse.

Field Type Required Notes
at Instant required —
by ActorRef required —
reasonCode string required —

GrantScope#

Field Type Required Notes
actions ScopeSelector<InboxActionName> — InboxActionName, ScopeSelector required —
roles ScopeSelector<AssignmentRole> — AssignmentRole, ScopeSelector required —
domains ScopeSelector<string> — ScopeSelector required —
workbenches ScopeSelector<string> — ScopeSelector required —
kinds ScopeSelector<WorkKind> — ScopeSelector, WorkKind required —
objects ScopeSelector<string> — ScopeSelector required —

GrantScopeFault#

ts
(typeof GRANT_SCOPE_FAULTS)[number];

grantScopeFaults#

Judge the grant as written, before anybody's authority is consulted (S8.11.d).

ts
grantScopeFaults(grant: AuthorityGrant): readonly HandoffFinding[]

grantStanding#

Compute the standing of one grant (S8.11.f).

ts
grantStanding(grant: AuthorityGrant, clock: ServerClock, delegatorStillHolds: boolean): GrantStanding

GrantStanding#

ts
(typeof GRANT_STANDINGS)[number];

HANDOFF_DISPOSITIONS#

Whether this handoff moves the work or merely covers it.

Values: permanent-transfer, for-the-duration-of-a-grant

HANDOFF_NOTICE_AUDIENCES#

The parties a handoff or a grant event concerns.

Values: source, destination, delegator, delegate, object-owner, waiting-parties

HANDOFF_NOTICE_FAULTS#

Values: notice-carrying-the-reason-to-a-party-it-is-not-about, ending-that-told-nobody-who-was-waiting, ending-that-did-not-tell-the-delegate, expiry-notice-carrying-a-reason-nobody-gave, notice-set-with-a-duplicated-audience

HANDOFF_SCHEMA_FAULTS#

Values: handoff-to-the-actor-who-already-holds-it, handoff-with-no-reason-code, handoff-with-no-context-for-the-successor, handoff-effective-before-it-was-requested, handoff-with-an-unparseable-instant, unresolved-census-that-was-never-taken, unresolved-census-older-than-the-work-it-describes, unresolved-census-taken-after-the-handoff-took-effect, unresolved-item-with-no-opening-instant, blocking-unresolved-work-handed-over-with-the-deadline-inherited, temporary-handoff-with-no-grant-to-end-it, permanent-transfer-that-names-a-grant, handoff-marked-effective-before-its-instant-arrived, scheduled-handoff-whose-effective-instant-has-passed, handoff-of-an-attestation-requested-by-a-machine-principal, handoff-requested-by-the-destination, handoff-requested-by-an-erased-identity, inherited-deadline-with-no-deadline-to-inherit, deadline-with-no-sla-class-to-measure-it-against

HANDOFF_TENSES#

Where a handoff sits relative to the clock.

Values: scheduled, effective, superseded, withdrawn

HandoffDisposition#

ts
(typeof HANDOFF_DISPOSITIONS)[number];

HandoffFinding#

Field Type Required Notes
kind ReviewerHandoffFault required —
subject string required The handoff, destination, transfer part, grant, work row or record.
detail string required —

HandoffNoticeAudience#

ts
(typeof HANDOFF_NOTICE_AUDIENCES)[number];

HandoffNoticeFault#

ts
(typeof HANDOFF_NOTICE_FAULTS)[number];

handoffNoticeFaults#

Judge a notice set (S8.11.g).

ts
handoffNoticeFaults(event: GrantEvent, notices: readonly AudienceNotice[]): readonly HandoffFinding[]

HandoffRecord#

Field Type Required Notes
handoffId string required —
target HandoffTarget required —
from ActorId required —
to ActorId required —
requestedBy ActorRef required Who asked for it, which is frequently neither party.
requestedAt Instant required —
effectiveAt Instant required When ownership actually moves. May be later than requestedAt.
reasonCode string required —
contextNote string required What the successor needs to know about the work. Not why it moved.
unresolved UnresolvedCensus required —
duePolicy DuePolicyOnReassign required —
due DueCommitment | null — DueCommitment required —
slaClassId string | null required —
disposition HandoffDisposition required —
grantId string | null required Set exactly when the disposition is for-the-duration-of-a-grant.
tense HandoffTense required —

HandoffSchemaFault#

ts
(typeof HANDOFF_SCHEMA_FAULTS)[number];

handoffSchemaFaults#

Judge the handoff REQUEST, before any ledger row exists (S8.11.a).

ts
handoffSchemaFaults(handoff: HandoffRecord, now: Instant): readonly HandoffFinding[]

HandoffTarget#

Field Type Required Notes
tenant TenantId required —
objectId string required —
askId string required The specific ask, so a handoff of one review is not a handoff of all.
role AssignmentRole required —
kind WorkKind required —
domain string required —
workbench string required —

HandoffTense#

ts
(typeof HANDOFF_TENSES)[number];

NONDELEGABLE_PAIRS#

The rule that is a PAIR rather than an action.

nondelegableActions#

Actions no grant may confer, DERIVED from what a delegation already means.

ts
nondelegableActions(): readonly InboxActionName[]

NOTICE_KEYS#

OnwardPolicy#

Whether a grant may be used to cut further grants, and how deep.

ts
| { readonly kind: 'refused' }
| { readonly kind: 'permitted'; readonly maxDepth: number }

PART_OUTCOMES#

Values: applied, skipped, failed

PartOutcome#

ts
(typeof PART_OUTCOMES)[number];

PartResult#

Field Type Required Notes
part TransferPart required —
outcome PartOutcome required —
at Instant | null — Instant required When it was applied. Null for skipped and for failed.
detail string required —

PendingWorkRow#

A piece of work whose holder may be holding it on borrowed authority.

Field Type Required Notes
itemId string required —
holder ActorId required —
soleGroundGrantId string | null required The grant this holder's claim rests on. Null when it rests on nothing.
otherGrounds readonly EligibilityGround[] — EligibilityGround required Grounds the holder has independently of any grant.
startedAt Instant | null — Instant required Set once the holder has begun. Not the same as having finished.
completedAt Instant | null — Instant required Set once the work is done. A completed action is not revisited.

PREDECESSOR_RECORDS#

Where the previous holder's identity survives the transfer.

Values: field, prose-only, absent

PredecessorRecord#

ts
(typeof PREDECESSOR_RECORDS)[number];

QualificationRecord#

A competency with an end on it, because competencies lapse.

Field Type Required Notes
qualificationId string required —
grantedAt Instant required —
expiresAt Instant | null — Instant required Null for a qualification that does not lapse. Rare, and stated.

RecordedAttribution#

Field Type Required Notes
recordId string required —
surface AttributionSurface required —
actorId ActorId | null — ActorId required The id the record is stored under.
displayedLabelOf ActorId | null — ActorId required Whose NAME the surface displays. Frequently not the same person.
onBehalfOf ActorId | null — ActorId required —
grantId string | null required —

REFUSAL_AXIS#

Which axis a refusal came from, so a caller can report by axis.

resolveGrant#

Look a grant up in the register. A grant is a row, so this can fail.

ts
resolveGrant(grants: readonly AuthorityGrant[], grantId: string): AuthorityGrant | null

ReviewerHandoffFault#

ts
| HandoffSchemaFault
| DestinationRefusal
| TransferFault
| GrantScopeFault
| GrantAuthorityFault
| GrantLifecycleFault
| DelegatedAttributionFault
| HandoffNoticeFault

SCOPE_DIMENSIONS#

Values: actions, roles, domains, workbenches, kinds, objects

ScopeDimension#

ts
(typeof SCOPE_DIMENSIONS)[number];

ScopeSelector#

One dimension of a grant's reach.

ts
| { readonly kind: 'all'; readonly justification: string }
| { readonly kind: 'these'; readonly values: readonly T[] }

selectorAdmits#

Whether a selector admits a value. all admits everything by construction.

ts
selectorAdmits(selector: ScopeSelector<T>, value: T): boolean

ServerClock#

Field Type Required Notes
now Instant required —
source ClockSource required —
skewToleranceSeconds number required How far a grant boundary may be from now before the answer is treated as indeterminate. Zero is allowed and means the boundary is taken literally.

SURFACES_REQUIRING_BOTH_ACTORS#

Surfaces on which both actors are MANDATORY.

Values: action, audit

SWEEP_OUTCOMES#

Values: untouched-no-grant-involved, still-authorized, left-with-another-ground, authorization-withdrawn, withdrawn-and-orphaned, completed-under-a-live-grant, completed-after-its-grant-ended, unresolvable-grant

sweepGrants#

Re-evaluate every pending row against the register, now (S8.11.f).

ts
sweepGrants(input: SweepInput): readonly SweepResult[]

SweepInput#

Field Type Required Notes
clock ServerClock required —
grants readonly AuthorityGrant[] — AuthorityGrant required —
delegatorsStillHold Readonly<Record<string, boolean>> required Whether each grant's delegator still holds what they lent. By grant id.
rows readonly PendingWorkRow[] — PendingWorkRow required —
successors Readonly<Record<string, ActorId | null>> — ActorId required Who the host found to take a withdrawn row. By item id.

SweepOutcome#

ts
(typeof SWEEP_OUTCOMES)[number];

SweepResult#

Field Type Required Notes
itemId string required —
outcome SweepOutcome required —
grantId string | null required —
standing GrantStanding | null — GrantStanding required —
holder ActorId | null — ActorId required Who holds it after the sweep. Null when nobody does.
detail string required —

TRANSFER_FAULTS#

Values: transfer-with-a-part-it-never-attempted, transfer-that-applied-a-part-out-of-order, transfer-that-continued-past-a-failed-part, partial-transfer-reported-as-complete, partial-transfer-with-no-compensation, transfer-that-notified-before-it-audited, transfer-whose-ledger-part-produced-no-ledger-pair, transfer-that-moved-work-without-writing-an-audit-row, predecessor-recorded-only-in-prose, predecessor-not-recorded-at-all, carried-context-reattributed-to-the-successor, applied-part-with-no-instant, skipped-part-that-carries-an-instant, compensation-with-no-reason-code, compensation-recorded-before-the-parts-it-undoes

TRANSFER_ORDER#

The order the parts must be applied in.

Values: assignment-ledger, outgoing-handover-grant, carried-context, due-and-sla, audit, notifications

TRANSFER_PARTS#

The parts a handoff actually consists of.

Values: assignment-ledger, outgoing-handover-grant, carried-context, due-and-sla, audit, notifications

TransferFault#

ts
(typeof TRANSFER_FAULTS)[number];

transferFaults#

Judge what actually happened when the work moved (S8.11.c).

ts
transferFaults(handoff: HandoffRecord, outcome: TransferOutcome, move: Reassignment | null): TransferJudgment

TransferJudgment#

The two verdicts a transfer gets, kept apart on purpose.

Field Type Required Notes
findings readonly HandoffFinding[] — HandoffFinding required —
ledger readonly AssignmentFinding[] — AssignmentFinding required —

TransferOutcome#

Field Type Required Notes
handoffId string required —
parts readonly PartResult[] — PartResult required —
reportedComplete boolean required What the caller told the requester.
predecessorRecord PredecessorRecord required —
carriedContextReattributed boolean required Whether carried comments and evidence now name the successor as author.
compensation { readonly at: Instant; readonly reasonCode: string } | null — Instant required What was done about a partial application. Null when nothing was.

TransferPart#

ts
(typeof TRANSFER_PARTS)[number];

UNRESOLVED_WORK_KINDS#

The kinds of loose end a review can be holding when it changes hands.

Values: open-thread, requested-change, pending-evidence, unrun-gate, partial-decision, outstanding-question

UnresolvedCensus#

What was found when somebody looked, or the fact that nobody did.

ts
| { readonly surveyed: true; readonly items: readonly UnresolvedItem[]; readonly surveyedAt: Instant; }
| { readonly surveyed: false; readonly reason: string; }

UnresolvedItem#

Field Type Required Notes
itemId string required —
kind UnresolvedWorkKind required —
openedAt Instant required —
blocksCompletion boolean required Whether the work cannot be completed until this is closed.

UnresolvedWorkKind#

ts
(typeof UNRESOLVED_WORK_KINDS)[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 | | ------------------------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | AuthorityGrant.grantId | string | — | | AuthorityGrant.parentGrantId | string | null | Set when this grant was itself cut from another. | | AuthorityGrant.scope | GrantScope | — | | AuthorityGrant.tenant | TenantId | — | | AUTHORIZATION_REFUSALS | enumeration | — | | AuthorizationObservation.grants | readonly AuthorityGrant[] | — | | AuthorizationObservation.stillAuthorized | readonly string[] | Item ids the deployment is still treating as authorized. | | AuthorizationRefusal | type | — | | authorizesDelegatedAction | function | The function the evidence clause is about: does this grant authorize this action, at this instant, on this clock. | | AUTHORIZING_STANDINGS | enumeration | Only one standing authorizes anything. Named so nothing has to remember. | | DelegatedAuthorization | type | — | | DelegatorStanding.actorId | ActorId | — | | DelegatorStanding.heldByGrant | string | null | Set when the delegator's own authority came from a grant. | | DestinationCandidate.actor | ActorRef | — | | DestinationCandidate.actorId | ActorId | — | | DestinationCandidate.tenant | TenantId | — | | DestinationRequirement.tenant | TenantId | — | | EffectiveActor.grantId | string | — | | effectiveActorLabel | function | How a delegated actor is rendered, everywhere, in one order. | | GRANT_AUTHORITY_FAULTS | enumeration | — | | GRANT_EVENTS | enumeration | — | | GRANT_LIFECYCLE_FAULTS | enumeration | — | | GRANT_SCOPE_FAULTS | enumeration | — | | GRANT_STANDINGS | enumeration | Where a grant stands, as six values. | | GrantAuthorityContext.grant | AuthorityGrant | — | | GrantAuthorityFault | type | — | | grantAuthorityFaults | function | Check that the authority being lent was the delegator's to lend (S8.11.e). | | GrantEvent | type | — | | GrantLifecycleFault | type | — | | grantLifecycleFaults | function | Compare the deployment's accounting with what the register actually says (S8.11.f). | | grantNotices | function | Build the notices for one event. | | GrantScopeFault | type | — | | grantScopeFaults | function | Judge the grant as written, before anybody's authority is consulted (S8.11.d). | | grantStanding | function | Compute the standing of one grant (S8.11.f). | | GrantStanding | type | — | | HandoffRecord.grantId | string | null | Set exactly when the disposition is for-the-duration-of-a-grant. | | HandoffTarget.tenant | TenantId | — | | PendingWorkRow.soleGroundGrantId | string | null | The grant this holder's claim rests on. Null when it rests on nothing. | | QualificationRecord.grantedAt | Instant | — | | RecordedAttribution.actorId | ActorId | null | The id the record is stored under. | | RecordedAttribution.grantId | string | null | — | | resolveGrant | function | Look a grant up in the register. A grant is a row, so this can fail. | | SCOPE_DIMENSIONS | enumeration | — | | ScopeDimension | type | — | | ScopeSelector | type | One dimension of a grant's reach. | | SURFACES_REQUIRING_BOTH_ACTORS | enumeration | Surfaces on which both actors are MANDATORY. | | sweepGrants | function | Re-evaluate every pending row against the register, now (S8.11.f). | | SweepInput.grants | readonly AuthorityGrant[] | — | | SweepResult.grantId | string | null | — |

Idempotency and concurrency#

Not applicable: nothing on this page is retried or applied twice: these are declarations, not operations.

Pagination#

Not applicable: nothing on this page returns a collection a caller reads in pages.

State and failure#

Symbol Type Notes
AUTHORIZATION_REFUSALS enumeration —
AuthorizationRefusal type —
DESTINATION_REFUSALS enumeration —
DestinationRefusal type —
DestinationVerdict type —
PART_OUTCOMES enumeration —
PartOutcome type —
PartResult.outcome PartOutcome —
REFUSAL_AXIS constant Which axis a refusal came from, so a caller can report by axis.
SWEEP_OUTCOMES enumeration —
SweepOutcome type —
SweepResult.outcome SweepOutcome —

Compatibility#

Not applicable: nothing on this page is versioned independently of the package.

Deprecation#

Symbol Type Notes
GRANT_LIFECYCLE_FAULTS enumeration —
GrantLifecycleFault type —
grantLifecycleFaults function Compare the deployment's accounting with what the register actually says (S8.11.f).

Evidence#

  • evidence/v1-workbenches/workbench-kit-export-map.json
  • libs/oshun/workbench-kit/src/reviewer-handoff.ts