Eve library

Schema and envelope

Evidence

Revision 1

On this page

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#

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

ts
(typeof CAPABILITY_STATES)[number];

commandAuthorizationMismatch#

The privilege-confusion check the two-field split exists to make possible.

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

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

ts
dedupeKey(event: EventEnvelope): string

DeliveryCompatibility#

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

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

ts
isExpired(command: CommandEnvelope, now: Instant): boolean

isProbeFresh#

Whether a probe answer may still be trusted at now.

ts
isProbeFresh(probe: CapabilityProbeEnvelope, now: Instant): boolean

isProgressRegression#

Whether next reports LESS progress than prev for the same job and attempt.

ts
isProgressRegression(prev: JobUpdateEnvelope, next: JobUpdateEnvelope): boolean

isTerminal#

ts
isTerminal(outcome: JobOutcome): boolean

JobOutcome#

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

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

ts
| { readonly mode: 'cursor'; readonly cursor: string | null; readonly pageSize: number }
| { readonly mode: 'offset'; readonly offset: number; readonly pageSize: number }

parseCapabilityProbeEnvelope#

ts
parseCapabilityProbeEnvelope(input: unknown): ParseResult<CapabilityProbeEnvelope>

parseCommandEnvelope#

ts
parseCommandEnvelope(input: unknown): ParseResult<CommandEnvelope>

parseEnvelope#

Dispatch on kind without the caller having to know the five parsers.

ts
parseEnvelope(input: unknown): ParseResult<AnyEnvelope>

parseEnvelopeJson#

Parse from the wire, where oversized actually arrives.

ts
parseEnvelopeJson(text: string): ParseResult<AnyEnvelope>

parseEventEnvelope#

ts
parseEventEnvelope(input: unknown): ParseResult<EventEnvelope>

parseExtensions#

ts
parseExtensions(input: unknown): ParseResult<{ readonly [key: string]: JsonValue }>

parseJobUpdateEnvelope#

ts
parseJobUpdateEnvelope(input: unknown): ParseResult<JobUpdateEnvelope>

parseQueryEnvelope#

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

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

ts
utf8ByteLength(text: string): number

versionCompatibility#

Whether this build may read an envelope written against schemaVersion.

ts
versionCompatibility(schemaVersion: number, parses: boolean): VersionCompatibility

VersionCompatibility#

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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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.json
  • evidence/v1-workbenches/workbench-kit-export-map.json
  • libs/oshun/workbench-kit/src/envelopes.ts