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.
| { 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.
assertMutationEnvelope(envelope: unknown): asserts envelope is MutationEnvelope<TPayload>
CapabilityResult#
The result of a capability the deployment has not configured.
| { readonly configured: true; readonly value: T }
| { readonly configured: false; readonly capability: string; readonly reason: string }
configured#
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#
(typeof KIT_INVARIANTS)[number];
meetsDeletionThreshold#
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#
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.jsonlibs/oshun/workbench-kit/src/invariants.ts