# Invariants

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](#actordecision)                               | type        | The decision an authorization check produced.                                                                                                                                                                                                                       |
| [assertMutationEnvelope](#assertmutationenvelope)             | function    | Refuses an envelope that could bypass any of the invariants.                                                                                                                                                                                                        |
| [CapabilityResult](#capabilityresult)                         | type        | The result of a capability the deployment has not configured.                                                                                                                                                                                                       |
| [configured](#configured)                                     | function    | —                                                                                                                                                                                                                                                                   |
| [DELETION_THRESHOLD_CONSUMERS](#deletion_threshold_consumers) | constant    | The S0.11 bar, as a function rather than a footnote.                                                                                                                                                                                                                |
| [KIT_INVARIANT_RULES](#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](#kit_invariants)                             | enumeration | The invariant ids, in the order ADR-S2 records them.                                                                                                                                                                                                                |
| [KitInvariant](#kitinvariant)                                 | interface   | —                                                                                                                                                                                                                                                                   |
| [KitInvariantError](#kitinvarianterror)                       | class       | —                                                                                                                                                                                                                                                                   |
| [KitInvariantId](#kitinvariantid)                             | type        | —                                                                                                                                                                                                                                                                   |
| [meetsDeletionThreshold](#meetsdeletionthreshold)             | function    | —                                                                                                                                                                                                                                                                   |
| [MutationEnvelope](#mutationenvelope)                         | interface   | What a plugin hands the kit to perform one mutation.                                                                                                                                                                                                                |
| [notConfigured](#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](#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](#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`
