# AGENTS.md: Temporal workflows

## Commands
- Local server: `temporal server start-dev` (UI at http://localhost:8233)
- Run worker: see `package.json`/`Makefile` (e.g. `npm run worker`, `go run ./worker`, `python -m app.worker`)
- Tests: the SDK's test environment (time-skipping) via the normal test command.
- Inspect: `temporal workflow list`, `temporal workflow show --workflow-id <id>`.

## Code map
`workflows/` (orchestration only) · `activities/` (all I/O) · `worker` entrypoint registering both on a named task queue · `client` code that starts workflows.

## Workflow rules (determinism)
- Workflow code must be deterministic: no network, DB, file I/O, random numbers, system time, threads or non-deterministic iteration. Use SDK APIs instead (`workflow.now()`, `workflow.sleep()`, SDK random/UUID helpers).
- All side effects happen in activities. Workflows only orchestrate: call activities, child workflows, timers, signals, queries and updates.
- Changing workflow code that already has running executions needs versioning (`patched`/`GetVersion`/Worker Versioning). Never reorder or remove activity calls without it.
- Keep workflow inputs and history small: pass IDs, not large payloads; use `continueAsNew` for long-running or looping workflows.
- Use stable, business-meaningful workflow IDs to get deduplication.

## Activity rules
- Activities are idempotent (safe to retry): use idempotency keys or upserts.
- Always set `startToCloseTimeout` (and `heartbeatTimeout` + heartbeats for long activities); configure `RetryPolicy` with backoff and mark permanent failures non-retryable.
- No business secrets in workflow inputs or results; payloads are stored in history (use a codec for encryption if needed).

## Tests
Unit-test activities directly; test workflows with the SDK test environment and mocked activities; add a replay test against saved histories when changing workflow code.

## Done
Tests and replay tests pass and the worker starts against the dev server.