HTTP and events

One endpoint per operation, authentication by default, verbs by idempotency, cursor lists, prefixed ids, idempotency keys and versioned events.

Stackra has no HTTP service yet. Encore is the generated runtime target (0091, 0124); services hold no Encore files. The examples use Encore’s api() because that is the chosen shape. The rules hold for any framework.

HTTP

Rule	Detail
One action per operation	Every operation is one action (@Action or @Query) with typed input and output classes, exposed by an adapter such as @AsEndpoint; stackra gen emits the api() (0098, 0091). No any, no Record<string, unknown> at a boundary.
Authenticated by default	auth: true, set from the action’s auth option and its API area (0082); the gateway enforces it (0237). An exposed endpoint without auth is a public surface and carries a comment saying why. Webhooks use a raw endpoint with signature verification.
Error envelope	Errors use the envelope and the kinds of 0140.
Verbs follow idempotency	POST creates (a second call creates again). PUT is an idempotent state transition (/archive, /activate). PATCH is a partial update. DELETE only where a row is truly removed. Archive instead.
Cursor lists	cursor and limit (at most 100). Sorting and filtering use explicit allow-lists. Never pass column names through.
Prefixed public ids	Ids at the boundary look like tea_01JQ…. The handler rejects a mismatched prefix before any query. Internal UUIDs never appear in URLs or responses. The PublicId type and the prefix registry live in @stackra/contracts (0117).
Typed errors	Throw invalidArgument, notFound, permissionDenied or failedPrecondition with a stable message. Never a bare Error. A cross-tenant miss is notFound.
Idempotency keys	Every write carries an Idempotency-Key header. The service dedupes for 24 hours per tenant. Money-like writes keep their own durable idempotency table and run in one transaction with an audit event.
Validation	Boundary validation comes from @stackra/validation decorators on the input class, compiled to one Zod schema; Zod is the only validation engine (0095). Business invariants live in the service layer, not the handler.
Streaming	Use streaming endpoints for realtime. Fan out through pub/sub, because a socket only knows its own instance.
Generated client	Frontends consume a generated client. It is regenerated, never hand-edited.

What gen emits for one @Query action (illustrative; never hand-written in a service):

export const list = api(
  { expose: true, auth: true, method: "GET", path: "/teams" },
  async (req: ListTeamsRequest): Promise<ListTeamsResponse> => {
    const limit = Math.min(req.limit ?? 50, 100);
    // read the principal from request context, never from req
    return teams.list({ ...req, limit });
  },
);

Enforcement: partial. The validator checks the service-unit files. Planned: a stackra gen check that every endpoint is one action, a rule file .agents/rules/http-conventions.md scoped to services/**, and a generated-client drift check (gen:client:check) in pnpm verify.

Events

Events are facts, not commands. A service publishes one when it needs another to react and does not need an answer now.

Rule	Detail
Event first	Cross-service communication is a versioned event unless the caller needs an authoritative decision immediately. Then a typed client call, and only on the allowed list in the service standard.
Event names	Integration event names are prefixed by the module key: <module-key>.<aggregate>.<verb>.v<n>, for example identity.user.created.v1 (0141, 0231). Integration events cross a service boundary and are versioned by name (0078). Domain events stay in-process and are not versioned.
Versioning	A breaking payload change bumps the version. The old topic stays alive for the compatibility window named in an ADR.
Delivery	Producers write through a transactional outbox. Consumers are idempotent: an inbox keyed by event id.
Subscribing	A subscriber declares @OnEvent on the event name and imports only the producer’s ./contracts shape. It never imports another service’s Topic or source; stackra gen emits the Topic and Subscription (0078, 0091).

Envelope, defined once as EventEnvelope in @stackra/contracts. The actor is the action pipeline’s Actor with its full onBehalfOf chain (0098):

{
  "id": "evt_01J…",
  "type": "ticket.validated.v1",
  "version": 1,
  "occurredAt": "2026-10-03T10:00:00Z",
  "source": "<service>",
  "tenantId": "…",
  "scopePath": "root.branch1",
  "actor": {
    "type": "user | service | agent | external-agent | job | webhook | system | anonymous",
    "id": "…",
    "via": "http | mcp | a2a | cli | queue | cron | event | ui",
    "onBehalfOf": { "type": "user", "id": "…" }
  },
  "correlationId": "…",
  "causationId": "…",
  "aggregate": { "type": "ticket", "id": "tkt_01J…", "version": 7 },
  "classification": "internal | confidential | pii",
  "data": {}
}

Enforcement: planned. A schema check of the envelope in the contracts package, plus contract tests per topic, when the first event exists.

History

• 2026-10-20, 0125: operations are actions (0098); validation is @stackra/validation on Zod (0095); integration event names and subscriptions follow 0078 and 0091; the envelope actor is the 0098 actor model; contracts follow 0117.
• 2026-10-20, 0229: event names carry the module-key prefix (0141); the auth flag comes from the action’s API area (0082); errors follow 0140.