# Schema and envelope

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](#anyenvelope)                                   | type        | —                                                                              |
| [CAPABILITY_STATES](#capability_states)                       | enumeration | The five states, named here and given their full record shape in S1.6.         |
| [CapabilityProbeEnvelope](#capabilityprobeenvelope)           | interface   | —                                                                              |
| [CapabilityStateName](#capabilitystatename)                   | type        | —                                                                              |
| [commandAuthorizationMismatch](#commandauthorizationmismatch) | function    | The privilege-confusion check the two-field split exists to make possible.     |
| [CommandEnvelope](#commandenvelope)                           | interface   | —                                                                              |
| [Consistency](#consistency)                                   | type        | —                                                                              |
| [Cost](#cost)                                                 | interface   | Money as integer minor units.                                                  |
| [CURRENT_SCHEMA_VERSION](#current_schema_version)             | constant    | The schema this build writes and the oldest it reads.                          |
| [dedupeKey](#dedupekey)                                       | function    | The key an at-least-once consumer deduplicates on.                             |
| [DeliveryCompatibility](#deliverycompatibility)               | type        | —                                                                              |
| [DependencyStatus](#dependencystatus)                         | interface   | —                                                                              |
| [ENVELOPE_KINDS](#envelope_kinds)                             | enumeration | —                                                                              |
| [EnvelopeCommon](#envelopecommon)                             | interface   | —                                                                              |
| [EnvelopeKind](#envelopekind)                                 | type        | —                                                                              |
| [EventEnvelope](#eventenvelope)                               | interface   | —                                                                              |
| [isExpired](#isexpired)                                       | function    | Whether a command may still be applied at `now`.                               |
| [isProbeFresh](#isprobefresh)                                 | function    | Whether a probe answer may still be trusted at `now`.                          |
| [isProgressRegression](#isprogressregression)                 | function    | Whether `next` reports LESS progress than `prev` for the same job and attempt. |
| [isTerminal](#isterminal)                                     | function    | —                                                                              |
| [JobOutcome](#joboutcome)                                     | type        | —                                                                              |
| [JobUpdateEnvelope](#jobupdateenvelope)                       | interface   | —                                                                              |
| [JsonValue](#jsonvalue)                                       | type        | —                                                                              |
| [MAX_ENVELOPE_BYTES](#max_envelope_bytes)                     | constant    | 256 KiB, measured on the serialized bytes.                                     |
| [MAX_PAGE_SIZE](#max_page_size)                               | constant    | —                                                                              |
| [MIN_SUPPORTED_SCHEMA_VERSION](#min_supported_schema_version) | constant    | —                                                                              |
| [Pagination](#pagination)                                     | type        | —                                                                              |
| [parseCapabilityProbeEnvelope](#parsecapabilityprobeenvelope) | function    | —                                                                              |
| [parseCommandEnvelope](#parsecommandenvelope)                 | function    | —                                                                              |
| [parseEnvelope](#parseenvelope)                               | function    | Dispatch on `kind` without the caller having to know the five parsers.         |
| [parseEnvelopeJson](#parseenvelopejson)                       | function    | Parse from the wire, where oversized actually arrives.                         |
| [parseEventEnvelope](#parseeventenvelope)                     | function    | —                                                                              |
| [parseExtensions](#parseextensions)                           | function    | —                                                                              |
| [parseJobUpdateEnvelope](#parsejobupdateenvelope)             | function    | —                                                                              |
| [parseQueryEnvelope](#parsequeryenvelope)                     | function    | —                                                                              |
| [QueryEnvelope](#queryenvelope)                               | interface   | —                                                                              |
| [Remediation](#remediation)                                   | interface   | —                                                                              |
| [REMEDIATION_ACTIONS](#remediation_actions)                   | enumeration | Remediation, as a STRUCTURE rather than free text.                             |
| [RemediationAction](#remediationaction)                       | type        | —                                                                              |
| [Usage](#usage)                                               | interface   | —                                                                              |
| [utf8ByteLength](#utf8bytelength)                             | function    | UTF-8 byte length, computed rather than delegated to `TextEncoder`.            |
| [versionCompatibility](#versioncompatibility)                 | function    | Whether this build may read an envelope written against `schemaVersion`.       |
| [VersionCompatibility](#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](./identity.md#capabilityid)                            | required | —                                                                     |
| `capabilityVersion` | `string`                                                              | required | The implementation version probed, so a stale answer is identifiable. |
| `state`             | [CapabilityStateName](#capabilitystatename)                           | required | —                                                                     |
| `dependencies`      | `readonly DependencyStatus[]` — [DependencyStatus](#dependencystatus) | required | —                                                                     |
| `checkedAt`         | [Instant](./identity.md#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](#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](./identity.md#entityid)                            | required | —                                                                          |
| `idempotencyKey`      | `string`                                                      | required | —                                                                          |
| `expectedRevision`    | `RevisionId \| null` — [RevisionId](./identity.md#revisionid) | required | Null when creating; a revision when updating. Optimistic concurrency.      |
| `deadline`            | [Instant](./identity.md#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](#capabilitystatename) | required | —     |
| `detail`     | `string`                                    | required | —     |

#### ENVELOPE_KINDS

Values: `command`, `query`, `event`, `job-update`, `capability-probe`

#### EnvelopeCommon

| Field           | Type                                                              | Required | Notes                                                                      |
| --------------- | ----------------------------------------------------------------- | -------- | -------------------------------------------------------------------------- |
| `envelopeId`    | [EnvelopeId](./identity.md#envelopeid)                            | required | —                                                                          |
| `kind`          | [EnvelopeKind](#envelopekind)                                     | required | —                                                                          |
| `schemaVersion` | `number`                                                          | required | —                                                                          |
| `occurredAt`    | [Instant](./identity.md#instant)                                  | required | —                                                                          |
| `tenant`        | [TenantId](./identity.md#tenantid)                                | required | —                                                                          |
| `workbench`     | [WorkbenchId](./identity.md#workbenchid)                          | required | —                                                                          |
| `actor`         | [ActorRef](./identity.md#actorref)                                | required | —                                                                          |
| `correlationId` | [CorrelationId](./identity.md#correlationid)                      | required | —                                                                          |
| `traceId`       | `string \| null`                                                  | required | Null when tracing is off. Never a substitute for `correlationId`.          |
| `extensions`    | `{ readonly [key: string]: JsonValue }` — [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](./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 | —                                                                          |

#### 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](./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 | —                                                                         |

#### 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](#jsonvalue) | required | Field path -> matcher. Typed by the resource, opaque to the kit.       |
| `pagination`  | [Pagination](#pagination)                                           | required | —                                                                      |
| `consistency` | [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](#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](#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`
