# Event and job

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](#cost)                                   | interface | Money as integer minor units. |
| [DeliveryCompatibility](#deliverycompatibility) | type      | —                             |
| [EventEnvelope](#eventenvelope)                 | interface | —                             |
| [JobOutcome](#joboutcome)                       | type      | —                             |
| [JobUpdateEnvelope](#jobupdateenvelope)         | interface | —                             |
| [Usage](#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](./identity.md#entityid)                            | required | —                                                                          |
| `sequence`    | `number`                                                      | required | Monotonic per subject. What makes at-least-once delivery deduplicable.     |
| `causationId` | `EnvelopeId \| null` — [EnvelopeId](./identity.md#envelopeid) | required | The envelope that caused this one. Null for an externally-triggered event. |
| `delivery`    | [DeliveryCompatibility](#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](./identity.md#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](#usage) | required | —                                                                         |
| `outcome`    | [JobOutcome](#joboutcome)         | required | —                                                                         |

#### Usage

| Field      | Type                           | Required | Notes |
| ---------- | ------------------------------ | -------- | ----- |
| `unit`     | `string`                       | required | —     |
| `quantity` | `number`                       | required | —     |
| `cost`     | `Cost \| null` — [Cost](#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`
