# Capability

What a capability declares about itself, and the five states it can honestly be
in.

Generated from `libs/oshun/workbench-kit/src/capability-state.ts`,
`libs/oshun/workbench-kit/src/registry.ts` by
`node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs`. Ledger:
S1.6 / S1.7. Do not edit by hand.

## Summary

- `src/capability-state.ts`
- `src/registry.ts`

| Entry point                             | Runtime class | Authorized by |
| --------------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/capability-state` | `contract`    | S1.6          |
| `@oshun/workbench-kit/registry`         | `contract`    | S1.7          |

## Exports

| Symbol                                                  | Kind        | Summary                                                                                                               |
| ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| [Audience](#audience)                                   | type        | —                                                                                                                     |
| [AUDIENCES](#audiences)                                 | enumeration | —                                                                                                                     |
| [CapabilityDependency](#capabilitydependency)           | interface   | —                                                                                                                     |
| [CapabilityDescriptor](#capabilitydescriptor)           | interface   | —                                                                                                                     |
| [CapabilityOwner](#capabilityowner)                     | interface   | Who to ask when a capability is not `configured`.                                                                     |
| [CapabilitySource](#capabilitysource)                   | interface   | —                                                                                                                     |
| [CapabilityState](#capabilitystate)                     | type        | —                                                                                                                     |
| [CapabilityStateCommon](#capabilitystatecommon)         | interface   | Fields every state carries, whatever it is.                                                                           |
| [CapabilityStateHandlers](#capabilitystatehandlers)     | interface   | —                                                                                                                     |
| [CIRCUIT_POSITIONS](#circuit_positions)                 | enumeration | —                                                                                                                     |
| [CircuitPosition](#circuitposition)                     | type        | —                                                                                                                     |
| [compareSemanticVersions](#comparesemanticversions)     | function    | Semver precedence: -1, 0 or 1. A prerelease sorts BEFORE its release.                                                 |
| [CONFIGURATION_CATEGORIES](#configuration_categories)   | enumeration | —                                                                                                                     |
| [ConfigurationCategory](#configurationcategory)         | type        | —                                                                                                                     |
| [ConfigurationReference](#configurationreference)       | interface   | —                                                                                                                     |
| [ConfiguredState](#configuredstate)                     | interface   | —                                                                                                                     |
| [CostModel](#costmodel)                                 | interface   | —                                                                                                                     |
| [DATA_CLASSIFICATIONS](#data_classifications)           | enumeration | —                                                                                                                     |
| [DataClassification](#dataclassification)               | type        | —                                                                                                                     |
| [DegradedState](#degradedstate)                         | interface   | —                                                                                                                     |
| [FailedState](#failedstate)                             | interface   | —                                                                                                                     |
| [FAILURE_CLASSES](#failure_classes)                     | enumeration | A STABLE error class, not a message.                                                                                  |
| [FailureClass](#failureclass)                           | type        | —                                                                                                                     |
| [findCycles](#findcycles)                               | function    | Every dependency cycle, as a path that returns to its start.                                                          |
| [FIXTURE_POLICIES](#fixture_policies)                   | enumeration | —                                                                                                                     |
| [FixturePolicy](#fixturepolicy)                         | type        | —                                                                                                                     |
| [formatSemanticVersion](#formatsemanticversion)         | function    | —                                                                                                                     |
| [formatTypedReference](#formattypedreference)           | function    | —                                                                                                                     |
| [HealthProbe](#healthprobe)                             | interface   | —                                                                                                                     |
| [Host](#host)                                           | type        | —                                                                                                                     |
| [HOSTS](#hosts)                                         | enumeration | —                                                                                                                     |
| [isStateFresh](#isstatefresh)                           | function    | Whether an answer may still be trusted at `now`.                                                                      |
| [Lifecycle](#lifecycle)                                 | type        | —                                                                                                                     |
| [LIFECYCLES](#lifecycles)                               | enumeration | —                                                                                                                     |
| [matchCapabilityState](#matchcapabilitystate)           | function    | A TOTAL match over the five states.                                                                                   |
| [mergeCapabilitySources](#mergecapabilitysources)       | function    | Merge plugin-supplied registries, refusing collisions.                                                                |
| [MergeCollision](#mergecollision)                       | interface   | —                                                                                                                     |
| [MergeResult](#mergeresult)                             | type        | —                                                                                                                     |
| [MissingConfiguration](#missingconfiguration)           | interface   | A setting that is absent.                                                                                             |
| [NotConfiguredState](#notconfiguredstate)               | interface   | —                                                                                                                     |
| [parseCapabilityDescriptor](#parsecapabilitydescriptor) | function    | —                                                                                                                     |
| [parseCapabilityState](#parsecapabilitystate)           | function    | —                                                                                                                     |
| [parseSafeDetail](#parsesafedetail)                     | function    | —                                                                                                                     |
| [parseSemanticVersion](#parsesemanticversion)           | function    | A strict semantic version, with no build metadata and no `v` prefix.                                                  |
| [parseTypedReference](#parsetypedreference)             | function    | —                                                                                                                     |
| [PROBE_KINDS](#probe_kinds)                             | enumeration | —                                                                                                                     |
| [ProbeKind](#probekind)                                 | type        | —                                                                                                                     |
| [probeProjection](#probeprojection)                     | function    | What a runtime should execute, in a stable order.                                                                     |
| [ProbeProjectionRow](#probeprojectionrow)               | interface   | —                                                                                                                     |
| [projectionCoverage](#projectioncoverage)               | function    | Every entry must appear in the reference projection, and every entry with probes must appear in the probe projection. |
| [REFERENCE_KINDS](#reference_kinds)                     | enumeration | —                                                                                                                     |
| [ReferenceKind](#referencekind)                         | type        | —                                                                                                                     |
| [referenceProjection](#referenceprojection)             | function    | What a human or an API reference page needs, in a stable order.                                                       |
| [ReferenceProjectionRow](#referenceprojectionrow)       | interface   | —                                                                                                                     |
| [RegistryValidationOptions](#registryvalidationoptions) | interface   | —                                                                                                                     |
| [RegistryViolation](#registryviolation)                 | interface   | —                                                                                                                     |
| [REQUIRED_VERIFICATIONS](#required_verifications)       | enumeration | The four things that must be VERIFIED before a capability may call itself configured.                                 |
| [RESOURCE_KINDS](#resource_kinds)                       | enumeration | —                                                                                                                     |
| [ResourceKind](#resourcekind)                           | type        | —                                                                                                                     |
| [ResourceNeed](#resourceneed)                           | interface   | —                                                                                                                     |
| [RetryMetadata](#retrymetadata)                         | interface   | —                                                                                                                     |
| [Runtime](#runtime)                                     | type        | —                                                                                                                     |
| [RUNTIMES](#runtimes)                                   | enumeration | —                                                                                                                     |
| [SemanticVersion](#semanticversion)                     | interface   | —                                                                                                                     |
| [Slo](#slo)                                             | interface   | The service-level objective.                                                                                          |
| [TypedReference](#typedreference)                       | interface   | `<kind>:<dotted.name>`.                                                                                               |
| [UnavailableState](#unavailablestate)                   | interface   | —                                                                                                                     |
| [usability](#usability)                                 | function    | How much of the capability a caller may rely on. THREE-valued, deliberately.                                          |
| [Usability](#usability)                                 | type        | —                                                                                                                     |
| [validateRegistry](#validateregistry)                   | function    | Validate a whole registry.                                                                                            |
| [Verification](#verification)                           | interface   | —                                                                                                                     |
| [VerificationSubject](#verificationsubject)             | type        | —                                                                                                                     |

## Shapes

#### Audience

```ts
(typeof AUDIENCES)[number];
```

#### AUDIENCES

Values: `creator`, `reviewer`, `operator`, `learner`, `viewer`, `system`

#### CapabilityDependency

| Field        | Type                                                   | Required | Notes |
| ------------ | ------------------------------------------------------ | -------- | ----- |
| `dependency` | `string`                                               | required | —     |
| `state`      | [CapabilityStateName](./schema.md#capabilitystatename) | required | —     |
| `detail`     | `string`                                               | required | —     |

#### CapabilityDescriptor

| Field                 | Type                                                                                    | Required | Notes                                               |
| --------------------- | --------------------------------------------------------------------------------------- | -------- | --------------------------------------------------- |
| `id`                  | [CapabilityId](./identity.md#capabilityid)                                              | required | —                                                   |
| `aliases`             | `readonly string[]`                                                                     | required | —                                                   |
| `version`             | [SemanticVersion](#semanticversion)                                                     | required | —                                                   |
| `owner`               | `string`                                                                                | required | —                                                   |
| `domain`              | `string`                                                                                | required | —                                                   |
| `audiences`           | `readonly Audience[]` — [Audience](#audience)                                           | required | —                                                   |
| `hosts`               | `readonly Host[]` — [Host](#host)                                                       | required | —                                                   |
| `runtime`             | [Runtime](#runtime)                                                                     | required | —                                                   |
| `lifecycle`           | [Lifecycle](#lifecycle)                                                                 | required | —                                                   |
| `description`         | `string`                                                                                | required | —                                                   |
| `supersededBy`        | `CapabilityId \| null` — [CapabilityId](./identity.md#capabilityid)                     | required | Required when `lifecycle` is deprecated or retired. |
| `requires`            | `readonly CapabilityId[]` — [CapabilityId](./identity.md#capabilityid)                  | required | —                                                   |
| `optional`            | `readonly CapabilityId[]` — [CapabilityId](./identity.md#capabilityid)                  | required | —                                                   |
| `provides`            | `readonly string[]`                                                                     | required | —                                                   |
| `configuration`       | `readonly ConfigurationReference[]` — [ConfigurationReference](#configurationreference) | required | —                                                   |
| `resources`           | `readonly ResourceNeed[]` — [ResourceNeed](#resourceneed)                               | required | —                                                   |
| `probes`              | `readonly HealthProbe[]` — [HealthProbe](#healthprobe)                                  | required | —                                                   |
| `references`          | `readonly TypedReference[]` — [TypedReference](#typedreference)                         | required | —                                                   |
| `authorizationScopes` | `readonly string[]`                                                                     | required | —                                                   |
| `requiresElevation`   | `boolean`                                                                               | required | —                                                   |
| `dataClassification`  | [DataClassification](#dataclassification)                                               | required | —                                                   |
| `trustControls`       | `readonly string[]`                                                                     | required | —                                                   |
| `metrics`             | `readonly string[]`                                                                     | required | —                                                   |
| `auditEvents`         | `readonly string[]`                                                                     | required | —                                                   |
| `slo`                 | [Slo](#slo)                                                                             | required | —                                                   |
| `cost`                | `CostModel \| null` — [CostModel](#costmodel)                                           | required | —                                                   |
| `fixturePolicy`       | [FixturePolicy](#fixturepolicy)                                                         | required | —                                                   |

#### CapabilityOwner

Who to ask when a capability is not `configured`.

| Field         | Type     | Required | Notes |
| ------------- | -------- | -------- | ----- |
| `team`        | `string` | required | —     |
| `contactPath` | `string` | required | —     |

#### CapabilitySource

| Field     | Type                                                                              | Required | Notes                                                                    |
| --------- | --------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `source`  | `string`                                                                          | required | Where these entries came from: a package name, a plugin id, a file path. |
| `entries` | `readonly CapabilityDescriptor[]` — [CapabilityDescriptor](#capabilitydescriptor) | required | —                                                                        |

#### CapabilityState

```ts
| ConfiguredState
| NotConfiguredState
| DegradedState
| UnavailableState
| FailedState
```

#### CapabilityStateCommon

Fields every state carries, whatever it is.

| Field               | Type                                                                              | Required | Notes                                                               |
| ------------------- | --------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------- |
| `capability`        | [CapabilityId](./identity.md#capabilityid)                                        | required | —                                                                   |
| `capabilityVersion` | `string`                                                                          | required | —                                                                   |
| `checkedAt`         | [Instant](./identity.md#instant)                                                  | required | —                                                                   |
| `freshnessSeconds`  | `number`                                                                          | required | How long this answer may be trusted. 0 means it must not be cached. |
| `dependencies`      | `readonly CapabilityDependency[]` — [CapabilityDependency](#capabilitydependency) | required | —                                                                   |
| `owner`             | [CapabilityOwner](#capabilityowner)                                               | required | —                                                                   |
| `limitations`       | `readonly string[]`                                                               | required | What a caller would otherwise wrongly assume works.                 |
| `remediation`       | [Remediation](./schema.md#remediation)                                            | required | —                                                                   |
| `safeDetail`        | `string`                                                                          | required | One human sentence, checked for credentials.                        |

#### CapabilityStateHandlers

| Field            | Type                                                                           | Required | Notes |
| ---------------- | ------------------------------------------------------------------------------ | -------- | ----- |
| `configured`     | `(state: ConfiguredState) => T` — [ConfiguredState](#configuredstate)          | required | —     |
| `not_configured` | `(state: NotConfiguredState) => T` — [NotConfiguredState](#notconfiguredstate) | required | —     |
| `degraded`       | `(state: DegradedState) => T` — [DegradedState](#degradedstate)                | required | —     |
| `unavailable`    | `(state: UnavailableState) => T` — [UnavailableState](#unavailablestate)       | required | —     |
| `failed`         | `(state: FailedState) => T` — [FailedState](#failedstate)                      | required | —     |

#### CIRCUIT_POSITIONS

Values: `closed`, `open`, `half-open`

#### CircuitPosition

```ts
(typeof CIRCUIT_POSITIONS)[number];
```

#### compareSemanticVersions

Semver precedence: -1, 0 or 1. A prerelease sorts BEFORE its release.

```ts
compareSemanticVersions(a: SemanticVersion, b: SemanticVersion): number
```

#### CONFIGURATION_CATEGORIES

Values: `credential`, `endpoint`, `quota`, `feature-flag`, `tenant-binding`,
`model-selection`

#### ConfigurationCategory

```ts
(typeof CONFIGURATION_CATEGORIES)[number];
```

#### ConfigurationReference

| Field         | Type                                            | Required | Notes |
| ------------- | ----------------------------------------------- | -------- | ----- |
| `settingName` | `string`                                        | required | —     |
| `category`    | [ConfigurationCategory](#configurationcategory) | required | —     |
| `required`    | `boolean`                                       | required | —     |

#### ConfiguredState

| Field           | Type                                                      | Required | Notes |
| --------------- | --------------------------------------------------------- | -------- | ----- |
| `state`         | `'configured'` — [configured](./invariants.md#configured) | required | —     |
| `verifications` | `readonly Verification[]` — [Verification](#verification) | required | —     |

#### CostModel

| Field                   | Type     | Required | Notes |
| ----------------------- | -------- | -------- | ----- |
| `unit`                  | `string` | required | —     |
| `currency`              | `string` | required | —     |
| `estimatedMinorPerUnit` | `number` | required | —     |

#### DATA_CLASSIFICATIONS

Values: `public`, `internal`, `confidential`, `restricted`, `personal`

#### DataClassification

```ts
(typeof DATA_CLASSIFICATIONS)[number];
```

#### DegradedState

| Field                 | Type                                                        | Required | Notes                                                               |
| --------------------- | ----------------------------------------------------------- | -------- | ------------------------------------------------------------------- |
| `state`               | `'degraded'`                                                | required | —                                                                   |
| `affected`            | `readonly string[]`                                         | required | Non-empty. Nothing affected is `configured`, not degraded.          |
| `retained`            | `readonly string[]`                                         | required | Non-empty. Nothing retained is `unavailable`, not degraded.         |
| `cause`               | `string`                                                    | required | —                                                                   |
| `recheckAfterSeconds` | `number \| null`                                            | required | When to look again. Null only when recovery is not time-based.      |
| `expiresAt`           | `Instant \| null` — [Instant](./identity.md#instant)        | required | When this degradation stops being believable. Null when open-ended. |
| `recovery`            | `{ readonly automatic: boolean; readonly detail: string; }` | required | —                                                                   |

#### FailedState

| Field           | Type                                         | Required | Notes                                 |
| --------------- | -------------------------------------------- | -------- | ------------------------------------- |
| `state`         | `'failed'`                                   | required | —                                     |
| `failureClass`  | [FailureClass](#failureclass)                | required | —                                     |
| `correlationId` | [CorrelationId](./identity.md#correlationid) | required | The probe that produced this verdict. |

#### FAILURE_CLASSES

A STABLE error class, not a message.

Values: `configuration-invalid`, `authentication-rejected`,
`authorization-denied`, `dependency-contract-mismatch`, `quota-exhausted`,
`internal-error`, `probe-inconclusive`

#### FailureClass

```ts
(typeof FAILURE_CLASSES)[number];
```

#### findCycles

Every dependency cycle, as a path that returns to its start.

```ts
findCycles(byId: ReadonlyMap<string, CapabilityDescriptor>): readonly string[][]
```

#### FIXTURE_POLICIES

Values: `synthetic-only`, `anonymized`, `production-copy`

#### FixturePolicy

```ts
(typeof FIXTURE_POLICIES)[number];
```

#### formatSemanticVersion

```ts
formatSemanticVersion(version: SemanticVersion): string
```

#### formatTypedReference

```ts
formatTypedReference(reference: TypedReference): string
```

#### HealthProbe

| Field             | Type                    | Required | Notes                                                                          |
| ----------------- | ----------------------- | -------- | ------------------------------------------------------------------------------ |
| `name`            | `string`                | required | —                                                                              |
| `kind`            | [ProbeKind](#probekind) | required | —                                                                              |
| `intervalSeconds` | `number`                | required | How often a runtime should run it. Bounded below, so a probe cannot busy-loop. |

#### Host

```ts
(typeof HOSTS)[number];
```

#### HOSTS

Values: `studio-web`, `studio-desktop`, `operator-console`, `bff`, `worker`,
`cli`

#### isStateFresh

Whether an answer may still be trusted at `now`.

```ts
isStateFresh(state: CapabilityState, now: Instant): boolean
```

#### Lifecycle

```ts
(typeof LIFECYCLES)[number];
```

#### LIFECYCLES

Values: `experimental`, `beta`, `general-availability`, `deprecated`, `retired`

#### matchCapabilityState

A TOTAL match over the five states.

```ts
matchCapabilityState(state: CapabilityState, handlers: CapabilityStateHandlers<T>): T
```

#### mergeCapabilitySources

Merge plugin-supplied registries, refusing collisions.

```ts
mergeCapabilitySources(sources: readonly CapabilitySource[]): MergeResult
```

#### MergeCollision

| Field     | Type                | Required | Notes |
| --------- | ------------------- | -------- | ----- |
| `id`      | `string`            | required | —     |
| `sources` | `readonly string[]` | required | —     |

#### MergeResult

```ts
| { readonly ok: true; readonly entries: readonly CapabilityDescriptor[] }
| { readonly ok: false; readonly collisions: readonly MergeCollision[] }
```

#### MissingConfiguration

A setting that is absent.

| Field         | Type                                            | Required | Notes |
| ------------- | ----------------------------------------------- | -------- | ----- |
| `category`    | [ConfigurationCategory](#configurationcategory) | required | —     |
| `settingName` | `string`                                        | required | —     |

#### NotConfiguredState

| Field                 | Type                                                                              | Required | Notes                                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `state`               | `'not_configured'`                                                                | required | —                                                                                                                      |
| `missing`             | `readonly MissingConfiguration[]` — [MissingConfiguration](#missingconfiguration) | required | —                                                                                                                      |
| `resolutionAuthority` | `'self-service' \| 'tenant-admin' \| 'platform-operator'`                         | required | Who may fix it, so the answer is actionable by the person reading it rather than by somebody they have to go and find. |

#### parseCapabilityDescriptor

```ts
parseCapabilityDescriptor(input: unknown): ParseResult<CapabilityDescriptor>
```

#### parseCapabilityState

```ts
parseCapabilityState(input: unknown): ParseResult<CapabilityState>
```

#### parseSafeDetail

```ts
parseSafeDetail(input: unknown, field: string): ParseResult<string>
```

#### parseSemanticVersion

A strict semantic version, with no build metadata and no `v` prefix.

```ts
parseSemanticVersion(input: unknown): ParseResult<SemanticVersion>
```

#### parseTypedReference

```ts
parseTypedReference(input: unknown): ParseResult<TypedReference>
```

#### PROBE_KINDS

Values: `liveness`, `readiness`, `capability`

#### ProbeKind

```ts
(typeof PROBE_KINDS)[number];
```

#### probeProjection

What a runtime should execute, in a stable order.

```ts
probeProjection(entries: readonly CapabilityDescriptor[]): readonly ProbeProjectionRow[]
```

#### ProbeProjectionRow

| Field             | Type                              | Required | Notes |
| ----------------- | --------------------------------- | -------- | ----- |
| `capability`      | `string`                          | required | —     |
| `probe`           | `string`                          | required | —     |
| `kind`            | [ProbeKind](#probekind)           | required | —     |
| `intervalSeconds` | `number`                          | required | —     |
| `hosts`           | `readonly Host[]` — [Host](#host) | required | —     |
| `runtime`         | [Runtime](#runtime)               | required | —     |

#### projectionCoverage

Every entry must appear in the reference projection, and every entry with probes
must appear in the probe projection.

```ts
projectionCoverage(entries: readonly CapabilityDescriptor[]): { readonly missingFromReference: readonly string[]; readonly missingFromProbes: readonly string[]; }
```

#### REFERENCE_KINDS

Values: `command`, `query`, `job`, `route`, `block`, `gate`, `transfer`,
`publisher-feature`

#### ReferenceKind

```ts
(typeof REFERENCE_KINDS)[number];
```

#### referenceProjection

What a human or an API reference page needs, in a stable order.

```ts
referenceProjection(entries: readonly CapabilityDescriptor[]): readonly ReferenceProjectionRow[]
```

#### ReferenceProjectionRow

| Field                 | Type                                          | Required | Notes |
| --------------------- | --------------------------------------------- | -------- | ----- |
| `capability`          | `string`                                      | required | —     |
| `version`             | `string`                                      | required | —     |
| `owner`               | `string`                                      | required | —     |
| `domain`              | `string`                                      | required | —     |
| `lifecycle`           | [Lifecycle](#lifecycle)                       | required | —     |
| `audiences`           | `readonly Audience[]` — [Audience](#audience) | required | —     |
| `description`         | `string`                                      | required | —     |
| `requires`            | `readonly string[]`                           | required | —     |
| `provides`            | `readonly string[]`                           | required | —     |
| `surface`             | `readonly string[]`                           | required | —     |
| `dataClassification`  | [DataClassification](#dataclassification)     | required | —     |
| `authorizationScopes` | `readonly string[]`                           | required | —     |

#### RegistryValidationOptions

| Field            | Type                | Required | Notes                                                                       |
| ---------------- | ------------------- | -------- | --------------------------------------------------------------------------- |
| `knownOwners`    | `readonly string[]` | optional | Owners the organisation recognises. Empty means the check does not run.     |
| `knownContracts` | `readonly string[]` | optional | Contract names some capability must provide before another may consume one. |

#### RegistryViolation

| Field     | Type                                                                                                                                                                                                           | Required | Notes |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----- |
| `kind`    | `\| 'duplicate-id' \| 'duplicate-alias' \| 'alias-shadows-id' \| 'unknown-owner' \| 'undeclared-dependency' \| 'dependency-cycle' \| 'retired-still-required' \| 'unknown-successor' \| 'unprovided-contract'` | required | —     |
| `subject` | `string`                                                                                                                                                                                                       | required | —     |
| `detail`  | `string`                                                                                                                                                                                                       | required | —     |

#### REQUIRED_VERIFICATIONS

The four things that must be VERIFIED before a capability may call itself
configured.

Values: `configuration`, `dependencies`, `permissions`, `versions`

#### RESOURCE_KINDS

Values: `gpu`, `cpu-burst`, `object-storage`, `relational-storage`,
`network-egress`, `third-party-quota`

#### ResourceKind

```ts
(typeof RESOURCE_KINDS)[number];
```

#### ResourceNeed

| Field    | Type                          | Required | Notes |
| -------- | ----------------------------- | -------- | ----- |
| `kind`   | [ResourceKind](#resourcekind) | required | —     |
| `detail` | `string`                      | required | —     |

#### RetryMetadata

| Field          | Type                                | Required | Notes                                                                       |
| -------------- | ----------------------------------- | -------- | --------------------------------------------------------------------------- |
| `retryable`    | `boolean`                           | required | —                                                                           |
| `afterSeconds` | `number \| null`                    | required | Null when not retryable. A cooldown for a permanent failure is a busy loop. |
| `attemptsMade` | `number`                            | required | —                                                                           |
| `circuit`      | [CircuitPosition](#circuitposition) | required | —                                                                           |

#### Runtime

```ts
(typeof RUNTIMES)[number];
```

#### RUNTIMES

Values: `browser`, `server`, `isomorphic`

#### SemanticVersion

| Field        | Type             | Required | Notes                                                      |
| ------------ | ---------------- | -------- | ---------------------------------------------------------- |
| `major`      | `number`         | required | —                                                          |
| `minor`      | `number`         | required | —                                                          |
| `patch`      | `number`         | required | —                                                          |
| `prerelease` | `string \| null` | required | Dot-separated identifiers, or null when this is a release. |

#### Slo

The service-level objective.

| Field                  | Type     | Required | Notes |
| ---------------------- | -------- | -------- | ----- |
| `availabilityTarget`   | `number` | required | —     |
| `latencyP95Ms`         | `number` | required | —     |
| `evaluationWindowDays` | `number` | required | —     |

#### TypedReference

`<kind>:<dotted.name>`.

| Field  | Type                            | Required | Notes |
| ------ | ------------------------------- | -------- | ----- |
| `kind` | [ReferenceKind](#referencekind) | required | —     |
| `name` | `string`                        | required | —     |

#### UnavailableState

| Field         | Type                                     | Required | Notes                                    |
| ------------- | ---------------------------------------- | -------- | ---------------------------------------- |
| `state`       | `'unavailable'`                          | required | —                                        |
| `disposition` | `'transient' \| 'terminal' \| 'unknown'` | required | Whether the dependency is expected back. |
| `retry`       | [RetryMetadata](#retrymetadata)          | required | —                                        |
| `blockedOn`   | `readonly string[]`                      | required | —                                        |

#### usability

How much of the capability a caller may rely on. THREE-valued, deliberately.

```ts
usability(state: CapabilityState): Usability
```

#### Usability

```ts
'full' | 'reduced' | 'none';
```

#### validateRegistry

Validate a whole registry.

```ts
validateRegistry(entries: readonly CapabilityDescriptor[], options: RegistryValidationOptions = {}): readonly RegistryViolation[]
```

#### Verification

| Field       | Type                                        | Required | Notes                                                                       |
| ----------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `subject`   | [VerificationSubject](#verificationsubject) | required | —                                                                           |
| `checkedAt` | [Instant](./identity.md#instant)            | required | —                                                                           |
| `detail`    | `string`                                    | required | What was actually checked. Not "ok" — a detail nobody can audit is a claim. |

#### VerificationSubject

```ts
(typeof REQUIRED_VERIFICATIONS)[number];
```

## Valid examples

No committed fixture corpus covers this page's accepted cases; they are
unit-level and live in the module's own spec.

## Invalid examples

##### descriptor/admin-scopes-without-elevation

one of the two is wrong, and the permissive reading is the one that ships

Must produce: `invariant-violated`

```json
{
  "aliases": [],
  "audiences": ["creator"],
  "auditEvents": [],
  "authorizationScopes": ["tenant:admin", "platform:admin"],
  "configuration": [],
  "cost": null,
  "dataClassification": "internal",
  "description": "a capability",
  "domain": "shared",
  "fixturePolicy": "synthetic-only",
  "hosts": ["studio-web"],
  "id": "capability:x",
  "lifecycle": "general-availability",
  "metrics": ["requests_total"],
  "optional": [],
  "owner": "shared-platform",
  "probes": [],
  "provides": [],
  "references": [],
  "requires": [],
  "requiresElevation": false,
  "resources": [],
  "runtime": "isomorphic",
  "slo": {
    "availabilityTarget": 0.99,
    "evaluationWindowDays": 28,
    "latencyP95Ms": 500
  },
  "supersededBy": null,
  "trustControls": [],
  "version": "1.0.0"
}
```

##### descriptor/dependency-both-required-and-optional

a caller reading either list alone gets the opposite answer about whether it can
run without it

Must produce: `invariant-violated`

```json
{
  "aliases": [],
  "audiences": ["creator"],
  "auditEvents": [],
  "authorizationScopes": ["workbench:read"],
  "configuration": [],
  "cost": null,
  "dataClassification": "internal",
  "description": "a capability",
  "domain": "shared",
  "fixturePolicy": "synthetic-only",
  "hosts": ["studio-web"],
  "id": "capability:x",
  "lifecycle": "general-availability",
  "metrics": ["requests_total"],
  "optional": ["capability:y"],
  "owner": "shared-platform",
  "probes": [],
  "provides": [],
  "references": [],
  "requires": ["capability:y"],
  "requiresElevation": false,
  "resources": [],
  "runtime": "isomorphic",
  "slo": {
    "availabilityTarget": 0.99,
    "evaluationWindowDays": 28,
    "latencyP95Ms": 500
  },
  "supersededBy": null,
  "trustControls": [],
  "version": "1.0.0"
}
```

##### descriptor/deprecated-without-successor

a deprecation with no replacement is an instruction to stop with no instruction
to start, which is why nobody migrates

Must produce: `invariant-violated`

```json
{
  "aliases": [],
  "audiences": ["creator"],
  "auditEvents": [],
  "authorizationScopes": ["workbench:read"],
  "configuration": [],
  "cost": null,
  "dataClassification": "internal",
  "description": "a capability",
  "domain": "shared",
  "fixturePolicy": "synthetic-only",
  "hosts": ["studio-web"],
  "id": "capability:x",
  "lifecycle": "deprecated",
  "metrics": ["requests_total"],
  "optional": [],
  "owner": "shared-platform",
  "probes": [],
  "provides": [],
  "references": [],
  "requires": [],
  "requiresElevation": false,
  "resources": [],
  "runtime": "isomorphic",
  "slo": {
    "availabilityTarget": 0.99,
    "evaluationWindowDays": 28,
    "latencyP95Ms": 500
  },
  "supersededBy": null,
  "trustControls": [],
  "version": "1.0.0"
}
```

3 of 17 refused case(s) shown. The full corpus is committed at
`evidence/v1-workbenches/workbench-kit-registry-fixtures.json` and is what the
gate runs.

## Authorization and scope

| Symbol                                       | Type                | Notes |
| -------------------------------------------- | ------------------- | ----- |
| `CapabilityDescriptor.authorizationScopes`   | `readonly string[]` | —     |
| `ReferenceProjectionRow.authorizationScopes` | `readonly string[]` | —     |

## Idempotency and concurrency

| Symbol                       | Type     | Notes |
| ---------------------------- | -------- | ----- |
| `RetryMetadata.attemptsMade` | `number` | —     |

## Pagination

| Symbol                | Type       | Notes                                                                                                                 |
| --------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
| `probeProjection`     | `function` | What a runtime should execute, in a stable order.                                                                     |
| `projectionCoverage`  | `function` | Every entry must appear in the reference projection, and every entry with probes must appear in the probe projection. |
| `referenceProjection` | `function` | What a human or an API reference page needs, in a stable order.                                                       |

## State and failure

| Symbol                                | Type                             | Notes                                            |
| ------------------------------------- | -------------------------------- | ------------------------------------------------ |
| `CapabilityDependency.state`          | `CapabilityStateName`            | —                                                |
| `CapabilityState`                     | `type`                           | —                                                |
| `CapabilityStateHandlers.degraded`    | `(state: DegradedState) => T`    | —                                                |
| `CapabilityStateHandlers.unavailable` | `(state: UnavailableState) => T` | —                                                |
| `ConfiguredState.state`               | `'configured'`                   | —                                                |
| `DegradedState.state`                 | `'degraded'`                     | —                                                |
| `FailedState.failureClass`            | `FailureClass`                   | —                                                |
| `FailedState.state`                   | `'failed'`                       | —                                                |
| `FAILURE_CLASSES`                     | `enumeration`                    | A STABLE error class, not a message.             |
| `FailureClass`                        | `type`                           | —                                                |
| `isStateFresh`                        | `function`                       | Whether an answer may still be trusted at `now`. |
| `matchCapabilityState`                | `function`                       | A TOTAL match over the five states.              |
| `NotConfiguredState.state`            | `'not_configured'`               | —                                                |
| `parseCapabilityState`                | `function`                       | —                                                |
| `UnavailableState.state`              | `'unavailable'`                  | —                                                |

## Compatibility

| Symbol                                    | Type              | Notes                                                                 |
| ----------------------------------------- | ----------------- | --------------------------------------------------------------------- |
| `CapabilityDescriptor.version`            | `SemanticVersion` | —                                                                     |
| `CapabilityStateCommon.capabilityVersion` | `string`          | —                                                                     |
| `compareSemanticVersions`                 | `function`        | Semver precedence: -1, 0 or 1. A prerelease sorts BEFORE its release. |
| `formatSemanticVersion`                   | `function`        | —                                                                     |
| `parseSemanticVersion`                    | `function`        | A strict semantic version, with no build metadata and no `v` prefix.  |
| `ReferenceProjectionRow.version`          | `string`          | —                                                                     |

## Deprecation

| Symbol                             | Type          | Notes |
| ---------------------------------- | ------------- | ----- |
| `CapabilityDescriptor.lifecycle`   | `Lifecycle`   | —     |
| `Lifecycle`                        | `type`        | —     |
| `LIFECYCLES`                       | `enumeration` | —     |
| `ReferenceProjectionRow.lifecycle` | `Lifecycle`   | —     |

## Evidence

- `evidence/v1-workbenches/workbench-kit-export-map.json`
- `evidence/v1-workbenches/workbench-kit-registry-fixtures.json`
- `libs/oshun/workbench-kit/src/capability-state.ts`
- `libs/oshun/workbench-kit/src/registry.ts`
