Eve library

Concurrency, history and semantic diff

Evidence

Revision 1

On this page

The precondition a mutable command must state, the conflict a client can recover from, the retry that may not refresh the revision it is retrying, the immutable history all three are written into, and the six adapters that say what changed between two of its revisions — plus the restore that appends rather than rewinds, the score vector whose absences stay absent, and the propagation that answers what else a moved dependency made wrong.

Generated from libs/oshun/workbench-kit/src/concurrency.ts, libs/oshun/workbench-kit/src/diff.ts, libs/oshun/workbench-kit/src/restore.ts, libs/oshun/workbench-kit/src/revisions.ts, libs/oshun/workbench-kit/src/scores.ts, libs/oshun/workbench-kit/src/staleness.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: S2.3 / S2.4 / S2.5 / S2.6 / S2.8 / S2.12. Do not edit by hand.

Summary#

  • src/concurrency.ts
  • src/diff.ts
  • src/restore.ts
  • src/revisions.ts
  • src/scores.ts
  • src/staleness.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/concurrency contract S2.3
@oshun/workbench-kit/diff contract S2.5
@oshun/workbench-kit/restore contract S2.6
@oshun/workbench-kit/revisions contract S2.4
@oshun/workbench-kit/scores contract S2.8
@oshun/workbench-kit/staleness contract S2.12

Exports#

Symbol Kind Summary
ABSENT constant —
ADAPTER_VERSION constant —
AdapterOutput type What an adapter under test hands back. Deliberately loose — a real adapter returns whatever it likes, and that is the thing being caught.
adoptSentinel function The ONE place a legacy sentinel becomes a non-value.
AffectedResult interface —
aggregate function A mean, with what it left out attached (S2.8.e).
AggregateOutcome type —
AggregateView interface The part of an S2.10 aggregate this check needs, restated narrowly.
ancestryOf function The ancestors of one revision, nearest first.
AncestryResult type —
APPLICATION_FAULT_KINDS enumeration —
ApplicationFault interface —
ApplicationFaultKind type —
applyGovernedOperation function The only lawful way a stored revision changes.
applyPrecondition function The total function every path runs, and the only one (S2.3.b, S2.3.e).
applyThresholds function Derive verdicts, and hand the readings back untouched (S2.8.d).
assembleDiff function Order, redact and summarize whatever the adapters produced.
ATTEMPT_FAILURES enumeration Why an attempt did not succeed, from the client's point of view.
AttemptFailure type —
auditBulkRequest function Refuse a multi-subject request that is not fully checked.
auditCommandSchemas function Check every declared command against the precondition rules (S2.3.a, S2.3.e).
authorizeRestore function Decide whether a restore may proceed (S2.6.a).
BinaryField interface —
BinaryMetadata interface —
BranchPoint interface —
BulkItemPrecondition interface The precondition an item in a bulk or import request carries.
CanonicalizationFailure type —
canonicalize function The exact bytes a content hash is taken over.
CHANGE_TYPES enumeration What happened, as a closed vocabulary.
ChangeType type —
checkHistoryIntegrity function Every way a history can be wrong, checked at once (S2.4.d).
CommandSchema interface One command, described well enough to be checked without running it.
COMPARABILITY_FAULTS enumeration —
ComparabilityFault interface —
ComparabilityFaultKind type —
comparabilityFaults function Every reason two readings cannot be put on the same axis.
CompareAndSetRequest interface The write a persistence layer performs, and the shape it must perform it in.
CompareAndSetResult type —
compareIntent function —
compareOperations function The total order every diff is returned in.
CONCURRENCY_VIOLATION_KINDS enumeration —
ConcurrencyViolation interface —
ConcurrencyViolationKind type —
CONFLICT_CODES constant The registered error code each conflict kind is reported as.
CONFLICT_KINDS enumeration —
conflictEnvelope function Turn a conflict into the public error envelope a client receives.
ConflictEnvelopeOptions interface —
ConflictKind type —
ConflictReport interface Everything a conflict has to carry to be recoverable (S2.3.c).
ConflictTarget interface Which write, out of everything the request asked for, could not be applied.
ContentBinding type What a revision's content IS, from the history's point of view.
ContentHasher type A digest function the host supplies.
copyableIntent function The payload, for a "copy my text" affordance.
CreateAuthorization interface What makes a create-if-absent something other than a blind write.
createIfAbsent function The precondition a create carries, or a refusal.
DEPENDENCY_KINDS enumeration The eight things whose movement can invalidate a gate result.
DependencyChangeEvent interface —
DependencyGraph interface The graph, as the walker reads it.
DependencyKind type —
DependencyNode interface —
DependentResult interface A gate result that rests on a dependency. The leaf of the graph.
DerivedVerdict interface —
DIFF_ADAPTERS enumeration —
DIFF_SIGNIFICANCE enumeration Whether a change is to the WORK or to how it is displayed.
DiffAdapterKind type —
DiffAnchors interface Where an operation happened, at both ends.
diffBinaryMetadata function Compare what is comparable about two blobs (S2.5.g).
DiffContext interface —
diffGraph function Compare a graph (S2.5.e).
diffList function Compare a list (S2.5.c).
DiffOperation interface —
DiffPage interface —
DiffProvenance interface —
DiffResult interface —
DiffScalar type A value simple enough to show in a diff row.
diffScalarField function Compare one field (S2.5.b).
DiffSignificance type —
DiffSummary interface —
diffTimeline function Compare two timelines (S2.5.f).
diffTree function Compare a tree (S2.5.d).
diffValue function —
DiffValue type One side of a comparison.
EVENT_VIOLATION_KINDS enumeration —
EventViolation interface —
EventViolationKind type —
everyNonValueVector function A corpus containing every non-value state, for probing an adapter.
expectRevision function The precondition an update carries.
Fabrication interface —
FABRICATION_KINDS enumeration —
FabricationKind type —
FieldValue type —
GOVERNED_MUTABLE_FIELDS constant Fields a governed operation may touch, exposed so a store can allow-list them.
GOVERNED_OPERATIONS enumeration —
GovernedOperation type —
GovernedOperationKind type —
GovernedOutcome type —
GraphEdge interface —
GraphField interface —
GraphNode interface —
HashVerification type —
HISTORY_HARM_KINDS enumeration —
HISTORY_VIOLATION_KINDS enumeration —
HistoryHarm interface —
HistoryHarmKind type —
historyHarms function Compare the history before and after a restore, and report anything that was not a pure append (S2.6.e).
HistoryViolation interface —
HistoryViolationKind type —
ImmutabilityBreach interface —
immutabilityBreaches function Catch a revision that changed in a way no governed operation can produce.
INTENT_SUPPORT_SCOPE constant The grant a support agent needs to read somebody else's rejected submission.
IntentComparison interface The two sides a compare view needs, and the fact that they differ.
IntentSupportOutcome type —
invalidates function Whether this mutation of this kind is one that propagates.
INVALIDATION_REGISTRY constant The mutations this platform knows about, and what each one does.
INVALIDATION_VIOLATION_KINDS enumeration —
InvalidationViolation interface —
InvalidationViolationKind type —
IrreversibleEffect interface Something the restored revision would cause that cannot be taken back.
isIntentExpired function Whether a preserved intent may still be offered at now.
LegalHold interface A legal hold, which BLOCKS a tombstone.
Lineage type Where a revision came from.
LINEAGE_KINDS enumeration —
LineageKind type —
listCanDetectMoves function Whether a list comparison could have detected a move at all.
ListField interface —
ListItem interface —
longestCommonSubsequence function The longest common subsequence, as a table.
markStale function Turn a walk into marks (S2.12.d).
MAX_DIFF_PAGE constant —
measured function —
MUTATION_PATHS enumeration Every route a change reaches storage through.
MutationPath type —
MutationType interface One way a dependency can change, and whether it matters.
nodeKey function —
NON_VALUE_STATES enumeration Every way a score can not be a number, named.
nonValue function —
NonValueState type —
NOT_COUNTED_STATES enumeration States that mean "this dimension does not apply", rather than "we do not know".
NULL_VALUE constant —
ObservedState type What storage says is there now.
operationIdOf function The deterministic id. Path first, so ids sort the way operations do.
OutboxEvent interface An event the restore must publish, staged in the same write.
paginate function A page of a stably-ordered diff.
parentsOf function Every revision this one names as a parent, in one shape for the walkers.
parsePrecondition function Parse a precondition from the wire, closed-shape.
parseScoreReading function Round-trip a reading through JSON without an absence becoming a number.
PlannedRestore interface —
planRestore function Build the append that performs the restore (S2.6.d, S2.6.f).
Precondition type —
PRECONDITION_MODES enumeration The two ways a mutable command may state what it expects to be true.
preconditionEquals function Two preconditions are the same precondition.
PreconditionEvaluatedAt type When a precondition is compared against storage.
PreconditionMode type —
preconditionOfTransition function The precondition a stage transition carries (S2.1 -> S2.3.e).
PreconditionOutcome type —
preserveIntent function Keep a rejected submission, or refuse to.
PreserveIntentInput interface —
previewRestore function Everything a person needs before agreeing to a restore (S2.6.b).
probeAdapter function Run a UI or BFF adapter over a corpus containing every non-value, and report what it fabricated (S2.8.f).
propagate function Walk from a changed dependency to everything that rests on it (S2.12.c).
PropagationLimits interface —
PropagationOutcome type A walk that finished, or one that did not and says where to resume.
ProtectedField interface A field a restore may not silently overwrite.
Quantity interface A quantity with a unit.
RecomputeConstraints interface —
recomputeKey function The key two replays of one event must agree on.
RecomputeRouting type —
reconcile function Find what propagation missed, by comparing stored versions (S2.12.f).
RECONCILIATION_FINDING_KINDS enumeration —
ReconciliationFinding interface —
ReconciliationFindingKind type —
ReconstructedHistory interface —
reconstructHistory function Derive everything about the shape of a history (S2.4.f).
redact function Hide values, never operations.
REDACTION_REASONS enumeration —
RedactionPolicy interface —
RedactionReason type —
RejectedIntent interface A submission that was not applied, kept so the person who made it can get it back.
repairPlan function The versions a repair pass should re-emit for.
RESTORE_EVENT_KINDS enumeration —
RESTORE_REFUSALS enumeration —
RestoreAuthorization type —
RestoreEventKind type —
RestorePlanInput interface —
RestorePlanOutcome type —
RestorePolicy interface —
restorePrecondition function The precondition a restore must carry (S2.3.e, and the sharp edge in S2.6).
RestorePreview interface —
RestorePreviewInput interface —
RestoreRefusal interface —
RestoreRefusalKind type —
RestoreRequest interface —
restoreTargetsHead function Whether a restore's precondition names the head rather than the source.
ResumedRequest interface A submission rebuilt from a preserved intent, ready to be sent again.
resumeIntent function Recover a rejected submission — the only route from an intent to a write.
ResumeOutcome type —
RETRY_DISPOSITIONS enumeration Whether a failed attempt may be re-sent by machinery rather than by a person.
RETRY_VIOLATION_KINDS enumeration —
RetryAttempt interface One send of one request.
retryDecision function Decide whether machinery may send this again (S2.3.f).
RetryDecision type —
RetryDisposition type —
RetryViolation interface —
RetryViolationKind type —
retryViolations function Catch a retry that changed something it may not change.
RevisionContribution interface Whose words these are, when they are not the author's (S8.3.e).
RevisionRecord interface One revision, as it is stored.
RevisionStore interface A store that can perform the comparison and the write as ONE indivisible step.
RIGHTS_IMPACTS enumeration —
RightsImpact interface Material in the source revision whose permission has changed since.
RightsImpactKind type —
routeRecomputation function Decide what to do about one stale mark (S2.12.e).
ROUTING_OUTCOMES enumeration —
RoutingOutcome type —
SafeCurrentMetadata interface What a caller may be told about the current state without being allowed to read it.
ScalarField interface —
SchemaAudit interface What an audit of a command set found, and what it did not look at.
SCORE_DIRECTIONS enumeration Which way is better.
SCORE_VERDICTS enumeration —
SCORE_VIOLATION_KINDS enumeration —
ScoreApplicability interface Where the dimension applies. Empty means everywhere in its workbench.
ScoredDimension interface —
ScoreDimensionSpec interface —
ScoreDirection type —
ScoreProvenance interface Everything that decides what a number MEANS.
ScoreReading type —
ScoreRow interface A row for an export, a table or a wire payload.
ScoreScale type What the numbers mean, which decides which arithmetic is legal on them.
ScoreUncertainty type How sure the evaluator is, when it can say.
ScoreVector interface A whole vector, as it is stored and passed around.
ScoreVerdict type —
ScoreViolation interface —
ScoreViolationKind type —
SentinelAdoption interface —
SI_UNITS constant —
StaleGate interface A gate whose verdict was reached against content that is about to change.
StaleMark interface —
StoredObservation interface What a dependent result claims to have been answered against.
summarize function Counts, and the three that must never be folded into the others.
supportViewOfIntent function A support agent reading a customer's rejected submission.
Threshold interface —
ThresholdPolicy interface —
TimelineClip interface —
TimelineField interface —
Tombstone interface —
TOMBSTONE_CAUSES enumeration —
TombstoneCause type —
toRow function —
TreeField interface —
TreeNode interface —
TruncationNote interface —
unappliedMarks function Check that propagation landed before the release decision did (S2.12.d).
UnitTable interface Conversion factors to a base unit, per dimension. Extended by the caller.
validateDimensionSpec function —
validateEventStream function Check a node's event stream (S2.12.b).
validateInvalidationRegistry function Check an invalidation registry (S2.12.a).
validateVector function Check a whole vector against the dimensions it claims to score (S2.8.a–c).
verifyArtifactPin function Verify an artifact-backed revision against the digest its reference pins.
verifyContentHash function Verify a revision against the content presented as its own (S2.4.e).
withPreservedIntent function Attach the token that reaches the preserved submission (S2.3.d).

Shapes#

ABSENT#

ADAPTER_VERSION#

Value: 1

AdapterOutput#

What an adapter under test hands back. Deliberately loose — a real adapter returns whatever it likes, and that is the thing being caught.

ts
readonly { readonly dimensionId?: unknown; readonly value?: unknown; readonly state?: unknown; readonly verdict?: unknown; }[]

adoptSentinel#

The ONE place a legacy sentinel becomes a non-value.

ts
adoptSentinel(dimensionId: string, raw: number, sentinels: Readonly<Record<number, NonValueState>>): { readonly reading: ScoreReading; readonly adopted: SentinelAdoption | null }

AffectedResult#

Field Type Required Notes
result DependentResult required —
through readonly DependencyNode[] — DependencyNode required —
depth number required —

aggregate#

A mean, with what it left out attached (S2.8.e).

ts
aggregate(scored: readonly ScoredDimension[], registry: readonly ScoreDimensionSpec[]): AggregateOutcome

AggregateOutcome#

ts
| { readonly outcome: 'aggregated'; readonly mean: number; readonly n: number; readonly excluded: Readonly<Record<string, number>>; }
| { readonly outcome: 'refused'; readonly reason: string }

AggregateView#

The part of an S2.10 aggregate this check needs, restated narrowly.

Field Type Required Notes
at Instant required —
components readonly { readonly gateId: string; readonly runId: string | null; readonly isStale: boolean; }[] required —

ancestryOf#

The ancestors of one revision, nearest first.

ts
ancestryOf(records: readonly RevisionRecord[], revisionId: RevisionId): AncestryResult

AncestryResult#

ts
| { readonly found: true; readonly ancestors: readonly RevisionId[] }
| { readonly found: false; readonly reason: string }

APPLICATION_FAULT_KINDS#

Values: authorized-over-an-unapplied-mark, mark-for-a-result-the-aggregate-does-not-have, mark-newer-than-the-aggregate

ApplicationFault#

Field Type Required Notes
kind ApplicationFaultKind required —
subject string required —
detail string required —

ApplicationFaultKind#

ts
(typeof APPLICATION_FAULT_KINDS)[number];

applyGovernedOperation#

The only lawful way a stored revision changes.

ts
applyGovernedOperation(record: RevisionRecord, operation: GovernedOperation): GovernedOutcome

applyPrecondition#

The total function every path runs, and the only one (S2.3.b, S2.3.e).

ts
applyPrecondition(precondition: Precondition, observed: ObservedState, target: ConflictTarget): PreconditionOutcome

applyThresholds#

Derive verdicts, and hand the readings back untouched (S2.8.d).

ts
applyThresholds(vector: ScoreVector, registry: readonly ScoreDimensionSpec[], policy: ThresholdPolicy): readonly DerivedVerdict[]

assembleDiff#

Order, redact and summarize whatever the adapters produced.

ts
assembleDiff(operations: readonly DiffOperation[], policy: RedactionPolicy = {}): DiffResult

ATTEMPT_FAILURES#

Why an attempt did not succeed, from the client's point of view.

Values: unknown-outcome, conflict, refused

AttemptFailure#

ts
(typeof ATTEMPT_FAILURES)[number];

auditBulkRequest#

Refuse a multi-subject request that is not fully checked.

ts
auditBulkRequest(operation: string, items: readonly BulkItemPrecondition[]): readonly ConcurrencyViolation[]

auditCommandSchemas#

Check every declared command against the precondition rules (S2.3.a, S2.3.e).

ts
auditCommandSchemas(schemas: readonly CommandSchema[]): SchemaAudit

authorizeRestore#

Decide whether a restore may proceed (S2.6.a).

ts
authorizeRestore(request: RestoreRequest, policy: RestorePolicy, history: readonly RevisionRecord[], previewOperations: readonly DiffOperation[] = []): RestoreAuthorization

BinaryField#

Field Type Required Notes
path readonly string[] required —
before BinaryMetadata required —
after BinaryMetadata required —

BinaryMetadata#

Field Type Required Notes
digest string required —
byteLength number required —
mediaType string required —
width number | null required —
height number | null required —
durationSeconds number | null required —
codec string | null required —
channels number | null required —
embedded Readonly<Record<string, DiffScalar>> — DiffScalar required Embedded metadata a tool wrote: EXIF, ID3, XMP. Compared key by key.
provenance string | null required Where the bytes came from, when known.
available boolean required False when the artifact can no longer be retrieved.

BranchPoint#

Field Type Required Notes
at RevisionId required The revision two or more children descend from.
children readonly RevisionId[] — RevisionId required —

BulkItemPrecondition#

The precondition an item in a bulk or import request carries.

Field Type Required Notes
itemKey string required —
precondition Precondition required —

CanonicalizationFailure#

ts
| 'non-finite-number'
| 'undefined-value'
| 'function-value'
| 'symbol-value'
| 'bigint-value'
| 'circular-reference'

canonicalize#

The exact bytes a content hash is taken over.

ts
canonicalize(value: unknown): ParseResult<string>

CHANGE_TYPES#

What happened, as a closed vocabulary.

Values: added, removed, changed, moved, reordered, replaced, split, merged

ChangeType#

ts
(typeof CHANGE_TYPES)[number];

checkHistoryIntegrity#

Every way a history can be wrong, checked at once (S2.4.d).

ts
checkHistoryIntegrity(records: readonly RevisionRecord[]): readonly HistoryViolation[]

CommandSchema#

One command, described well enough to be checked without running it.

Field Type Required Notes
operation string required —
path MutationPath required —
mutates boolean required False for a query. A read that declares a precondition is refused too.
preconditionField string | null required The request field carrying the , or null if it has none.
perItem boolean required True when each item in the request carries its own. Required for bulk/import.
evaluatedAt PreconditionEvaluatedAt required —
retry RetryDisposition required —
idempotencyKeyField string | null required The request field carrying the idempotency key, or null.

COMPARABILITY_FAULTS#

Values: different-dimension, different-unit, different-direction, different-evaluator, different-evaluator-version, different-corpus-version, different-preprocessing, different-model

ComparabilityFault#

Field Type Required Notes
kind ComparabilityFaultKind required —
detail string required —

ComparabilityFaultKind#

ts
(typeof COMPARABILITY_FAULTS)[number];

comparabilityFaults#

Every reason two readings cannot be put on the same axis.

ts
comparabilityFaults(left: ScoredDimension, right: ScoredDimension, registry: readonly ScoreDimensionSpec[]): readonly ComparabilityFault[]

CompareAndSetRequest#

The write a persistence layer performs, and the shape it must perform it in.

Field Type Required Notes
subject EntityId required —
path MutationPath required —
precondition Precondition required —
idempotencyKey string required —
nextRevision RevisionId required —
content TContent required —
writtenAt Instant required When and by whom, supplied by the caller for the same reason the revision is.
writtenBy ActorRef required —

CompareAndSetResult#

ts
| { readonly outcome: 'applied'; readonly revision: RevisionId }
| { readonly outcome: 'already-applied'; readonly revision: RevisionId }
| { readonly outcome: 'conflict'; readonly observed: ObservedState }

compareIntent#

ts
compareIntent(intent: RejectedIntent<TPayload>, current: SafeCurrentMetadata | null, lastSeenContentHash: string | null): IntentComparison<TPayload>

compareOperations#

The total order every diff is returned in.

ts
compareOperations(a: DiffOperation, b: DiffOperation): number

CONCURRENCY_VIOLATION_KINDS#

Values: mutation-without-precondition, read-declares-precondition, duplicate-operation, bulk-precondition-not-per-item, per-item-precondition-on-single-subject-path, deferred-precondition-evaluated-at-submit, replay-without-idempotency-key, replay-on-create-only-path

ConcurrencyViolation#

Field Type Required Notes
kind ConcurrencyViolationKind required —
subject string required —
detail string required —

ConcurrencyViolationKind#

ts
(typeof CONCURRENCY_VIOLATION_KINDS)[number];

CONFLICT_CODES#

The registered error code each conflict kind is reported as.

CONFLICT_KINDS#

Values: stale-revision, already-exists, subject-absent

conflictEnvelope#

Turn a conflict into the public error envelope a client receives.

ts
conflictEnvelope(report: ConflictReport, options: ConflictEnvelopeOptions): ParseResult<PublicErrorEnvelope>

ConflictEnvelopeOptions#

Field Type Required Notes
correlationId CorrelationId required —
registry ErrorRegistry optional Defaults to the registry the kit ships.
docsUrl string | null optional Where the compare-and-reload steps are documented, if anywhere.

ConflictKind#

ts
(typeof CONFLICT_KINDS)[number];

ConflictReport#

Everything a conflict has to carry to be recoverable (S2.3.c).

Field Type Required Notes
kind ConflictKind required —
target ConflictTarget required —
expectedRevision RevisionId | null — RevisionId required The revision the caller expected. Null on a create-if-absent conflict.
current SafeCurrentMetadata | null — SafeCurrentMetadata required What is there now. Null when the subject is absent — there is nothing to show.
intentToken string | null required —

ConflictTarget#

Which write, out of everything the request asked for, could not be applied.

Field Type Required Notes
path MutationPath required —
subject EntityId required —
itemKey string | null required The caller's own key for the item, on a multi-subject path. Null otherwise.
itemIndex number | null required Position in the submitted request, for locating it in a file. Null otherwise.

ContentBinding#

What a revision's content IS, from the history's point of view.

ts
| { readonly kind: 'inline'; readonly contentHash: Sha256Hex }
| { readonly kind: 'artifact'; readonly contentHash: Sha256Hex }
| { readonly kind: 'tombstoned'; readonly contentHash: Sha256Hex; readonly tombstone: Tombstone; }

ContentHasher#

A digest function the host supplies.

ts
(canonical: string) => Sha256Hex;

copyableIntent#

The payload, for a "copy my text" affordance.

ts
copyableIntent(intent: RejectedIntent<TPayload>): TPayload

CreateAuthorization#

What makes a create-if-absent something other than a blind write.

Field Type Required Notes
grant string required —
naturalKey string required —
reason string required —

createIfAbsent#

The precondition a create carries, or a refusal.

ts
createIfAbsent(authorization: CreateAuthorization): ParseResult<Precondition>

DEPENDENCY_KINDS#

The eight things whose movement can invalidate a gate result.

Values: source, model, consent, canon, asset, policy, evaluator, target-configuration

DependencyChangeEvent#

Field Type Required Notes
eventId string required —
node DependencyNode required —
mutation string required —
fromVersion number | null required Null only for the node's first appearance.
toVersion number required —
sequence number required Per-node, monotonic, gapless. The hole a lost event leaves.
at Instant required —
cause string required —

DependencyGraph#

The graph, as the walker reads it.

DependencyKind#

ts
(typeof DEPENDENCY_KINDS)[number];

DependencyNode#

Field Type Required Notes
kind DependencyKind required —
id string required —

DependentResult#

A gate result that rests on a dependency. The leaf of the graph.

Field Type Required Notes
runId string required —
gateId string required —
targetRevision string required —
observedVersion number required The version of the dependency this result was answered against.

DerivedVerdict#

Field Type Required Notes
dimensionId string required —
verdict ScoreVerdict required —
undeterminedBecause NonValueState | null — NonValueState required The state that made it undetermined, when it is. Null otherwise.
policyId string required —
policyVersion number required —
reading ScoreReading required The reading this was derived from, unchanged.

DIFF_ADAPTERS#

Values: scalar, list, tree, graph, timeline, binary-metadata

DIFF_SIGNIFICANCE#

Whether a change is to the WORK or to how it is displayed.

Values: semantic, presentation

DiffAdapterKind#

ts
(typeof DIFF_ADAPTERS)[number];

DiffAnchors#

Where an operation happened, at both ends.

Field Type Required Notes
before StableAnchor | null — StableAnchor required —
after StableAnchor | null — StableAnchor required —

diffBinaryMetadata#

Compare what is comparable about two blobs (S2.5.g).

ts
diffBinaryMetadata(context: DiffContext, field: BinaryField): readonly DiffOperation[]

DiffContext#

Field Type Required Notes
beforeRevision RevisionRef required —
afterRevision RevisionRef required —
actor ActorRef | null — ActorRef optional —

diffGraph#

Compare a graph (S2.5.e).

ts
diffGraph(context: DiffContext, field: GraphField): readonly DiffOperation[]

diffList#

Compare a list (S2.5.c).

ts
diffList(context: DiffContext, field: ListField): readonly DiffOperation[]

DiffOperation#

Field Type Required Notes
operationId string required Deterministic: adapter, path and change type. Two runs produce the same id.
adapter DiffAdapterKind required —
changeType ChangeType required —
significance DiffSignificance required —
path readonly string[] required Stable, sortable address. Rendered by a client; never parsed by one.
summaryKey string required A translation key. A sentence here is text no translator receives.
summaryParams Readonly<Record<string, DiffScalar>> — DiffScalar required Parameters for the key. Scalars only; they cross the same boundary an error does.
anchors DiffAnchors required —
before DiffValue required —
after DiffValue required —
provenance DiffProvenance required —

DiffPage#

Field Type Required Notes
operations readonly DiffOperation[] — DiffOperation required —
nextCursor string | null required The id to resume after. Null when this is the last page.

DiffProvenance#

Field Type Required Notes
beforeRevision RevisionRef required —
afterRevision RevisionRef required —
adapter DiffAdapterKind required —
adapterVersion number required Bumped when an adapter's comparison changes, so a cached diff is invalid.
actor ActorRef | null — ActorRef required Who made this particular change, when the diff spans revisions that can attribute it. Null between two revisions with several authors in between — naming one of them would be a guess presented as a fact.

DiffResult#

Field Type Required Notes
operations readonly DiffOperation[] — DiffOperation required —
summary DiffSummary required —

DiffScalar#

A value simple enough to show in a diff row.

ts
string | number | boolean;

diffScalarField#

Compare one field (S2.5.b).

ts
diffScalarField(context: DiffContext, field: ScalarField): readonly DiffOperation[]

DiffSignificance#

ts
(typeof DIFF_SIGNIFICANCE)[number];

DiffSummary#

Field Type Required Notes
total number required —
semantic number required —
presentation number required —
redacted number required —
inaccessible number required —
unsupported number required —
byChangeType Readonly<Record<ChangeType, number>> — ChangeType required —
byAdapter Readonly<Record<string, number>> required —

diffTimeline#

Compare two timelines (S2.5.f).

ts
diffTimeline(context: DiffContext, field: TimelineField): readonly DiffOperation[]

diffTree#

Compare a tree (S2.5.d).

ts
diffTree(context: DiffContext, field: TreeField): readonly DiffOperation[]

diffValue#

ts
diffValue(value: DiffScalar): DiffValue

DiffValue#

One side of a comparison.

ts
| { readonly kind: 'value'; readonly value: DiffScalar }
| { readonly kind: 'absent' }
| { readonly kind: 'null' }
| { readonly kind: 'default'; readonly value: DiffScalar }
| { readonly kind: 'redacted'; readonly reason: RedactionReason }
| { readonly kind: 'inaccessible'; readonly reason: string }
| { readonly kind: 'unsupported'; readonly reason: string }
| { readonly kind: 'opaque'; readonly digest: string; readonly byteLength: number }

EVENT_VIOLATION_KINDS#

Values: sequence-not-a-positive-integer, duplicate-sequence, sequence-gap, version-chain-broken, version-went-backwards, first-event-with-a-from-version, later-event-without-a-from-version, out-of-order-timestamps

EventViolation#

Field Type Required Notes
kind EventViolationKind required —
subject string required —
detail string required —

EventViolationKind#

ts
(typeof EVENT_VIOLATION_KINDS)[number];

everyNonValueVector#

A corpus containing every non-value state, for probing an adapter.

ts
everyNonValueVector(subjectRevision: RevisionId, provenance: ScoreProvenance, measuredDimensionId = 'dimension:measured'): ScoreVector

expectRevision#

The precondition an update carries.

ts
expectRevision(expected: RevisionId): Precondition

Fabrication#

Field Type Required Notes
kind FabricationKind required —
dimensionId string required —
detail string required —

FABRICATION_KINDS#

Values: invented-a-number-for-a-non-value, dropped-a-non-value-row, changed-a-measured-value, turned-a-non-value-into-a-verdict, reordered-so-a-non-value-sorts-as-zero

FabricationKind#

ts
(typeof FABRICATION_KINDS)[number];

FieldValue#

ts
| { readonly present: false }
| { readonly present: true; readonly value: DiffScalar | null | Quantity }

GOVERNED_MUTABLE_FIELDS#

Fields a governed operation may touch, exposed so a store can allow-list them.

GOVERNED_OPERATIONS#

Values: tombstone-content, place-legal-hold, release-legal-hold

GovernedOperation#

ts
| { readonly operation: 'tombstone-content'; readonly tombstone: Tombstone }
| { readonly operation: 'place-legal-hold'; readonly hold: LegalHold }
| { readonly operation: 'release-legal-hold'; readonly holdId: string; readonly authority: string; readonly reason: string; }

GovernedOperationKind#

ts
(typeof GOVERNED_OPERATIONS)[number];

GovernedOutcome#

ts
| { readonly outcome: 'applied'; readonly record: RevisionRecord }
| { readonly outcome: 'refused'; readonly reason: string }

GraphEdge#

Field Type Required Notes
edgeId string required —
fromNode string required —
fromPort string required —
toNode string required —
toPort string required —

GraphField#

Field Type Required Notes
path readonly string[] required —
before { readonly nodes: readonly GraphNode[]; readonly edges: readonly GraphEdge[] } — GraphEdge, GraphNode required —
after { readonly nodes: readonly GraphNode[]; readonly edges: readonly GraphEdge[] } — GraphEdge, GraphNode required —

GraphNode#

Field Type Required Notes
nodeId string required —
type string required —
ports readonly string[] required —
properties Readonly<Record<string, DiffScalar>> — DiffScalar required —
layout Readonly<Record<string, DiffScalar>> — DiffScalar required Layout only. Never a semantic change, however much it moves.

HashVerification#

ts
| { readonly verdict: 'verified' }
| { readonly verdict: 'tampered'; readonly recorded: Sha256Hex; readonly computed: Sha256Hex }
| { readonly verdict: 'tombstoned'; readonly recorded: Sha256Hex }
| { readonly verdict: 'artifact-pin-verified' }
| { readonly verdict: 'artifact-pin-mismatch'; readonly recorded: Sha256Hex; readonly pinned: Sha256Hex; }
| { readonly verdict: 'uncanonicalizable'; readonly reason: string }

HISTORY_HARM_KINDS#

Values: revision-removed, revision-mutated, parent-reassigned, more-than-one-revision-added, nothing-added, added-revision-does-not-follow-the-head

HISTORY_VIOLATION_KINDS#

Values: duplicate-revision-id, self-parent, missing-parent, cross-entity-parent, cross-tenant-parent, cycle, no-root, multiple-roots, duplicate-sequence, sequence-gap, sequence-not-after-parent, timestamp-before-parent, merge-with-one-parent, duplicate-merge-parent, merge-base-not-an-ancestor, schema-version-regression, empty-reason, contribution-credited-to-its-own-author, contribution-that-names-no-proposal

HistoryHarm#

Field Type Required Notes
kind HistoryHarmKind required —
subject string required —
detail string required —

HistoryHarmKind#

ts
(typeof HISTORY_HARM_KINDS)[number];

historyHarms#

Compare the history before and after a restore, and report anything that was not a pure append (S2.6.e).

ts
historyHarms(before: readonly RevisionRecord[], after: readonly RevisionRecord[], expectedHead: RevisionId): readonly HistoryHarm[]

HistoryViolation#

Field Type Required Notes
kind HistoryViolationKind required —
subject string required —
detail string required —

HistoryViolationKind#

ts
(typeof HISTORY_VIOLATION_KINDS)[number];

ImmutabilityBreach#

Field Type Required Notes
field string required —
before string required —
after string required —

immutabilityBreaches#

Catch a revision that changed in a way no governed operation can produce.

ts
immutabilityBreaches(before: RevisionRecord, after: RevisionRecord): readonly ImmutabilityBreach[]

INTENT_SUPPORT_SCOPE#

The grant a support agent needs to read somebody else's rejected submission.

Value: 'support:read-intent'

IntentComparison#

The two sides a compare view needs, and the fact that they differ.

Field Type Required Notes
intentToken string required —
submittedPayload TPayload required —
submittedAgainst Precondition required —
current SafeCurrentMetadata | null — SafeCurrentMetadata required —
contentUnchanged boolean required True when the current content hash equals the one the caller last saw.
preconditionNowHolds boolean required True when the current head is the revision the submission expected.

IntentSupportOutcome#

ts
| { readonly outcome: 'granted'; readonly intent: RejectedIntent<TPayload> }
| { readonly outcome: 'denied'; readonly reason: string }
| { readonly outcome: 'expired'; readonly expiredAt: Instant }

invalidates#

Whether this mutation of this kind is one that propagates.

ts
invalidates(registry: readonly MutationType[], node: DependencyNode, mutation: string): MutationType | null

INVALIDATION_REGISTRY#

The mutations this platform knows about, and what each one does.

INVALIDATION_VIOLATION_KINDS#

Values: unknown-dependency-kind, duplicate-mutation-type, mutation-with-no-reason, kind-with-no-invalidating-mutation, kind-with-no-benign-mutation

InvalidationViolation#

Field Type Required Notes
kind InvalidationViolationKind required —
subject string required —
detail string required —

InvalidationViolationKind#

ts
(typeof INVALIDATION_VIOLATION_KINDS)[number];

IrreversibleEffect#

Something the restored revision would cause that cannot be taken back.

Field Type Required Notes
effect EffectKind required —
trigger string required —
detail string required —

isIntentExpired#

Whether a preserved intent may still be offered at now.

ts
isIntentExpired(intent: RejectedIntent<TPayload>, now: Instant): boolean

LegalHold#

A legal hold, which BLOCKS a tombstone.

Field Type Required Notes
holdId string required —
authority string required —
placedAt Instant required —
reason string required —

Lineage#

Where a revision came from.

ts
| { readonly kind: 'root' }
| { readonly kind: 'linear'; readonly parent: RevisionId; readonly base: RevisionId | null }
| { readonly kind: 'merge'; readonly parents: readonly RevisionId[]; readonly base: RevisionId }

LINEAGE_KINDS#

Values: root, linear, merge

LineageKind#

ts
(typeof LINEAGE_KINDS)[number];

listCanDetectMoves#

Whether a list comparison could have detected a move at all.

ts
listCanDetectMoves(field: ListField): boolean

ListField#

Field Type Required Notes
path readonly string[] required —
before readonly ListItem[] — ListItem required —
after readonly ListItem[] — ListItem required —
ordered boolean required False when the order carries no meaning — a tag set, a permission list.

ListItem#

Field Type Required Notes
key string | null required The item's own stable id. Null when the list has no item identity.
value DiffScalar required —

longestCommonSubsequence#

The longest common subsequence, as a table.

ts
longestCommonSubsequence(left: readonly string[], right: readonly string[]): readonly { readonly leftIndex: number; readonly rightIndex: number }[]

markStale#

Turn a walk into marks (S2.12.d).

ts
markStale(event: DependencyChangeEvent, affected: readonly AffectedResult[], registryEntry: MutationType, markedAt: Instant): readonly StaleMark[]

MAX_DIFF_PAGE#

Value: 200

measured#

ts
measured(raw: number, uncertainty: ScoreUncertainty | null = null): ScoreReading

MUTATION_PATHS#

Every route a change reaches storage through.

Values: single, bulk, import, job, restore, transition, compatibility

MutationPath#

ts
(typeof MUTATION_PATHS)[number];

MutationType#

One way a dependency can change, and whether it matters.

Field Type Required Notes
kind DependencyKind required —
mutation string required —
invalidates boolean required —
why string required —

nodeKey#

ts
nodeKey(node: DependencyNode): string

NON_VALUE_STATES#

Every way a score can not be a number, named.

Values: absent, not-applicable, insufficient-data, unsupported, unavailable, failed, stale, redacted

nonValue#

ts
nonValue(state: NonValueState, detail: string): ScoreReading

NonValueState#

ts
(typeof NON_VALUE_STATES)[number];

NOT_COUNTED_STATES#

States that mean "this dimension does not apply", rather than "we do not know".

Values: not-applicable, unsupported

NULL_VALUE#

ObservedState#

What storage says is there now.

ts
| { readonly present: false }
| { readonly present: true; readonly revision: RevisionId; readonly updatedAt: Instant; readonly updatedBy: ActorRef; readonly stage: string | null; readonly contentHash: string | null; }

operationIdOf#

The deterministic id. Path first, so ids sort the way operations do.

ts
operationIdOf(adapter: DiffAdapterKind, path: readonly string[], changeType: ChangeType): string

OutboxEvent#

An event the restore must publish, staged in the same write.

Field Type Required Notes
kind RestoreEventKind required —
subject EntityId required —
revisionId RevisionId required —
payloadKey string required —
detail string required —

paginate#

A page of a stably-ordered diff.

ts
paginate(operations: readonly DiffOperation[], cursor: string | null, pageSize: number = MAX_DIFF_PAGE): DiffPage

parentsOf#

Every revision this one names as a parent, in one shape for the walkers.

ts
parentsOf(lineage: Lineage): readonly RevisionId[]

parsePrecondition#

Parse a precondition from the wire, closed-shape.

ts
parsePrecondition(input: unknown): ParseResult<Precondition>

parseScoreReading#

Round-trip a reading through JSON without an absence becoming a number.

ts
parseScoreReading(input: unknown): ScoreReading | null

PlannedRestore#

Field Type Required Notes
revision RevisionRecord required The revision to append. Nothing existing is touched.
outbox readonly OutboxEvent[] — OutboxEvent required Written in the SAME transaction as the revision, or not at all.
precondition Precondition required —
idempotencyKey string required —
invalidatedGates readonly string[] required The gates whose verdicts the restore invalidates.

planRestore#

Build the append that performs the restore (S2.6.d, S2.6.f).

ts
planRestore(input: RestorePlanInput): RestorePlanOutcome

Precondition#

ts
| { readonly mode: 'expect-revision'; readonly expected: RevisionId }
| { readonly mode: 'create-if-absent'; readonly authorization: CreateAuthorization }

PRECONDITION_MODES#

The two ways a mutable command may state what it expects to be true.

Values: expect-revision, create-if-absent

preconditionEquals#

Two preconditions are the same precondition.

ts
preconditionEquals(left: Precondition, right: Precondition): boolean

PreconditionEvaluatedAt#

When a precondition is compared against storage.

ts
'submit' | 'apply';

PreconditionMode#

ts
(typeof PRECONDITION_MODES)[number];

preconditionOfTransition#

The precondition a stage transition carries (S2.1 -> S2.3.e).

ts
preconditionOfTransition(command: { readonly expectedRevision: string; }): ParseResult<Precondition>

PreconditionOutcome#

ts
| { readonly outcome: 'proceed-update'; readonly from: RevisionId }
| { readonly outcome: 'proceed-create'; readonly naturalKey: string }
| { readonly outcome: 'conflict'; readonly conflict: ConflictReport }

preserveIntent#

Keep a rejected submission, or refuse to.

ts
preserveIntent(input: PreserveIntentInput<TPayload>): ParseResult<RejectedIntent<TPayload>>

PreserveIntentInput#

Field Type Required Notes
intentToken string required —
operation string required —
subject EntityId required —
path MutationPath required —
precondition Precondition required —
payload TPayload required —
submittedAt Instant required —
submittedBy ActorRef required —
expiresAt Instant required —

previewRestore#

Everything a person needs before agreeing to a restore (S2.6.b).

ts
previewRestore(input: RestorePreviewInput): RestorePreview

probeAdapter#

Run a UI or BFF adapter over a corpus containing every non-value, and report what it fabricated (S2.8.f).

ts
probeAdapter(adapter: (vector: ScoreVector, registry: readonly ScoreDimensionSpec[]) => AdapterOutput, vector: ScoreVector, registry: readonly ScoreDimensionSpec[]): readonly Fabrication[]

propagate#

Walk from a changed dependency to everything that rests on it (S2.12.c).

ts
propagate(root: DependencyNode, toVersion: number, graph: DependencyGraph, limits: PropagationLimits): PropagationOutcome

PropagationLimits#

Field Type Required Notes
maxDepth number required —
maxFanOut number required Per node. Exceeding it truncates that node's expansion, loudly.
pageSize number required Total results to return in one page.

PropagationOutcome#

A walk that finished, or one that did not and says where to resume.

ts
| { readonly complete: true; readonly affected: readonly AffectedResult[]; readonly visited: number; readonly cycles: readonly string[]; }
| { readonly complete: false; readonly affected: readonly AffectedResult[]; readonly visited: number; readonly cycles: readonly string[]; readonly truncated: readonly TruncationNote[]; readonly resumeFrom: readonly DependencyNode[]; }

ProtectedField#

A field a restore may not silently overwrite.

Field Type Required Notes
path readonly string[] required —
reason string required —
overrideGrant string | null required —

Quantity#

A quantity with a unit.

Field Type Required Notes
amount number required —
unit string required —

RecomputeConstraints#

Field Type Required Notes
estimatedCost number required What one recomputation of this result costs, in whatever unit the deployment counts.
budgetRemaining number required —
providerAvailable boolean required False when the provider the evaluator needs is unreachable or unconfigured.
requiresHuman boolean required True when a human has to answer the gate; a machine cannot re-do that.
evaluatorId string required The evaluator that would run. Part of the idempotency key.
evaluatorVersion number required —

recomputeKey#

The key two replays of one event must agree on.

ts
recomputeKey(mark: StaleMark, constraints: RecomputeConstraints): string

RecomputeRouting#

ts
| { readonly outcome: 'queued'; readonly idempotencyKey: string; readonly estimatedCost: number; }
| { readonly outcome: 'requires-explicit-action'; readonly reasonKey: string; readonly detail: string; readonly who: string; }
| { readonly outcome: 'refused'; readonly reasonKey: string; readonly detail: string }

reconcile#

Find what propagation missed, by comparing stored versions (S2.12.f).

ts
reconcile(observations: readonly StoredObservation[], currentVersions: Readonly<Record<string, number>>): readonly ReconciliationFinding[]

RECONCILIATION_FINDING_KINDS#

Values: missed-event, partial-propagation, observed-version-ahead-of-the-source, mark-for-a-version-that-never-arrived, marked-stale-while-current

ReconciliationFinding#

Field Type Required Notes
kind ReconciliationFindingKind required —
subject string required —
detail string required —
observedVersion number required The versions involved, so a repair pass has what it needs to act.
currentVersion number required —

ReconciliationFindingKind#

ts
(typeof RECONCILIATION_FINDING_KINDS)[number];

ReconstructedHistory#

Field Type Required Notes
heads readonly RevisionId[] — RevisionId required Revisions nothing descends from. More than one means live divergence.
roots readonly RevisionId[] — RevisionId required —
branchPoints readonly BranchPoint[] — BranchPoint required —
merges readonly RevisionId[] — RevisionId required —
chronological readonly RevisionId[] — RevisionId required Every revision in at then sequence order: the audit reading order.
bySequence readonly RevisionId[] — RevisionId required Sequence order alone, which is the ORDER THINGS HAPPENED IN.
clockDisagreesWithSequence boolean required True when chronological and bySequence disagree — a clock-skew signal.

reconstructHistory#

Derive everything about the shape of a history (S2.4.f).

ts
reconstructHistory(records: readonly RevisionRecord[]): ReconstructedHistory

redact#

Hide values, never operations.

ts
redact(operations: readonly DiffOperation[], policy: RedactionPolicy): readonly DiffOperation[]

REDACTION_REASONS#

Values: sensitive-field, rights-restricted, tenant-isolated, legal-hold

RedactionPolicy#

Field Type Required Notes
redactPaths readonly (readonly string[])[] optional Paths whose VALUES may not be shown. The fact of the change still is.
reason RedactionReason optional —

RedactionReason#

ts
(typeof REDACTION_REASONS)[number];

RejectedIntent#

A submission that was not applied, kept so the person who made it can get it back.

Field Type Required Notes
intentToken string required —
operation string required —
subject EntityId required —
path MutationPath required —
precondition Precondition required The precondition as submitted. Stale by definition, and left that way.
payload TPayload required —
submittedAt Instant required —
submittedBy ActorRef required —
expiresAt Instant required After this instant the intent is discarded; a draft is not an archive.

repairPlan#

The versions a repair pass should re-emit for.

ts
repairPlan(findings: readonly ReconciliationFinding[]): readonly { readonly subject: string; readonly toVersion: number }[]

RESTORE_EVENT_KINDS#

Values: revision.restored, gate.invalidated, projection.invalidated

RESTORE_REFUSALS#

Values: unauthorized, grant-missing, no-reason-given, source-not-in-history, source-is-the-head, source-is-tombstoned, head-moved, precondition-names-the-source, target-stage-not-allowed, protected-field-would-change

RestoreAuthorization#

ts
| { readonly authorized: true }
| { readonly authorized: false; readonly refusals: readonly RestoreRefusal[] }

RestoreEventKind#

ts
(typeof RESTORE_EVENT_KINDS)[number];

RestorePlanInput#

Field Type Required Notes
request RestoreRequest required —
preview RestorePreview required —
history readonly RevisionRecord[] — RevisionRecord required —
newRevisionId RevisionId required The revision id the caller minted for the new revision.
contentHash RevisionRecord['content']['contentHash'] — RevisionRecord required The content hash of the restored content, computed by the caller.
dependentProjections readonly string[] optional Projections that read this object and must be recomputed.

RestorePlanOutcome#

ts
| { readonly outcome: 'planned'; readonly plan: PlannedRestore }
| { readonly outcome: 'refused'; readonly refusals: readonly RestoreRefusal[] }

RestorePolicy#

Field Type Required Notes
protectedFields readonly ProtectedField[] — ProtectedField required —
restoreGrant string required The grant a restore itself requires, over and above ordinary editing.
allowedTargetStages readonly string[] required Stages a restore may land in. Empty means the object has no stage model.

restorePrecondition#

The precondition a restore must carry (S2.3.e, and the sharp edge in S2.6).

ts
restorePrecondition(currentHead: RevisionId): Precondition

RestorePreview#

Field Type Required Notes
diff DiffResult required —
staleGates readonly StaleGate[] — StaleGate required Gates whose verdict does not survive the restore.
rightsImpacts readonly RightsImpact[] — RightsImpact required —
irreversibleEffects readonly IrreversibleEffect[] — IrreversibleEffect required —
protectedFieldRefusals readonly RestoreRefusal[] — RestoreRefusal required —
clean boolean required True when nothing here needs a human to look at it.

RestorePreviewInput#

Field Type Required Notes
request RestoreRequest required —
policy RestorePolicy required —
history readonly RevisionRecord[] — RevisionRecord required —
operations readonly DiffOperation[] — DiffOperation required The S2.5 operations between the head and the source revision.
gates readonly StaleGate[] — StaleGate required Gates currently satisfied, with the revision each was decided against.
rights readonly RightsImpact[] — RightsImpact required —
effects readonly IrreversibleEffect[] — IrreversibleEffect required Effects the object's stage model says the restored state can cause.

RestoreRefusal#

Field Type Required Notes
kind RestoreRefusalKind required —
detail string required —

RestoreRefusalKind#

ts
(typeof RESTORE_REFUSALS)[number];

RestoreRequest#

Field Type Required Notes
subject EntityId required —
sourceRevision RevisionId required The revision being restored FROM.
currentHead RevisionId required What the caller believes the head is. Checked against the history.
targetStage string | null required —
actor ActorDecision required —
actorRef ActorRef required —
reason string required —
precondition Precondition required —
at Instant required —
idempotencyKey string required —

restoreTargetsHead#

Whether a restore's precondition names the head rather than the source.

ts
restoreTargetsHead(precondition: Precondition, sourceRevision: RevisionId, currentHead: RevisionId): ConcurrencyViolation | null

ResumedRequest#

A submission rebuilt from a preserved intent, ready to be sent again.

Field Type Required Notes
operation string required —
subject EntityId required —
path MutationPath required —
precondition Precondition required —
payload TPayload required —
idempotencyKey string required —
resumedFrom string required —

resumeIntent#

Recover a rejected submission — the only route from an intent to a write.

ts
resumeIntent(intent: RejectedIntent<TPayload>, observed: ObservedState, restated: Precondition, idempotencyKey: string, now: Instant): ResumeOutcome<TPayload>

ResumeOutcome#

ts
| { readonly outcome: 'resumed'; readonly request: ResumedRequest<TPayload> }
| { readonly outcome: 'head-moved'; readonly conflict: ConflictReport }
| { readonly outcome: 'refused'; readonly reason: string }

RETRY_DISPOSITIONS#

Whether a failed attempt may be re-sent by machinery rather than by a person.

Values: none, idempotent-replay

RETRY_VIOLATION_KINDS#

Values: precondition-changed, idempotency-key-changed, next-revision-changed, attempt-not-advanced

RetryAttempt#

One send of one request.

Field Type Required Notes
attempt number required 1 for the first send.
precondition Precondition required —
idempotencyKey string required —
nextRevision RevisionId required —

retryDecision#

Decide whether machinery may send this again (S2.3.f).

ts
retryDecision(previous: RetryAttempt, failure: AttemptFailure, maxAttempts: number): RetryDecision

RetryDecision#

ts
| { readonly decision: 'retry'; readonly attempt: RetryAttempt }
| { readonly decision: 'stop-conflict'; readonly reason: string }
| { readonly decision: 'stop'; readonly reason: string }

RetryDisposition#

ts
(typeof RETRY_DISPOSITIONS)[number];

RetryViolation#

Field Type Required Notes
kind RetryViolationKind required —
detail string required —

RetryViolationKind#

ts
(typeof RETRY_VIOLATION_KINDS)[number];

retryViolations#

Catch a retry that changed something it may not change.

ts
retryViolations(previous: RetryAttempt, next: RetryAttempt): readonly RetryViolation[]

RevisionContribution#

Whose words these are, when they are not the author's (S8.3.e).

Field Type Required Notes
contributor ActorRef required The actor whose content this is.
proposalId string required The proposal the content arrived through, so the revision is traceable.
amended boolean required Whether the author changed the proposal before admitting it.

RevisionRecord#

One revision, as it is stored.

Field Type Required Notes
tenant TenantId required —
workbench WorkbenchId required —
entityId EntityId required —
revisionId RevisionId required —
sequence number required Monotonic per entity, starting at 1.
schemaVersion number required The entity schema this revision's content conforms to. Integer, >= 1.
lineage Lineage required —
author ActorRef required The actor as recorded. A delegated actor carries both identities.
at Instant required —
reason string required —
content ContentBinding required —
legalHold LegalHold | null — LegalHold required —
contribution RevisionContribution | null — RevisionContribution required Whose words this revision's content is, when they are not the author's.

RevisionStore#

A store that can perform the comparison and the write as ONE indivisible step.

Field Type Required Notes
load (subject: EntityId) => Promise<ObservedState> — EntityId, ObservedState required —
compareAndSet (request: CompareAndSetRequest<TContent>) => Promise<CompareAndSetResult> — CompareAndSetRequest, CompareAndSetResult required —

RIGHTS_IMPACTS#

Values: consent-withdrawn, licence-expired, territory-restricted, subject-erasure

RightsImpact#

Material in the source revision whose permission has changed since.

Field Type Required Notes
kind RightsImpactKind required —
subjectRef string required —
withdrawnAt Instant required —
detail string required —

RightsImpactKind#

ts
(typeof RIGHTS_IMPACTS)[number];

routeRecomputation#

Decide what to do about one stale mark (S2.12.e).

ts
routeRecomputation(mark: StaleMark, constraints: RecomputeConstraints): RecomputeRouting

ROUTING_OUTCOMES#

Values: queued, requires-explicit-action, refused

RoutingOutcome#

ts
(typeof ROUTING_OUTCOMES)[number];

SafeCurrentMetadata#

What a caller may be told about the current state without being allowed to read it.

Field Type Required Notes
currentRevision RevisionId required —
updatedAt Instant required —
updatedBy string required —
stage string | null required —
contentHash string | null required —

ScalarField#

Field Type Required Notes
path readonly string[] required —
before FieldValue required —
after FieldValue required —
schemaDefault DiffScalar optional What the schema supplies when the field is absent. Undefined when nothing does.
sensitive boolean optional True when the value must never be shown. The CHANGE still is.
enumMembers readonly string[] optional The enum's member set, when the field is one.
units UnitTable optional —

SchemaAudit#

What an audit of a command set found, and what it did not look at.

Field Type Required Notes
violations readonly ConcurrencyViolation[] — ConcurrencyViolation required —
mutatingOperations number required —
coveredPaths readonly MutationPath[] — MutationPath required —
uncoveredPaths readonly MutationPath[] — MutationPath required —

SCORE_DIRECTIONS#

Which way is better.

Values: higher-is-better, lower-is-better, target-is-best

SCORE_VERDICTS#

Values: pass, warn, fail, undetermined

SCORE_VIOLATION_KINDS#

Values: unit-is-not-a-unit, target-direction-without-a-target, target-on-a-non-target-direction, bounded-scale-inverted, value-outside-a-bounded-scale, ordinal-scale-with-fewer-than-two-levels, ordinal-value-is-not-an-integer-level, non-finite-value, uncertainty-interval-inverted, uncertainty-interval-excludes-the-value, confidence-out-of-range, sample-of-one-with-a-standard-deviation, non-value-with-no-detail, version-not-a-positive-integer, model-without-a-provider, corpus-without-a-version, unknown-dimension, duplicate-dimension, reading-for-another-revision

ScoreApplicability#

Where the dimension applies. Empty means everywhere in its workbench.

Field Type Required Notes
assetKinds readonly string[] required —
stages readonly string[] required —

ScoredDimension#

Field Type Required Notes
dimensionId string required —
reading ScoreReading required —
provenance ScoreProvenance required —

ScoreDimensionSpec#

Field Type Required Notes
dimensionId string required —
unit string required A unit, always. "score" is not a unit; it is a refusal to name one.
direction ScoreDirection required —
scale ScoreScale required —
applicability ScoreApplicability required —
target number | null required Required when the direction is target-is-best; null otherwise.
describe string required —

ScoreDirection#

ts
(typeof SCORE_DIRECTIONS)[number];

ScoreProvenance#

Everything that decides what a number MEANS.

Field Type Required Notes
evaluatorId string required —
evaluatorVersion number required —
corpusId string | null required The reference set it scored against, when it has one.
corpusVersion number | null required —
modelId string | null required The model, when the evaluator is model-backed.
modelVersion string | null required —
providerId string | null required The provider that served it. Required whenever a model is named.
preprocessingId string required —
preprocessingVersion number required —
policyId string required The policy the VERDICT would be derived under. Never applied to the value.
policyVersion number required —
inputRevision RevisionId required —
inputHash Sha256Hex required —
runId string required —
at Instant required —

ScoreReading#

ts
| { readonly kind: 'measured'; readonly raw: number; readonly uncertainty: ScoreUncertainty | null; }
| { readonly kind: 'non-value'; readonly state: NonValueState; readonly detail: string }

ScoreRow#

A row for an export, a table or a wire payload.

Field Type Required Notes
dimensionId string required —
value number | null required —
state NonValueState | 'measured' — NonValueState, measured required —
unit string | null required —
detail string | null required —

ScoreScale#

What the numbers mean, which decides which arithmetic is legal on them.

ts
| { readonly kind: 'bounded'; readonly min: number; readonly max: number }
| { readonly kind: 'unbounded' }
| { readonly kind: 'ordinal'; readonly levels: readonly string[] }

ScoreUncertainty#

How sure the evaluator is, when it can say.

ts
| { readonly kind: 'interval'; readonly low: number; readonly high: number; readonly confidence: number; }
| { readonly kind: 'sample'; readonly stddev: number; readonly n: number }

ScoreVector#

A whole vector, as it is stored and passed around.

Field Type Required Notes
subjectRevision RevisionId required —
dimensions readonly ScoredDimension[] — ScoredDimension required —

ScoreVerdict#

ts
(typeof SCORE_VERDICTS)[number];

ScoreViolation#

Field Type Required Notes
kind ScoreViolationKind required —
subject string required —
detail string required —

ScoreViolationKind#

ts
(typeof SCORE_VIOLATION_KINDS)[number];

SentinelAdoption#

Field Type Required Notes
dimensionId string required —
sentinel number required —
became NonValueState required —

SI_UNITS#

StaleGate#

A gate whose verdict was reached against content that is about to change.

Field Type Required Notes
gateId string required —
passedAgainst RevisionId required —
evidence readonly EvidenceRef[] — EvidenceRef required —
why string required —

StaleMark#

Field Type Required Notes
runId string required —
gateId string required —
node DependencyNode required —
fromVersion number | null required —
toVersion number required —
eventId string required —
reasonKey string required —
detail string required —
markedAt Instant required —
through readonly DependencyNode[] — DependencyNode required How the change reached this result.

StoredObservation#

What a dependent result claims to have been answered against.

Field Type Required Notes
runId string required —
gateId string required —
node DependencyNode required —
observedVersion number required —
markedStale boolean required —
markedToVersion number | null required The version the mark is catching up TO. Null when nothing marked it.

summarize#

Counts, and the three that must never be folded into the others.

ts
summarize(operations: readonly DiffOperation[]): DiffSummary

supportViewOfIntent#

A support agent reading a customer's rejected submission.

ts
supportViewOfIntent(intent: RejectedIntent<TPayload>, scopes: readonly string[], now: Instant): IntentSupportOutcome<TPayload>

Threshold#

Field Type Required Notes
dimensionId string required —
failBeyond number required Compared with the direction in mind; warnAt is between pass and fail.
warnBeyond number | null required —

ThresholdPolicy#

Field Type Required Notes
policyId string required —
policyVersion number required —
thresholds readonly Threshold[] — Threshold required —

TimelineClip#

Field Type Required Notes
clipId string required —
lane string required —
start number required Start, in the timeline's own time base.
duration number required —
sourceIn number required Where the material starts inside the source. A trim moves this.
sourceId string required —
parameters Readonly<Record<string, DiffScalar>> — DiffScalar required —

TimelineField#

Field Type Required Notes
path readonly string[] required —
before { readonly timeBase: TimeBase; readonly clips: readonly TimelineClip[] } — TimeBase, TimelineClip required —
after { readonly timeBase: TimeBase; readonly clips: readonly TimelineClip[] } — TimeBase, TimelineClip required —

Tombstone#

Field Type Required Notes
cause TombstoneCause required —
authority string required Who authorized it — a governed operation, not an author's own decision.
at Instant required —
reference string required The record of the decision, so the removal is traceable to a request.

TOMBSTONE_CAUSES#

Values: erasure-request, retention-expiry, unlawful-content, rights-withdrawal

TombstoneCause#

ts
(typeof TOMBSTONE_CAUSES)[number];

toRow#

ts
toRow(scored: ScoredDimension, registry: readonly ScoreDimensionSpec[]): ScoreRow

TreeField#

Field Type Required Notes
path readonly string[] required —
before readonly TreeNode[] — TreeNode required —
after readonly TreeNode[] — TreeNode required —

TreeNode#

Field Type Required Notes
nodeId string required —
parentId string | null required —
position number required Position among siblings.
fields Readonly<Record<string, DiffScalar>> — DiffScalar required —

TruncationNote#

Field Type Required Notes
node DependencyNode required —
reason 'fan-out' | 'depth' | 'page' required —
detail string required —

unappliedMarks#

Check that propagation landed before the release decision did (S2.12.d).

ts
unappliedMarks(aggregate: AggregateView, marks: readonly StaleMark[]): readonly ApplicationFault[]

UnitTable#

Conversion factors to a base unit, per dimension. Extended by the caller.

validateDimensionSpec#

ts
validateDimensionSpec(spec: ScoreDimensionSpec): readonly ScoreViolation[]

validateEventStream#

Check a node's event stream (S2.12.b).

ts
validateEventStream(events: readonly DependencyChangeEvent[]): readonly EventViolation[]

validateInvalidationRegistry#

Check an invalidation registry (S2.12.a).

ts
validateInvalidationRegistry(registry: readonly MutationType[]): readonly InvalidationViolation[]

validateVector#

Check a whole vector against the dimensions it claims to score (S2.8.a–c).

ts
validateVector(vector: ScoreVector, registry: readonly ScoreDimensionSpec[]): readonly ScoreViolation[]

verifyArtifactPin#

Verify an artifact-backed revision against the digest its reference pins.

ts
verifyArtifactPin(record: RevisionRecord, pinned: Sha256Hex): HashVerification

verifyContentHash#

Verify a revision against the content presented as its own (S2.4.e).

ts
verifyContentHash(record: RevisionRecord, content: unknown, hasher: ContentHasher): HashVerification

withPreservedIntent#

Attach the token that reaches the preserved submission (S2.3.d).

ts
withPreservedIntent(report: ConflictReport, intentToken: string): ConflictReport

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 | | ------------------------------ | --------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | authorizeRestore | function | Decide whether a restore may proceed (S2.6.a). | | CreateAuthorization.grant | string | — | | DiffContext.actor | ActorRef | null | — | | DiffProvenance.actor | ActorRef | null | Who made this particular change, when the diff spans revisions that can attribute it. Null between two revisions with several authors in between — naming one of them would be a guess presented as a fact. | | INTENT_SUPPORT_SCOPE | constant | The grant a support agent needs to read somebody else's rejected submission. | | ProtectedField.overrideGrant | string | null | — | | RestoreAuthorization | type | — | | RestorePolicy.restoreGrant | string | The grant a restore itself requires, over and above ordinary editing. | | RestoreRequest.actor | ActorDecision | — | | RestoreRequest.actorRef | ActorRef | — | | RevisionRecord.tenant | TenantId | — |

Idempotency and concurrency#

| Symbol | Type | Notes | | ------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | ATTEMPT_FAILURES | enumeration | Why an attempt did not succeed, from the client's point of view. | | AttemptFailure | type | — | | CommandSchema.idempotencyKeyField | string | null | The request field carrying the idempotency key, or null. | | CompareAndSetRequest.idempotencyKey | string | — | | CompareAndSetRequest.nextRevision | RevisionId | — | | CONCURRENCY_VIOLATION_KINDS | enumeration | — | | ConcurrencyViolationKind | type | — | | ConflictReport.expectedRevision | RevisionId | null | The revision the caller expected. Null on a create-if-absent conflict. | | DependencyChangeEvent.sequence | number | Per-node, monotonic, gapless. The hole a lost event leaves. | | DependentResult.targetRevision | string | — | | DiffContext.afterRevision | RevisionRef | — | | DiffContext.beforeRevision | RevisionRef | — | | DiffProvenance.afterRevision | RevisionRef | — | | DiffProvenance.beforeRevision | RevisionRef | — | | expectRevision | function | The precondition an update carries. | | longestCommonSubsequence | function | The longest common subsequence, as a table. | | OutboxEvent.revisionId | RevisionId | — | | PlannedRestore.idempotencyKey | string | — | | PlannedRestore.revision | RevisionRecord | The revision to append. Nothing existing is touched. | | ReconstructedHistory.bySequence | readonly RevisionId[] | Sequence order alone, which is the ORDER THINGS HAPPENED IN. | | ReconstructedHistory.clockDisagreesWithSequence | boolean | True when chronological and bySequence disagree — a clock-skew signal. | | RestorePlanInput.newRevisionId | RevisionId | The revision id the caller minted for the new revision. | | RestoreRequest.idempotencyKey | string | — | | RestoreRequest.sourceRevision | RevisionId | The revision being restored FROM. | | ResumedRequest.idempotencyKey | string | — | | RetryAttempt.attempt | number | 1 for the first send. | | RetryAttempt.idempotencyKey | string | — | | RetryAttempt.nextRevision | RevisionId | — | | RevisionRecord.revisionId | RevisionId | — | | RevisionRecord.sequence | number | Monotonic per entity, starting at 1. | | SafeCurrentMetadata.currentRevision | RevisionId | — | | ScoreProvenance.inputRevision | RevisionId | — | | ScoreVector.subjectRevision | RevisionId | — |

Pagination#

| Symbol | Type | Notes | | --------------------------------------- | ------------------- | --------------------------------------------------------- | -------------------------------------------------------- | | DiffPage.nextCursor | string | null | The id to resume after. Null when this is the last page. | | paginate | function | A page of a stably-ordered diff. | | PropagationLimits.pageSize | number | Total results to return in one page. | | RestorePlanInput.dependentProjections | readonly string[] | Projections that read this object and must be recomputed. |

State and failure#

| Symbol | Type | Notes | | --------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------- | --- | | AggregateOutcome | type | — | | ATTEMPT_FAILURES | enumeration | Why an attempt did not succeed, from the client's point of view. | | AttemptFailure | type | — | | CanonicalizationFailure | type | — | | CONCURRENCY_VIOLATION_KINDS | enumeration | — | | ConcurrencyViolationKind | type | — | | DerivedVerdict.verdict | ScoreVerdict | — | | EVENT_VIOLATION_KINDS | enumeration | — | | EventViolationKind | type | — | | GovernedOutcome | type | — | | HISTORY_VIOLATION_KINDS | enumeration | — | | HistoryViolationKind | type | — | | IntentSupportOutcome | type | — | | INVALIDATION_VIOLATION_KINDS | enumeration | — | | InvalidationViolationKind | type | — | | NON_VALUE_STATES | enumeration | Every way a score can not be a number, named. | | NonValueState | type | — | | NOT_COUNTED_STATES | enumeration | States that mean "this dimension does not apply", rather than "we do not know". | | ObservedState | type | What storage says is there now. | | PreconditionOutcome | type | — | | PropagationOutcome | type | A walk that finished, or one that did not and says where to resume. | | RESTORE_REFUSALS | enumeration | — | | RestorePlanOutcome | type | — | | RestorePreview.protectedFieldRefusals | readonly RestoreRefusal[] | — | | RestoreRefusalKind | type | — | | ResumeOutcome | type | — | | RETRY_VIOLATION_KINDS | enumeration | — | | RetryViolationKind | type | — | | retryViolations | function | Catch a retry that changed something it may not change. | | ROUTING_OUTCOMES | enumeration | — | | RoutingOutcome | type | — | | SchemaAudit.violations | readonly ConcurrencyViolation[] | — | | SCORE_VERDICTS | enumeration | — | | SCORE_VIOLATION_KINDS | enumeration | — | | ScoreRow.state | NonValueState | 'measured' | — | | ScoreVerdict | type | — | | ScoreViolationKind | type | — |

Compatibility#

| Symbol | Type | Notes | | --------------------------------------- | ---------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------- | | ADAPTER_VERSION | constant | — | | DependencyChangeEvent.fromVersion | number | null | Null only for the node's first appearance. | | DependencyChangeEvent.toVersion | number | — | | DependentResult.observedVersion | number | The version of the dependency this result was answered against. | | DerivedVerdict.policyVersion | number | — | | DiffProvenance.adapterVersion | number | Bumped when an adapter's comparison changes, so a cached diff is invalid. | | DiffSummary.unsupported | number | — | | RecomputeConstraints.evaluatorVersion | number | — | | ReconciliationFinding.currentVersion | number | — | | ReconciliationFinding.observedVersion | number | The versions involved, so a repair pass has what it needs to act. | | RevisionRecord.schemaVersion | number | The entity schema this revision's content conforms to. Integer, >= 1. | | ScoreProvenance.corpusVersion | number | null | — | | ScoreProvenance.evaluatorVersion | number | — | | ScoreProvenance.modelVersion | string | null | — | | ScoreProvenance.policyVersion | number | — | | ScoreProvenance.preprocessingVersion | number | — | | StaleMark.fromVersion | number | null | — | | StaleMark.toVersion | number | — | | StoredObservation.markedToVersion | number | null | The version the mark is catching up TO. Null when nothing marked it. | | StoredObservation.observedVersion | number | — | | ThresholdPolicy.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-conflict-fixtures.json
  • evidence/v1-workbenches/workbench-kit-diff-fixtures.json
  • evidence/v1-workbenches/workbench-kit-export-map.json
  • libs/oshun/workbench-kit/src/concurrency.ts
  • libs/oshun/workbench-kit/src/diff.ts
  • libs/oshun/workbench-kit/src/restore.ts
  • libs/oshun/workbench-kit/src/revisions.ts
  • libs/oshun/workbench-kit/src/scores.ts
  • libs/oshun/workbench-kit/src/staleness.ts