# Command and query

The two envelopes a caller sends. Shared fields are on the schema page.

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 |
| ----------------------------------- | --------- | ------- |
| [CommandEnvelope](#commandenvelope) | interface | —       |
| [Consistency](#consistency)         | type      | —       |
| [MAX_PAGE_SIZE](#max_page_size)     | constant  | —       |
| [Pagination](#pagination)           | type      | —       |
| [QueryEnvelope](#queryenvelope)     | interface | —       |

## Shapes

#### 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' }
```

#### MAX_PAGE_SIZE

Value: `200`

#### Pagination

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

#### QueryEnvelope

| Field         | Type                                                                           | Required | Notes                                                                  |
| ------------- | ------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------- |
| `kind`        | `'query'`                                                                      | required | —                                                                      |
| `resource`    | `string`                                                                       | required | —                                                                      |
| `filters`     | `{ readonly [field: string]: JsonValue }` — [JsonValue](./schema.md#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 | —                                                                      |

## Valid examples

##### command/create-has-null-expected-revision

a create has no revision to expect, and null says so where undefined would not

```json
{
  "actor": {
    "actorId": "actor:u1",
    "kind": "human",
    "tenant": "tenant:acme"
  },
  "authorizationIntent": "workbench:publish",
  "correlationId": "correlation:publish-42",
  "deadline": "2026-07-29T10:00:30Z",
  "envelopeId": "envelope:e1",
  "expectedRevision": null,
  "extensions": {},
  "idempotencyKey": "idem-1",
  "kind": "command",
  "occurredAt": "2026-07-29T10:00:00Z",
  "operation": "run.publish",
  "payload": {
    "note": "ship it"
  },
  "schemaVersion": 1,
  "subject": "entity:run-9",
  "tenant": "tenant:acme",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "workbench": "workbench:isis-generation"
}
```

##### command/minimal-accepted

the canonical shape every other command case is a mutation of

```json
{
  "actor": {
    "actorId": "actor:u1",
    "kind": "human",
    "tenant": "tenant:acme"
  },
  "authorizationIntent": "workbench:publish",
  "correlationId": "correlation:publish-42",
  "deadline": "2026-07-29T10:00:30Z",
  "envelopeId": "envelope:e1",
  "expectedRevision": "revision:r2",
  "extensions": {},
  "idempotencyKey": "idem-1",
  "kind": "command",
  "occurredAt": "2026-07-29T10:00:00Z",
  "operation": "run.publish",
  "payload": {
    "note": "ship it"
  },
  "schemaVersion": 1,
  "subject": "entity:run-9",
  "tenant": "tenant:acme",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "workbench": "workbench:isis-generation"
}
```

##### command/namespaced-extension

the one open field, namespaced so two domains cannot collide on "status"

```json
{
  "actor": {
    "actorId": "actor:u1",
    "kind": "human",
    "tenant": "tenant:acme"
  },
  "authorizationIntent": "workbench:publish",
  "correlationId": "correlation:publish-42",
  "deadline": "2026-07-29T10:00:30Z",
  "envelopeId": "envelope:e1",
  "expectedRevision": "revision:r2",
  "extensions": {
    "isis.retryHint": "backoff"
  },
  "idempotencyKey": "idem-1",
  "kind": "command",
  "occurredAt": "2026-07-29T10:00:00Z",
  "operation": "run.publish",
  "payload": {
    "note": "ship it"
  },
  "schemaVersion": 1,
  "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

##### command/actor-carries-display-data

an email as identity turns the audit row this command produces into a guess

Must produce: `display-data-in-identity`

```json
{
  "actor": {
    "actorId": "actor:u1",
    "email": "u1@example.com",
    "kind": "human",
    "tenant": "tenant:acme"
  },
  "authorizationIntent": "workbench:publish",
  "correlationId": "correlation:publish-42",
  "deadline": "2026-07-29T10:00:30Z",
  "envelopeId": "envelope:e1",
  "expectedRevision": "revision:r2",
  "extensions": {},
  "idempotencyKey": "idem-1",
  "kind": "command",
  "occurredAt": "2026-07-29T10:00:00Z",
  "operation": "run.publish",
  "payload": {
    "note": "ship it"
  },
  "schemaVersion": 1,
  "subject": "entity:run-9",
  "tenant": "tenant:acme",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "workbench": "workbench:isis-generation"
}
```

##### command/deadline-before-occurred-at

a command that expired before it was created is a clock fault; treating it as a
timeout hides the fault

Must produce: `invariant-violated`

```json
{
  "actor": {
    "actorId": "actor:u1",
    "kind": "human",
    "tenant": "tenant:acme"
  },
  "authorizationIntent": "workbench:publish",
  "correlationId": "correlation:publish-42",
  "deadline": "2026-07-29T09:59:59Z",
  "envelopeId": "envelope:e1",
  "expectedRevision": "revision:r2",
  "extensions": {},
  "idempotencyKey": "idem-1",
  "kind": "command",
  "occurredAt": "2026-07-29T10:00:00Z",
  "operation": "run.publish",
  "payload": {
    "note": "ship it"
  },
  "schemaVersion": 1,
  "subject": "entity:run-9",
  "tenant": "tenant:acme",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "workbench": "workbench:isis-generation"
}
```

##### command/expected-revision-undefined

undefined cannot distinguish a create from a caller that forgot the field, and
the difference is a lost update

Must produce: `missing-field`

```json
{
  "actor": {
    "actorId": "actor:u1",
    "kind": "human",
    "tenant": "tenant:acme"
  },
  "authorizationIntent": "workbench:publish",
  "correlationId": "correlation:publish-42",
  "deadline": "2026-07-29T10:00:30Z",
  "envelopeId": "envelope:e1",
  "extensions": {},
  "idempotencyKey": "idem-1",
  "kind": "command",
  "occurredAt": "2026-07-29T10:00:00Z",
  "operation": "run.publish",
  "payload": {
    "note": "ship it"
  },
  "schemaVersion": 1,
  "subject": "entity:run-9",
  "tenant": "tenant:acme",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "workbench": "workbench:isis-generation"
}
```

3 of 16 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                                                           |
| ------------------------------------- | -------- | --------------------------------------------------------------- |
| `CommandEnvelope.authorizationIntent` | `string` | The grant the caller CLAIMS to need — an intent, not a verdict. |

## Idempotency and concurrency

| Symbol                             | Type        | Notes |
| ---------------------------------- | ----------- | ----- | --------------------------------------------------------------------- |
| `CommandEnvelope.expectedRevision` | `RevisionId | null` | Null when creating; a revision when updating. Optimistic concurrency. |
| `CommandEnvelope.idempotencyKey`   | `string`    | —     |

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

Not applicable: nothing on this page has a failure mode of its own.

## Compatibility

Not applicable: nothing on this page is versioned independently of the package.

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