Eve library

Command and query

Evidence

Revision 1

On this page

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#

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

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