Eve library

Capability

Evidence

Revision 1

On this page

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 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#

ts
(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#

ts
| 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#

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 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#

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 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#

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 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 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#

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 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.

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 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#

ts
(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#

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 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.

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 required —
checkedAt 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