The two envelopes a producer emits. An event has consumers it cannot enumerate; a job has one worker fleet.
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#
- view over
src/envelopes.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/envelopes |
contract |
S1.5 |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| Cost | interface | Money as integer minor units. |
| DeliveryCompatibility | type | — |
| EventEnvelope | interface | — |
| JobOutcome | type | — |
| JobUpdateEnvelope | interface | — |
| Usage | interface | — |
Shapes#
Cost#
Money as integer minor units.
| Field | Type | Required | Notes |
|---|---|---|---|
currency |
string |
required | — |
amountMinor |
number |
required | — |
DeliveryCompatibility#
'at-least-once' | 'exactly-once-per-subject';
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 | — |
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 | — |
Usage#
| Field | Type | Required | Notes |
|---|---|---|---|
unit |
string |
required | — |
quantity |
number |
required | — |
cost |
Cost | null — Cost |
required | — |
Valid examples#
event/accepted#
the canonical event, with the sequence that makes at-least-once delivery deduplicable
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"causationId": "envelope:e0",
"correlationId": "correlation:publish-42",
"delivery": "at-least-once",
"envelopeId": "envelope:e1",
"eventType": "run.published",
"extensions": {},
"kind": "event",
"occurredAt": "2026-07-29T10:00:00Z",
"payload": {
"revision": "revision:r3"
},
"producer": "isis-run-worker",
"schemaVersion": 1,
"sequence": 7,
"subject": "entity:run-9",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
event/exactly-once-delivery#
the field exists so a consumer knows whether it must deduplicate rather than assuming and being wrong once
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"causationId": "envelope:e0",
"correlationId": "correlation:publish-42",
"delivery": "exactly-once-per-subject",
"envelopeId": "envelope:e1",
"eventType": "run.published",
"extensions": {},
"kind": "event",
"occurredAt": "2026-07-29T10:00:00Z",
"payload": {
"revision": "revision:r3"
},
"producer": "isis-run-worker",
"schemaVersion": 1,
"sequence": 7,
"subject": "entity:run-9",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
event/externally-triggered-has-null-causation#
null says "nothing in this system caused it" where undefined would mean "we lost the chain"
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"causationId": null,
"correlationId": "correlation:publish-42",
"delivery": "at-least-once",
"envelopeId": "envelope:e1",
"eventType": "run.published",
"extensions": {},
"kind": "event",
"occurredAt": "2026-07-29T10:00:00Z",
"payload": {
"revision": "revision:r3"
},
"producer": "isis-run-worker",
"schemaVersion": 1,
"sequence": 7,
"subject": "entity:run-9",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
3 of 9 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#
event/negative-sequence#
a negative sequence breaks the ordering the dedupe key depends on
Must produce: invalid-field
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"causationId": "envelope:e0",
"correlationId": "correlation:publish-42",
"delivery": "at-least-once",
"envelopeId": "envelope:e1",
"eventType": "run.published",
"extensions": {},
"kind": "event",
"occurredAt": "2026-07-29T10:00:00Z",
"payload": {
"revision": "revision:r3"
},
"producer": "isis-run-worker",
"schemaVersion": 1,
"sequence": -1,
"subject": "entity:run-9",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
event/producer-missing#
the actor is not the producer: a retry by a different component has the same actor
Must produce: missing-field
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"causationId": "envelope:e0",
"correlationId": "correlation:publish-42",
"delivery": "at-least-once",
"envelopeId": "envelope:e1",
"eventType": "run.published",
"extensions": {},
"kind": "event",
"occurredAt": "2026-07-29T10:00:00Z",
"payload": {
"revision": "revision:r3"
},
"producer": "",
"schemaVersion": 1,
"sequence": 7,
"subject": "entity:run-9",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
event/self-causation#
a causation walk over an event that caused itself would not terminate
Must produce: invariant-violated
{
"actor": {
"actorId": "actor:u1",
"kind": "human",
"tenant": "tenant:acme"
},
"causationId": "envelope:e1",
"correlationId": "correlation:publish-42",
"delivery": "at-least-once",
"envelopeId": "envelope:e1",
"eventType": "run.published",
"extensions": {},
"kind": "event",
"occurredAt": "2026-07-29T10:00:00Z",
"payload": {
"revision": "revision:r3"
},
"producer": "isis-run-worker",
"schemaVersion": 1,
"sequence": 7,
"subject": "entity:run-9",
"tenant": "tenant:acme",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"workbench": "workbench:isis-generation"
}
3 of 11 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#
Not applicable: nothing on this page carries an actor, a grant, a scope or a tenant, so authorization is decided entirely by the caller.
Idempotency and concurrency#
| Symbol | Type | Notes |
| --------------------------- | ----------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| 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#
Not applicable: nothing on this page returns a collection a caller reads in pages.
State and failure#
| Symbol | Type | Notes |
|---|---|---|
JobOutcome |
type |
— |
JobUpdateEnvelope.outcome |
JobOutcome |
— |
Compatibility#
| Symbol | Type | Notes |
|---|---|---|
DeliveryCompatibility |
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