# AGENTS.md — @openstatus/services

Every workspace-scoped mutation lives here, not in a tRPC router or a Hono
handler. Routers validate input, call a verb, map errors.

One documented exception: the checker ingest path
(`apps/workflows/src/checker/transition.ts`) writes `monitor_status`,
`incident` and the outbox directly. `ServiceContext` requires a `Workspace` that
path would have to load on every check, `withTransaction` opens an interactive
transaction where it needs a single atomic `db.batch()`, and a fail-closed
`emitAudit` would roll back a real status transition because an audit insert
failed. Do not "fix" it by routing it through a verb.

## Shape of a verb

- **One file per verb** under `packages/services/src/<entity>/` (`create.ts`,
  `update.ts`, `remove.ts`), re-exported from that entity's `index.ts`. Callers
  import from `@openstatus/services/<entity>`.
- **Signature:** `async function verbEntity(args: { ctx: ServiceContext; input: VerbInput })`.
  `ctx` carries `workspace`, `actor`, and an optional `db`/transaction.
- **`requireScope(ctx, "write")` is the first line of every write verb** —
  before `Input.parse(...)`, before `withTransaction`.
- **`withTransaction(ctx, async (tx) => …)`** wraps every mutation; it reuses an
  outer transaction if one was threaded through `ctx`, otherwise opens one.
  Inside the block, write through `tx` — never `defaultDb`.
- **Every read and write filters by `ctx.workspace.id`.** Use the
  `getXInWorkspace` fetch-or-throw helpers in the entity's `internal.ts`.
- **Throw `ServiceError` subclasses** from `./errors`. Routers convert them with
  `toTRPCError`.

## Audit log

`emitAudit(tx, ctx, entry)` runs inside the same transaction as the mutation.
Fail-closed: a failed audit insert rolls the mutation back.

- Updates pass both `before` (pre-mutation snapshot) and `after` (the
  `.returning()` row); `changed_fields` is diffed automatically and no-op updates
  are skipped. Creates pass only `after`, deletes only `before`.
- **Strip secrets from snapshots** — credentials, bot tokens, raw API keys.
- Action names are `{entity}.{verb}`; new variants go in the discriminated union
  at `packages/db/src/schema/audit_logs/validation.ts`.

A missing `emitAudit` or `requireScope` is a defect, not a style nit. Both are
lint-enforced; if a verb genuinely needs neither, the inline disable must carry
a reason.

## Scope enforcement

API keys carry `read` / `write` scopes. "Write" means any DB mutation **or**
side-effecting external call (probe, webhook, notification); everything else is
read. `requireScope` is a no-op for `user` / `system` / `slack` / `webhook` /
`subscriber` actors and active for `apiKey` and `mcp`. MCP tools declare
`scope` and register through `registerScopedTool`, so read-only keys never see
write tools.

## Status-page visitor access

`src/page-access` decides whether an anonymous visitor may see a gated page
(password, email domain, IP range). It is pure — the transport builds a
`PageVisitor` — and the status-page proxy imports it, so keep it Edge-safe.
A verb reachable by visitors takes a `visitor` argument and calls
`assertPageAccess`; `null` is only for callers that already authorized the
request inside their own workspace.

## Runtime constraints

- **No `node:*` imports.** `apps/workflows` runs this code on Deno, and the
  package is written to stay Edge-safe so a Next.js route can adopt it without a
  rewrite — no Edge route imports it today. That is why `deepEqual` is
  hand-rolled rather than pulled from `node:util`.
- **No logtape here.** It breaks Edge builds; use `console.warn`.

## Query plans

Turso exposes neither `EXPLAIN` nor `ANALYZE`, and `sqlite_stat1` never exists
there. Verify a plan locally against `openstatus-dev.db` instead; in production
the only signal you get is `rows_read`.

## Tests

Suites live in `packages/services/src/<entity>/__tests__/`, mint their own
workspace, and assert the audit side-effect with `expectAuditRow(...)` from
`packages/services/test/helpers.ts`. Each entity also carries a
`'rejects read-only actor'` case built with `makeApiKeyCtx(...)`; `requireScope`
fires before any DB lookup, so fake ids are fine there.

**Audit rows outlive the entities they describe.** A suite that creates entities
through a service on the committed db and deletes them in cleanup must also call
`clearAuditLogFor(...)` — SQLite recycles `INTEGER PRIMARY KEY` ids after
deletes, so a later test's freshly-inserted entity can land on the orphan's id
and inherit its actor attribution. The failure surfaces in an unrelated suite,
which is what makes it expensive.

## Uptime weights

`impactUptimeWeight` in `packages/db/src/schema/page_components/constants.ts`
is pinned by tests: `major_outage` = 1, `partial_outage` = 0.5,
`degraded_performance` = 0. These numbers have been changed and reverted before —
confirm with a maintainer before touching them.