Eve library

Invariants

Evidence

Revision 1

On this page

The six things a domain plugin may not override.

Generated from libs/oshun/workbench-kit/src/invariants.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: ADR-S2 / S0.7.g. Do not edit by hand.

Summary#

  • src/invariants.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit contract ADR-S2 / S1.1.a
@oshun/workbench-kit/invariants contract ADR-S2 / S0.7.g

Exports#

Symbol Kind Summary
ActorDecision type The decision an authorization check produced.
assertMutationEnvelope function Refuses an envelope that could bypass any of the invariants.
CapabilityResult type The result of a capability the deployment has not configured.
configured function —
DELETION_THRESHOLD_CONSUMERS constant The S0.11 bar, as a function rather than a footnote.
KIT_INVARIANT_RULES constant Verbatim from evidence/v1-workbenches/workbench-kit-extension-model.json. Restating them here rather than importing the artifact is deliberate: a library must not read an audit artifact at runtime, and the drift between the two is checked by a test instead.
KIT_INVARIANTS enumeration The invariant ids, in the order ADR-S2 records them.
KitInvariant interface —
KitInvariantError class —
KitInvariantId type —
meetsDeletionThreshold function —
MutationEnvelope interface What a plugin hands the kit to perform one mutation.
notConfigured function —

Shapes#

ActorDecision#

The decision an authorization check produced.

ts
| { readonly allowed: true; readonly actorId: string; readonly grant: string }
| { readonly allowed: false; readonly actorId: string; readonly reason: string }

assertMutationEnvelope#

Refuses an envelope that could bypass any of the invariants.

ts
assertMutationEnvelope(envelope: unknown): asserts envelope is MutationEnvelope<TPayload>

CapabilityResult#

The result of a capability the deployment has not configured.

ts
| { readonly configured: true; readonly value: T }
| { readonly configured: false; readonly capability: string; readonly reason: string }

configured#

ts
configured(value: T): CapabilityResult<T>

DELETION_THRESHOLD_CONSUMERS#

The S0.11 bar, as a function rather than a footnote.

Value: 2

KIT_INVARIANT_RULES#

Verbatim from evidence/v1-workbenches/workbench-kit-extension-model.json. Restating them here rather than importing the artifact is deliberate: a library must not read an audit artifact at runtime, and the drift between the two is checked by a test instead.

KIT_INVARIANTS#

The invariant ids, in the order ADR-S2 records them.

Values: authorization, audit, idempotency, honest-capability, no-escape-hatch, deletion-threshold

KitInvariant#

Field Type Required Notes
id KitInvariantId required —
rule string required —
source string required The ledger cell that decided it, so a change has somewhere to be argued.

KitInvariantError#

KitInvariantId#

ts
(typeof KIT_INVARIANTS)[number];

meetsDeletionThreshold#

ts
meetsDeletionThreshold(realConsumers: readonly string[], approvedException?: string): boolean

MutationEnvelope#

What a plugin hands the kit to perform one mutation.

Field Type Required Notes
operation string required What is being changed, in the plugin's own vocabulary.
subjectId string required The object the change lands on.
actor ActorDecision required The authorization verdict — the invariant, not a claim the caller makes.
idempotencyKey string required Retry safety: the same key must not apply the change twice.
expectedRevision string | null required Optimistic-concurrency token, or null when the object is being created.
payload TPayload required Domain data. Opaque to the kit by construction.

notConfigured#

ts
notConfigured(capability: string, reason: string): CapabilityResult<T>

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
ActorDecision type The decision an authorization check produced.
MutationEnvelope.actor ActorDecision The authorization verdict — the invariant, not a claim the caller makes.

Idempotency and concurrency#

| Symbol | Type | Notes | | ----------------------------------- | -------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- | | MutationEnvelope.expectedRevision | string | null | Optimistic-concurrency token, or null when the object is being created. | | MutationEnvelope.idempotencyKey | string | Retry safety: the same key must not apply the change twice. |

Pagination#

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

State and failure#

Symbol Type Notes
KitInvariantError class —

Compatibility#

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

Deprecation#

Not applicable: nothing on this page can be deprecated on its own; the package version is its lifecycle.

Evidence#

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