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.tssrc/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 | type | — |
| AUDIENCES | enumeration | — |
| CapabilityDependency | interface | — |
| CapabilityDescriptor | interface | — |
| CapabilityOwner | interface | Who to ask when a capability is not configured. |
| CapabilitySource | interface | — |
| CapabilityState | type | — |
| CapabilityStateCommon | interface | Fields every state carries, whatever it is. |
| CapabilityStateHandlers | interface | — |
| CIRCUIT_POSITIONS | enumeration | — |
| CircuitPosition | type | — |
| compareSemanticVersions | function | Semver precedence: -1, 0 or 1. A prerelease sorts BEFORE its release. |
| CONFIGURATION_CATEGORIES | enumeration | — |
| ConfigurationCategory | type | — |
| ConfigurationReference | interface | — |
| ConfiguredState | interface | — |
| CostModel | interface | — |
| DATA_CLASSIFICATIONS | enumeration | — |
| DataClassification | type | — |
| DegradedState | interface | — |
| FailedState | interface | — |
| FAILURE_CLASSES | enumeration | A STABLE error class, not a message. |
| FailureClass | type | — |
| findCycles | function | Every dependency cycle, as a path that returns to its start. |
| FIXTURE_POLICIES | enumeration | — |
| FixturePolicy | type | — |
| formatSemanticVersion | function | — |
| formatTypedReference | function | — |
| HealthProbe | interface | — |
| Host | type | — |
| HOSTS | enumeration | — |
| isStateFresh | function | Whether an answer may still be trusted at now. |
| Lifecycle | type | — |
| LIFECYCLES | enumeration | — |
| matchCapabilityState | function | A TOTAL match over the five states. |
| mergeCapabilitySources | function | Merge plugin-supplied registries, refusing collisions. |
| MergeCollision | interface | — |
| MergeResult | type | — |
| MissingConfiguration | interface | A setting that is absent. |
| NotConfiguredState | interface | — |
| parseCapabilityDescriptor | function | — |
| parseCapabilityState | function | — |
| parseSafeDetail | function | — |
| parseSemanticVersion | function | A strict semantic version, with no build metadata and no v prefix. |
| parseTypedReference | function | — |
| PROBE_KINDS | enumeration | — |
| ProbeKind | type | — |
| probeProjection | function | What a runtime should execute, in a stable order. |
| ProbeProjectionRow | interface | — |
| projectionCoverage | function | Every entry must appear in the reference projection, and every entry with probes must appear in the probe projection. |
| REFERENCE_KINDS | enumeration | — |
| ReferenceKind | type | — |
| referenceProjection | function | What a human or an API reference page needs, in a stable order. |
| ReferenceProjectionRow | interface | — |
| RegistryValidationOptions | interface | — |
| RegistryViolation | interface | — |
| REQUIRED_VERIFICATIONS | enumeration | The four things that must be VERIFIED before a capability may call itself configured. |
| RESOURCE_KINDS | enumeration | — |
| ResourceKind | type | — |
| ResourceNeed | interface | — |
| RetryMetadata | interface | — |
| Runtime | type | — |
| RUNTIMES | enumeration | — |
| SemanticVersion | interface | — |
| Slo | interface | The service-level objective. |
| TypedReference | interface | <kind>:<dotted.name>. |
| UnavailableState | interface | — |
| usability | function | How much of the capability a caller may rely on. THREE-valued, deliberately. |
| Usability | type | — |
| validateRegistry | function | Validate a whole registry. |
| Verification | interface | — |
| VerificationSubject | type | — |
Shapes#
Audience#
(typeof AUDIENCES)[number];
AUDIENCES#
Values: creator, reviewer, operator, learner, viewer, system
CapabilityDependency#
| Field | Type | Required | Notes |
|---|---|---|---|
dependency |
string |
required | — |
state |
CapabilityStateName | required | — |
detail |
string |
required | — |
CapabilityDescriptor#
| Field | Type | Required | Notes |
|---|---|---|---|
id |
CapabilityId | required | — |
aliases |
readonly string[] |
required | — |
version |
SemanticVersion | required | — |
owner |
string |
required | — |
domain |
string |
required | — |
audiences |
readonly Audience[] — Audience |
required | — |
hosts |
readonly Host[] — Host |
required | — |
runtime |
Runtime | required | — |
lifecycle |
Lifecycle | required | — |
description |
string |
required | — |
supersededBy |
CapabilityId | null — CapabilityId |
required | Required when lifecycle is deprecated or retired. |
requires |
readonly CapabilityId[] — CapabilityId |
required | — |
optional |
readonly CapabilityId[] — CapabilityId |
required | — |
provides |
readonly string[] |
required | — |
configuration |
readonly ConfigurationReference[] — ConfigurationReference |
required | — |
resources |
readonly ResourceNeed[] — ResourceNeed |
required | — |
probes |
readonly HealthProbe[] — HealthProbe |
required | — |
references |
readonly TypedReference[] — TypedReference |
required | — |
authorizationScopes |
readonly string[] |
required | — |
requiresElevation |
boolean |
required | — |
dataClassification |
DataClassification | required | — |
trustControls |
readonly string[] |
required | — |
metrics |
readonly string[] |
required | — |
auditEvents |
readonly string[] |
required | — |
slo |
Slo | required | — |
cost |
CostModel | null — CostModel |
required | — |
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 |
required | — |
CapabilityState#
| ConfiguredState
| NotConfiguredState
| DegradedState
| UnavailableState
| FailedState
CapabilityStateCommon#
Fields every state carries, whatever it is.
| Field | Type | Required | Notes |
|---|---|---|---|
capability |
CapabilityId | required | — |
capabilityVersion |
string |
required | — |
checkedAt |
Instant | required | — |
freshnessSeconds |
number |
required | How long this answer may be trusted. 0 means it must not be cached. |
dependencies |
readonly CapabilityDependency[] — CapabilityDependency |
required | — |
owner |
CapabilityOwner | required | — |
limitations |
readonly string[] |
required | What a caller would otherwise wrongly assume works. |
remediation |
Remediation | required | — |
safeDetail |
string |
required | One human sentence, checked for credentials. |
CapabilityStateHandlers#
| Field | Type | Required | Notes |
|---|---|---|---|
configured |
(state: ConfiguredState) => T — ConfiguredState |
required | — |
not_configured |
(state: NotConfiguredState) => T — NotConfiguredState |
required | — |
degraded |
(state: DegradedState) => T — DegradedState |
required | — |
unavailable |
(state: UnavailableState) => T — UnavailableState |
required | — |
failed |
(state: FailedState) => T — FailedState |
required | — |
CIRCUIT_POSITIONS#
Values: closed, open, half-open
CircuitPosition#
(typeof CIRCUIT_POSITIONS)[number];
compareSemanticVersions#
Semver precedence: -1, 0 or 1. A prerelease sorts BEFORE its release.
compareSemanticVersions(a: SemanticVersion, b: SemanticVersion): number
CONFIGURATION_CATEGORIES#
Values: credential, endpoint, quota, feature-flag, tenant-binding,
model-selection
ConfigurationCategory#
(typeof CONFIGURATION_CATEGORIES)[number];
ConfigurationReference#
| Field | Type | Required | Notes |
|---|---|---|---|
settingName |
string |
required | — |
category |
ConfigurationCategory | required | — |
required |
boolean |
required | — |
ConfiguredState#
| Field | Type | Required | Notes |
|---|---|---|---|
state |
'configured' — configured |
required | — |
verifications |
readonly 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#
(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 |
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 | required | — |
correlationId |
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#
(typeof FAILURE_CLASSES)[number];
findCycles#
Every dependency cycle, as a path that returns to its start.
findCycles(byId: ReadonlyMap<string, CapabilityDescriptor>): readonly string[][]
FIXTURE_POLICIES#
Values: synthetic-only, anonymized, production-copy
FixturePolicy#
(typeof FIXTURE_POLICIES)[number];
formatSemanticVersion#
formatSemanticVersion(version: SemanticVersion): string
formatTypedReference#
formatTypedReference(reference: TypedReference): string
HealthProbe#
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string |
required | — |
kind |
ProbeKind | required | — |
intervalSeconds |
number |
required | How often a runtime should run it. Bounded below, so a probe cannot busy-loop. |
Host#
(typeof HOSTS)[number];
HOSTS#
Values: studio-web, studio-desktop, operator-console, bff, worker,
cli
isStateFresh#
Whether an answer may still be trusted at now.
isStateFresh(state: CapabilityState, now: Instant): boolean
Lifecycle#
(typeof LIFECYCLES)[number];
LIFECYCLES#
Values: experimental, beta, general-availability, deprecated, retired
matchCapabilityState#
A TOTAL match over the five states.
matchCapabilityState(state: CapabilityState, handlers: CapabilityStateHandlers<T>): T
mergeCapabilitySources#
Merge plugin-supplied registries, refusing collisions.
mergeCapabilitySources(sources: readonly CapabilitySource[]): MergeResult
MergeCollision#
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string |
required | — |
sources |
readonly string[] |
required | — |
MergeResult#
| { 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 | required | — |
settingName |
string |
required | — |
NotConfiguredState#
| Field | Type | Required | Notes |
|---|---|---|---|
state |
'not_configured' |
required | — |
missing |
readonly 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#
parseCapabilityDescriptor(input: unknown): ParseResult<CapabilityDescriptor>
parseCapabilityState#
parseCapabilityState(input: unknown): ParseResult<CapabilityState>
parseSafeDetail#
parseSafeDetail(input: unknown, field: string): ParseResult<string>
parseSemanticVersion#
A strict semantic version, with no build metadata and no v prefix.
parseSemanticVersion(input: unknown): ParseResult<SemanticVersion>
parseTypedReference#
parseTypedReference(input: unknown): ParseResult<TypedReference>
PROBE_KINDS#
Values: liveness, readiness, capability
ProbeKind#
(typeof PROBE_KINDS)[number];
probeProjection#
What a runtime should execute, in a stable order.
probeProjection(entries: readonly CapabilityDescriptor[]): readonly ProbeProjectionRow[]
ProbeProjectionRow#
| Field | Type | Required | Notes |
|---|---|---|---|
capability |
string |
required | — |
probe |
string |
required | — |
kind |
ProbeKind | required | — |
intervalSeconds |
number |
required | — |
hosts |
readonly Host[] — Host |
required | — |
runtime |
Runtime | required | — |
projectionCoverage#
Every entry must appear in the reference projection, and every entry with probes must appear in the probe projection.
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#
(typeof REFERENCE_KINDS)[number];
referenceProjection#
What a human or an API reference page needs, in a stable order.
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 | required | — |
audiences |
readonly Audience[] — Audience |
required | — |
description |
string |
required | — |
requires |
readonly string[] |
required | — |
provides |
readonly string[] |
required | — |
surface |
readonly string[] |
required | — |
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#
(typeof RESOURCE_KINDS)[number];
ResourceNeed#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
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 | required | — |
Runtime#
(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 | 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 | required | — |
blockedOn |
readonly string[] |
required | — |
usability#
How much of the capability a caller may rely on. THREE-valued, deliberately.
usability(state: CapabilityState): Usability
Usability#
'full' | 'reduced' | 'none';
validateRegistry#
Validate a whole registry.
validateRegistry(entries: readonly CapabilityDescriptor[], options: RegistryValidationOptions = {}): readonly RegistryViolation[]
Verification#
| Field | Type | Required | Notes |
|---|---|---|---|
subject |
VerificationSubject | required | — |
checkedAt |
Instant | required | — |
detail |
string |
required | What was actually checked. Not "ok" — a detail nobody can audit is a claim. |
VerificationSubject#
(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
{
"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
{
"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
{
"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.jsonevidence/v1-workbenches/workbench-kit-registry-fixtures.jsonlibs/oshun/workbench-kit/src/capability-state.tslibs/oshun/workbench-kit/src/registry.ts