Eve library

Event and job

Evidence

Revision 1

On this page

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#

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

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 —

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

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

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

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

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

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

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