The fields every envelope carries, the one open field, and how a version is read off the wire.
Generated from libs/oshun/workbench-kit/src/envelopes.ts by
node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger:
S1.5. Do not edit by hand.
Summary#
src/envelopes.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/envelopes |
contract |
S1.5 |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| AnyEnvelope | type | — |
| CAPABILITY_STATES | enumeration | The five states, named here and given their full record shape in S1.6. |
| CapabilityProbeEnvelope | interface | — |
| CapabilityStateName | type | — |
| commandAuthorizationMismatch | function | The privilege-confusion check the two-field split exists to make possible. |
| CommandEnvelope | interface | — |
| Consistency | type | — |
| Cost | interface | Money as integer minor units. |
| CURRENT_SCHEMA_VERSION | constant | The schema this build writes and the oldest it reads. |
| dedupeKey | function | The key an at-least-once consumer deduplicates on. |
| DeliveryCompatibility | type | — |
| DependencyStatus | interface | — |
| ENVELOPE_KINDS | enumeration | — |
| EnvelopeCommon | interface | — |
| EnvelopeKind | type | — |
| EventEnvelope | interface | — |
| isExpired | function | Whether a command may still be applied at now. |
| isProbeFresh | function | Whether a probe answer may still be trusted at now. |
| isProgressRegression | function | Whether next reports LESS progress than prev for the same job and attempt. |
| isTerminal | function | — |
| JobOutcome | type | — |
| JobUpdateEnvelope | interface | — |
| JsonValue | type | — |
| MAX_ENVELOPE_BYTES | constant | 256 KiB, measured on the serialized bytes. |
| MAX_PAGE_SIZE | constant | — |
| MIN_SUPPORTED_SCHEMA_VERSION | constant | — |
| Pagination | type | — |
| parseCapabilityProbeEnvelope | function | — |
| parseCommandEnvelope | function | — |
| parseEnvelope | function | Dispatch on kind without the caller having to know the five parsers. |
| parseEnvelopeJson | function | Parse from the wire, where oversized actually arrives. |
| parseEventEnvelope | function | — |
| parseExtensions | function | — |
| parseJobUpdateEnvelope | function | — |
| parseQueryEnvelope | function | — |
| QueryEnvelope | interface | — |
| Remediation | interface | — |
| REMEDIATION_ACTIONS | enumeration | Remediation, as a STRUCTURE rather than free text. |
| RemediationAction | type | — |
| Usage | interface | — |
| utf8ByteLength | function | UTF-8 byte length, computed rather than delegated to TextEncoder. |
| versionCompatibility | function | Whether this build may read an envelope written against schemaVersion. |
| VersionCompatibility | type | — |
Shapes#
AnyEnvelope#
| CommandEnvelope
| QueryEnvelope
| EventEnvelope
| JobUpdateEnvelope
| CapabilityProbeEnvelope
CAPABILITY_STATES#
The five states, named here and given their full record shape in S1.6.
Values: configured, not_configured, degraded, unavailable, failed
CapabilityProbeEnvelope#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
'capability-probe' |
required | — |
capability |
CapabilityId | required | — |
capabilityVersion |
string |
required | The implementation version probed, so a stale answer is identifiable. |
state |
CapabilityStateName | required | — |
dependencies |
readonly DependencyStatus[] — DependencyStatus |
required | — |
checkedAt |
Instant | required | — |
freshnessSeconds |
number |
required | How long this answer may be trusted. 0 would mean "never cache". |
limitations |
readonly string[] |
required | What works less well than a caller would assume. |
remediation |
Remediation | required | — |
CapabilityStateName#
(typeof CAPABILITY_STATES)[number];
commandAuthorizationMismatch#
The privilege-confusion check the two-field split exists to make possible.
commandAuthorizationMismatch(command: CommandEnvelope, grantedUnder: string): string | null
CommandEnvelope#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
'command' |
required | — |
operation |
string |
required | — |
subject |
EntityId | required | — |
idempotencyKey |
string |
required | — |
expectedRevision |
RevisionId | null — RevisionId |
required | Null when creating; a revision when updating. Optimistic concurrency. |
deadline |
Instant | required | After this instant the command must not be applied, only reported expired. |
authorizationIntent |
string |
required | The grant the caller CLAIMS to need — an intent, not a verdict. |
payload |
TPayload |
required | — |
Consistency#
| { readonly level: 'strong' }
| { readonly level: 'bounded-staleness'; readonly maxStalenessSeconds: number }
| { readonly level: 'eventual' }
Cost#
Money as integer minor units.
| Field | Type | Required | Notes |
|---|---|---|---|
currency |
string |
required | — |
amountMinor |
number |
required | — |
CURRENT_SCHEMA_VERSION#
The schema this build writes and the oldest it reads.
Value: 1
dedupeKey#
The key an at-least-once consumer deduplicates on.
dedupeKey(event: EventEnvelope): string
DeliveryCompatibility#
'at-least-once' | 'exactly-once-per-subject';
DependencyStatus#
| Field | Type | Required | Notes |
|---|---|---|---|
dependency |
string |
required | — |
state |
CapabilityStateName | required | — |
detail |
string |
required | — |
ENVELOPE_KINDS#
Values: command, query, event, job-update, capability-probe
EnvelopeCommon#
| Field | Type | Required | Notes |
|---|---|---|---|
envelopeId |
EnvelopeId | required | — |
kind |
EnvelopeKind | required | — |
schemaVersion |
number |
required | — |
occurredAt |
Instant | required | — |
tenant |
TenantId | required | — |
workbench |
WorkbenchId | required | — |
actor |
ActorRef | required | — |
correlationId |
CorrelationId | required | — |
traceId |
string | null |
required | Null when tracing is off. Never a substitute for correlationId. |
extensions |
{ readonly [key: string]: JsonValue } — JsonValue |
required | The only open field. Keys are <vendor>.<name>; the kit never reads them. |
EnvelopeKind#
(typeof ENVELOPE_KINDS)[number];
EventEnvelope#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
'event' |
required | — |
producer |
string |
required | The component that emitted it. Not the actor — a retry has the same actor. |
eventType |
string |
required | — |
subject |
EntityId | required | — |
sequence |
number |
required | Monotonic per subject. What makes at-least-once delivery deduplicable. |
causationId |
EnvelopeId | null — EnvelopeId |
required | The envelope that caused this one. Null for an externally-triggered event. |
delivery |
DeliveryCompatibility | required | — |
payload |
TPayload |
required | — |
isExpired#
Whether a command may still be applied at now.
isExpired(command: CommandEnvelope, now: Instant): boolean
isProbeFresh#
Whether a probe answer may still be trusted at now.
isProbeFresh(probe: CapabilityProbeEnvelope, now: Instant): boolean
isProgressRegression#
Whether next reports LESS progress than prev for the same job and attempt.
isProgressRegression(prev: JobUpdateEnvelope, next: JobUpdateEnvelope): boolean
isTerminal#
isTerminal(outcome: JobOutcome): boolean
JobOutcome#
| { readonly status: 'running' }
| { readonly status: 'succeeded'; readonly output: ArtifactRef }
| { readonly status: 'failed'; readonly errorCode: string; readonly errorMessage: string; readonly retryable: boolean; }
| { readonly status: 'cancelled'; readonly reason: string }
JobUpdateEnvelope#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
'job-update' |
required | — |
jobId |
JobId | required | — |
attempt |
number |
required | 1-based. Attempt 0 would mean the job never ran, which is not an update. |
stage |
string |
required | — |
progress |
number | null |
required | 0..1, or null when the work is genuinely indeterminate. |
checkpoint |
string | null |
required | Opaque resume token. Forbidden on a terminal outcome — nothing to resume. |
usage |
Usage | null — Usage |
required | — |
outcome |
JobOutcome | required | — |
JsonValue#
| string
| number
| boolean
| null
| readonly JsonValue[]
| { readonly [key: string]: JsonValue }
MAX_ENVELOPE_BYTES#
256 KiB, measured on the serialized bytes.
MAX_PAGE_SIZE#
Value: 200
MIN_SUPPORTED_SCHEMA_VERSION#
Value: 1
Pagination#
| { readonly mode: 'cursor'; readonly cursor: string | null; readonly pageSize: number }
| { readonly mode: 'offset'; readonly offset: number; readonly pageSize: number }
parseCapabilityProbeEnvelope#
parseCapabilityProbeEnvelope(input: unknown): ParseResult<CapabilityProbeEnvelope>
parseCommandEnvelope#
parseCommandEnvelope(input: unknown): ParseResult<CommandEnvelope>
parseEnvelope#
Dispatch on kind without the caller having to know the five parsers.
parseEnvelope(input: unknown): ParseResult<AnyEnvelope>
parseEnvelopeJson#
Parse from the wire, where oversized actually arrives.
parseEnvelopeJson(text: string): ParseResult<AnyEnvelope>
parseEventEnvelope#
parseEventEnvelope(input: unknown): ParseResult<EventEnvelope>
parseExtensions#
parseExtensions(input: unknown): ParseResult<{ readonly [key: string]: JsonValue }>
parseJobUpdateEnvelope#
parseJobUpdateEnvelope(input: unknown): ParseResult<JobUpdateEnvelope>
parseQueryEnvelope#
parseQueryEnvelope(input: unknown): ParseResult<QueryEnvelope>
QueryEnvelope#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
'query' |
required | — |
resource |
string |
required | — |
filters |
{ readonly [field: string]: JsonValue } — JsonValue |
required | Field path -> matcher. Typed by the resource, opaque to the kit. |
pagination |
Pagination | required | — |
consistency |
Consistency | required | — |
locale |
string |
required | BCP-47. Required, because "the server's locale" is nobody's locale. |
projection |
readonly string[] |
required | Field paths to return. Empty array means the resource's default shape. |
payload |
TPayload |
required | — |
Remediation#
| Field | Type | Required | Notes |
|---|---|---|---|
action |
RemediationAction | required | — |
docsUrl |
string | null |
required | Where the steps live. Never the steps themselves, and never a credential. |
requiresOperator |
boolean |
required | True when a human with elevated access must act; false when self-service. |
REMEDIATION_ACTIONS#
Remediation, as a STRUCTURE rather than free text.
Values: none, configure-credentials, grant-permission,
upgrade-dependency, increase-quota, restore-connectivity, contact-owner,
reload-and-compare
RemediationAction#
(typeof REMEDIATION_ACTIONS)[number];
Usage#
| Field | Type | Required | Notes |
|---|---|---|---|
unit |
string |
required | — |
quantity |
number |
required | — |
cost |
Cost | null — Cost |
required | — |
utf8ByteLength#
UTF-8 byte length, computed rather than delegated to TextEncoder.
utf8ByteLength(text: string): number
versionCompatibility#
Whether this build may read an envelope written against schemaVersion.
versionCompatibility(schemaVersion: number, parses: boolean): VersionCompatibility
VersionCompatibility#
| 'same'
| 'older-supported'
| 'older-unsupported'
| 'newer-tolerated'
| 'newer-unsupported'
Valid examples#
probe/configured-accepted#
a working capability offers no remediation, because there is nothing to remediate
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"capability": "capability:image-generation",
"capabilityVersion": "3.1.0",
"checkedAt": "2026-07-29T09:59:00Z",
"correlationId": "correlation:publish-42",
"dependencies": [
{
"dependency": "provider-api",
"detail": "credentials present, v3 supported",
"state": "configured"
}
],
"envelopeId": "envelope:e1",
"extensions": {},
"freshnessSeconds": 300,
"kind": "capability-probe",
"limitations": [],
"occurredAt": "2026-07-29T10:00:00Z",
"remediation": {
"action": "none",
"docsUrl": null,
"requiresOperator": false
},
"schemaVersion": 1,
"state": "configured",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
probe/degraded-with-remediation#
a degraded capability names both what works less well and what would fix it
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"capability": "capability:image-generation",
"capabilityVersion": "3.1.0",
"checkedAt": "2026-07-29T09:59:00Z",
"correlationId": "correlation:publish-42",
"dependencies": [
{
"dependency": "provider-api",
"detail": "rate limited at 10 rps",
"state": "degraded"
}
],
"envelopeId": "envelope:e1",
"extensions": {},
"freshnessSeconds": 300,
"kind": "capability-probe",
"limitations": ["throughput capped at 10 requests per second"],
"occurredAt": "2026-07-29T10:00:00Z",
"remediation": {
"action": "increase-quota",
"docsUrl": "https://docs.example.com/isis/quota",
"requiresOperator": true
},
"schemaVersion": 1,
"state": "degraded",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
probe/never-cache#
freshnessSeconds 0 means the answer must not be cached, which a nullable field could not say
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"capability": "capability:image-generation",
"capabilityVersion": "3.1.0",
"checkedAt": "2026-07-29T09:59:00Z",
"correlationId": "correlation:publish-42",
"dependencies": [
{
"dependency": "provider-api",
"detail": "credentials present, v3 supported",
"state": "configured"
}
],
"envelopeId": "envelope:e1",
"extensions": {},
"freshnessSeconds": 0,
"kind": "capability-probe",
"limitations": [],
"occurredAt": "2026-07-29T10:00:00Z",
"remediation": {
"action": "none",
"docsUrl": null,
"requiresOperator": false
},
"schemaVersion": 1,
"state": "configured",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
3 of 4 accepted case(s) shown. The full corpus is committed at
evidence/v1-workbenches/workbench-kit-envelope-goldens.json and is what the
gate runs.
Invalid examples#
probe/broken-with-no-remediation#
"broken, and there is nothing you can do" is almost never true and is never actionable
Must produce: invariant-violated
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"capability": "capability:image-generation",
"capabilityVersion": "3.1.0",
"checkedAt": "2026-07-29T09:59:00Z",
"correlationId": "correlation:publish-42",
"dependencies": [
{
"dependency": "provider-api",
"detail": "credentials present, v3 supported",
"state": "configured"
}
],
"envelopeId": "envelope:e1",
"extensions": {},
"freshnessSeconds": 300,
"kind": "capability-probe",
"limitations": ["provider unreachable"],
"occurredAt": "2026-07-29T10:00:00Z",
"remediation": {
"action": "none",
"docsUrl": null,
"requiresOperator": false
},
"schemaVersion": 1,
"state": "unavailable",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
probe/configured-but-offers-remediation#
if something needs fixing then the state is degraded, not configured
Must produce: invariant-violated
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"capability": "capability:image-generation",
"capabilityVersion": "3.1.0",
"checkedAt": "2026-07-29T09:59:00Z",
"correlationId": "correlation:publish-42",
"dependencies": [
{
"dependency": "provider-api",
"detail": "credentials present, v3 supported",
"state": "configured"
}
],
"envelopeId": "envelope:e1",
"extensions": {},
"freshnessSeconds": 300,
"kind": "capability-probe",
"limitations": [],
"occurredAt": "2026-07-29T10:00:00Z",
"remediation": {
"action": "increase-quota",
"docsUrl": "https://docs.example.com/q",
"requiresOperator": true
},
"schemaVersion": 1,
"state": "configured",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
probe/no-capability-version#
without it a cached answer cannot be told apart from a current one after a deploy
Must produce: missing-field
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"capability": "capability:image-generation",
"capabilityVersion": "",
"checkedAt": "2026-07-29T09:59:00Z",
"correlationId": "correlation:publish-42",
"dependencies": [
{
"dependency": "provider-api",
"detail": "credentials present, v3 supported",
"state": "configured"
}
],
"envelopeId": "envelope:e1",
"extensions": {},
"freshnessSeconds": 300,
"kind": "capability-probe",
"limitations": [],
"occurredAt": "2026-07-29T10:00:00Z",
"remediation": {
"action": "none",
"docsUrl": null,
"requiresOperator": false
},
"schemaVersion": 1,
"state": "configured",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
3 of 5 refused case(s) shown. The full corpus is committed at
evidence/v1-workbenches/workbench-kit-envelope-goldens.json and is what the
gate runs.
Authorization and scope#
| Symbol | Type | Notes |
|---|---|---|
commandAuthorizationMismatch |
function |
The privilege-confusion check the two-field split exists to make possible. |
CommandEnvelope.authorizationIntent |
string |
The grant the caller CLAIMS to need — an intent, not a verdict. |
EnvelopeCommon.actor |
ActorRef |
— |
EnvelopeCommon.tenant |
TenantId |
— |
Idempotency and concurrency#
| Symbol | Type | Notes |
| ---------------------------------- | ----------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| CommandEnvelope.expectedRevision | RevisionId | null | Null when creating; a revision when updating. Optimistic concurrency. |
| CommandEnvelope.idempotencyKey | string | — |
| dedupeKey | function | The key an at-least-once consumer deduplicates on. |
| EventEnvelope.causationId | EnvelopeId | null | The envelope that caused this one. Null for an externally-triggered event. |
| EventEnvelope.sequence | number | Monotonic per subject. What makes at-least-once delivery deduplicable. |
| JobUpdateEnvelope.attempt | number | 1-based. Attempt 0 would mean the job never ran, which is not an update. |
Pagination#
| Symbol | Type | Notes |
|---|---|---|
Pagination |
type |
— |
QueryEnvelope.pagination |
Pagination |
— |
QueryEnvelope.projection |
readonly string[] |
Field paths to return. Empty array means the resource's default shape. |
State and failure#
| Symbol | Type | Notes |
|---|---|---|
CAPABILITY_STATES |
enumeration |
The five states, named here and given their full record shape in S1.6. |
CapabilityProbeEnvelope.state |
CapabilityStateName |
— |
CapabilityStateName |
type |
— |
DependencyStatus.state |
CapabilityStateName |
— |
JobOutcome |
type |
— |
JobUpdateEnvelope.outcome |
JobOutcome |
— |
Compatibility#
| Symbol | Type | Notes |
|---|---|---|
CapabilityProbeEnvelope.capabilityVersion |
string |
The implementation version probed, so a stale answer is identifiable. |
CURRENT_SCHEMA_VERSION |
constant |
The schema this build writes and the oldest it reads. |
DeliveryCompatibility |
type |
— |
EnvelopeCommon.schemaVersion |
number |
— |
MIN_SUPPORTED_SCHEMA_VERSION |
constant |
— |
versionCompatibility |
function |
Whether this build may read an envelope written against schemaVersion. |
VersionCompatibility |
type |
— |
Deprecation#
Not applicable: nothing on this page can be deprecated on its own; the package version is its lifecycle.
Evidence#
evidence/v1-workbenches/workbench-kit-envelope-goldens.jsonevidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/envelopes.ts