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 | interface | — |
| Consistency | type | — |
| MAX_PAGE_SIZE | constant | — |
| Pagination | type | — |
| QueryEnvelope | interface | — |
Shapes#
CommandEnvelope#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
'command' |
required | — |
operation |
string |
required | — |
subject |
EntityId | required | — |
idempotencyKey |
string |
required | — |
expectedRevision |
RevisionId | null — RevisionId |
required | Null when creating; a revision when updating. Optimistic concurrency. |
deadline |
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#
| { readonly level: 'strong' }
| { readonly level: 'bounded-staleness'; readonly maxStalenessSeconds: number }
| { readonly level: 'eventual' }
MAX_PAGE_SIZE#
Value: 200
Pagination#
| { 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 |
required | Field path -> matcher. Typed by the resource, opaque to the kit. |
pagination |
Pagination | required | — |
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
{
"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
{
"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"
{
"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
{
"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
{
"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
{
"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.jsonevidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/envelopes.ts